| name | telegram-chip |
| description | 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. |
| metadata | {"clawdbot":{"always":false}} |
telegram-chip
Unified Telegram core with a single Telethon client and optional sales hooks.
Correct authorization procedure (important)
Use this exact order:
- Prepare
.env with TELEGRAM_API_ID and TELEGRAM_API_HASH.
- Run
./generate-session.sh and complete interactive login:
- phone number (
+7...),
- Telegram login code,
- 2FA password (if enabled).
- Verify
TELEGRAM_SESSION_STRING is present in .env.
- 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.
