|
| 1 | +# Telegram (Bot API) |
| 2 | + |
| 3 | +Updated: 2025-12-07 |
| 4 | + |
| 5 | +Status: ready for bot-mode use with grammY (long-poll + webhook). Text + media send, proxy, and webhook helpers all ship in-tree. |
| 6 | + |
| 7 | +## Goals |
| 8 | +- Let you talk to Clawdis via a Telegram bot in DMs and groups. |
| 9 | +- Share the same `main` session used by WhatsApp/WebChat; groups stay isolated as `group:<chatId>`. |
| 10 | +- Keep transport routing deterministic: replies always go back to the surface they arrived on. |
| 11 | + |
| 12 | +## How it will work (Bot API) |
| 13 | +1) Create a bot with @BotFather and grab the token. |
| 14 | +2) Configure Clawdis with `TELEGRAM_BOT_TOKEN` (or `telegram.botToken` in `~/.clawdis/clawdis.json`). |
| 15 | +3) Run the relay with provider `telegram` via `clawdis relay:telegram` (grammY long-poll). Webhook mode: `clawdis relay:telegram --webhook --port 8787 --webhook-secret <secret>` (optionally `--webhook-url` when the public URL differs). |
| 16 | +4) Direct chats: user sends the first message; all subsequent turns land in the shared `main` session (default, no extra config). |
| 17 | +5) Groups: add the bot, disable privacy mode (or make it admin) so it can read messages; group threads stay on `group:<chatId>` and require mention/command to trigger replies. |
| 18 | +6) Optional allowlist: reuse `inbound.allowFrom` for direct chats by chat id (`123456789` or `telegram:123456789`). |
| 19 | + |
| 20 | +## Capabilities & limits (Bot API) |
| 21 | +- Sees only messages sent after it’s added to a chat; no pre-history access. |
| 22 | +- Cannot DM users first; they must initiate. Channels are receive-only unless the bot is an admin poster. |
| 23 | +- File size caps follow Telegram Bot API (up to 2 GB for documents; smaller for some media types). |
| 24 | +- Typing indicators (`sendChatAction`) supported; inline reply/threading supported where Telegram allows. |
| 25 | + |
| 26 | +## Planned implementation details |
| 27 | +- Library: grammY is the only client for send + relay (fetch fallback removed). |
| 28 | +- Inbound normalization: maps Bot API updates to `MsgContext` with `Surface: "telegram"`, `ChatType: direct|group`, `SenderName`, `MediaPath`/`MediaType` when attachments arrive, and `Timestamp`; groups require @bot mention by default. |
| 29 | +- Outbound: text and media (photo/video/audio/document) with optional caption; chunked to limits. Typing cue sent best-effort. |
| 30 | +- Config: `TELEGRAM_BOT_TOKEN` env or `telegram.botToken` required; `telegram.requireMention`, `telegram.allowFrom`, `telegram.mediaMaxMb`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl` supported. |
| 31 | + |
| 32 | +Example config: |
| 33 | +```json5 |
| 34 | +{ |
| 35 | + telegram: { |
| 36 | + botToken: "123:abc", |
| 37 | + requireMention: true, |
| 38 | + allowFrom: ["123456789"], // direct chat ids allowed (or "*") |
| 39 | + mediaMaxMb: 5, |
| 40 | + proxy: "socks5://localhost:9050", |
| 41 | + webhookSecret: "mysecret", |
| 42 | + webhookUrl: "https://yourdomain.com/telegram-webhook" |
| 43 | + } |
| 44 | +} |
| 45 | +``` |
| 46 | +- Tests: grammY-based paths in `src/telegram/*.test.ts` cover DM + group gating; add more media and webhook cases as needed. |
| 47 | + |
| 48 | +## Group etiquette |
| 49 | +- Keep privacy mode off if you expect the bot to read all messages; with privacy on, it only sees commands/mentions. |
| 50 | +- Make the bot an admin if you need it to send in restricted groups or channels. |
| 51 | +- Mention the bot (`@yourbot`) or use commands to trigger; we’ll honor `group.requireMention` by default to avoid noise. |
| 52 | + |
| 53 | +## Roadmap |
| 54 | +- ✅ Design and defaults (this doc) |
| 55 | +- ✅ grammY long-poll relay + text/media send |
| 56 | +- ✅ Proxy + webhook helpers (setWebhook/deleteWebhook, health endpoint, optional public URL) |
| 57 | +- ⏳ Add more grammY coverage (webhook payloads, media edge cases) |
| 58 | + |
| 59 | +## Safety & ops |
| 60 | +- Treat the bot token as a secret (equivalent to account control); store under `~/.clawdis/credentials/` with 0600 perms. |
| 61 | +- Respect Telegram rate limits (429s); we’ll add throttling in the provider to stay below flood thresholds. |
| 62 | +- Use a test bot for development to avoid hitting production chats. |
0 commit comments