# Telegram Chip

> Unified Telegram core (HTTP API + MCP stdio + tgdl + sales hooks) with single-session Telethon architecture. Use when setting up Telegram automation, reading/sending Telegram messages via local API, exporting chat history, or troubleshooting Telethon auth/session conflicts.

- Skill: `qwwiwi/telegram-chip` (Agent Skill, multi-file: 22 files)
- Install (CLI): `npx skillmds@latest add qwwiwi/telegram-chip`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qwwiwi/telegram-chip/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: qwwiwi (https://skillmd.com/u/qwwiwi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qwwiwi/telegram-chip

---


# telegram-chip

Unified Telegram core with a single Telethon client and optional sales hooks.

## Correct authorization procedure (important)

Use this exact order:

1. Prepare `.env` with `TELEGRAM_API_ID` and `TELEGRAM_API_HASH`.
2. Run `./generate-session.sh` and complete interactive login:
   - phone number (`+7...`),
   - Telegram login code,
   - 2FA password (if enabled).
3. Verify `TELEGRAM_SESSION_STRING` is present in `.env`.
4. Start only one active Telethon process for this session string.

## Credential acquisition recommendations

When obtaining `TELEGRAM_API_ID` / `TELEGRAM_API_HASH` at `my.telegram.org/apps`:
- Prefer phone mobile internet (without Wi‑Fi/VPN), **or**
- Use a clean private/incognito browser session.

This reduces auth friction and weird web-session/cache issues.

## Hard rules

- Never share `TELEGRAM_SESSION_STRING` in chats/logs.
- If session leaks, revoke/regenerate immediately.
- One session string must not be used by multiple concurrent Telethon processes (prevents `AuthKeyDuplicatedError`).
- Use HTTP API (`api.py`) as the only integration point.
- Do not use direct Telethon imports outside this skill runtime (`skills/telegram-chip/.venv`).

## Reading polls

Anonymous multi-choice polls hide per-option vote counts from non-participants. Ask the session-owner human to vote manually in Telegram first, then `GET /chats/{chat_id}/messages/{message_id}` returns `poll.results[].voters`. See `README.md` → "Reading polls" for details.

## Read receipts (read_outbox_max_id)

To check if a peer has read a message you sent: `sent_message_id <= read_outbox_max_id` ⇒ read.

- `GET /chats/list` returns `read_outbox_max_id`, `read_inbox_max_id`, `top_message_id` per chat (alongside `unread_count`).
- `GET /chats/{chat_id}/read_status` — single-peer endpoint, lighter than `/chats/list` (uses `GetPeerDialogsRequest`).

`read_outbox_max_id == top_message_id` ⇒ peer прочитал всё.

See `README.md` → "Read receipts" for details.

See `README.md` and `TROUBLESHOOTING.md` for full setup and failure recovery.