{
  "markdown": "# Telegram\n\nConnect a Telegram bot to your Claude Code with an MCP server.\n\nThe MCP server logs into Telegram as a bot and provides tools to Claude to reply, react, or edit messages. When you message the bot, the server forwards the message to your Claude Code session.\n\n## Prerequisites\n\n- [Bun](https://bun.sh) — the MCP server runs on Bun. Install with `curl -fsSL https://bun.sh/install | bash`.\n\n## Quick Setup\n> Default pairing flow for a single-user DM bot. See [ACCESS.md](./ACCESS.md) for groups and multi-user setups.\n\n**1. Create a bot with BotFather.**\n\nOpen a chat with [@BotFather](https://t.me/BotFather) on Telegram and send `/newbot`. BotFather asks for two things:\n\n- **Name** — the display name shown in chat headers (anything, can contain spaces)\n- **Username** — a unique handle ending in `bot` (e.g. `my_assistant_bot`). This becomes your bot's link: `t.me/my_assistant_bot`.\n\nBotFather replies with a token that looks like `123456789:AAHfiqksKZ8...` — that's the whole token, copy it including the leading number and colon.\n\n**2. Install the plugin.**\n\nThese are Claude Code commands — run `claude` to start a session first.\n\nInstall the plugin:\n```\n/plugin install telegram@claude-plugins-official\n```\n\n**3. Give the server the token.**\n\n```\n/telegram:configure 123456789:AAHfiqksKZ8...\n```\n\nWrites `TELEGRAM_BOT_TOKEN=...` to `~/.claude/channels/telegram/.env`. You can also write that file by hand, or set the variable in your shell environment — shell takes precedence.\n\n> To run multiple bots on one machine (different tokens, separate allowlists), point `TELEGRAM_STATE_DIR` at a different directory per instance.\n\n**4. Relaunch with the channel flag.**\n\nThe server won't connect without this — exit your session and start a new one:\n\n```sh\nclaude --channels plugin:telegram@claude-plugins-official\n```\n\n**5. Pair.**\n\nWith Claude Code running from the previous step, DM your bot on Telegram — it replies with a 6-character pairing code. If the bot doesn't respond, make sure your session is running with `--channels`. In your Claude Code session:\n\n```\n/telegram:access pair <code>\n```\n\nYour next DM reaches the assistant.\n\n> Unlike Discord, there's no server invite step — Telegram bots accept DMs immediately. Pairing handles the user-ID lookup so you never touch numeric IDs.\n\n**6. Lock it down.**\n\nPairing is for capturing IDs. Once you're in, switch to `allowlist` so strangers don't get pairing-code replies. Ask Claude to do it, or `/telegram:access policy allowlist` directly.\n\n## Access control\n\nSee **[ACCESS.md](./ACCESS.md)** for DM policies, groups, mention detection, delivery config, skill commands, and the `access.json` schema.\n\nQuick reference: IDs are **numeric user IDs** (get yours from [@userinfobot](https://t.me/userinfobot)). Default policy is `pairing`. `ackReaction` only accepts Telegram's fixed emoji whitelist.\n\n## Tools exposed to the assistant\n\n| Tool | Purpose |\n| --- | --- |\n| `reply` | Send to a chat. Takes `chat_id` + `text`, optionally `reply_to` (message ID) for native threading and `files` (absolute paths) for attachments. Images (`.jpg`/`.png`/`.gif`/`.webp`) send as photos with inline preview; other types send as documents. Max 50MB each. Auto-chunks text; files send as separate messages after the text. Returns the sent message ID(s). |\n| `react` | Add an emoji reaction to a message by ID. **Only Telegram's fixed whitelist** is accepted (👍 👎 ❤ 🔥 👀 etc). |\n| `edit_message` | Edit a message the bot previously sent. Useful for \"working…\" → result progress updates. Only works on the bot's own messages. |\n\nInbound messages trigger a typing indicator automatically — Telegram shows\n\"botname is typing…\" while the assistant works on a response.\n\n## Photos\n\nInbound photos are downloaded to `~/.claude/channels/telegram/inbox/` and the\nlocal path is included in the `<channel>` notification so the assistant can\n`Read` it. Telegram compresses photos — if you need the original file, send it\nas a document instead (long-press → Send as File).\n\n## Voice transcription (optional)\n\nVoice messages can be automatically transcribed to text using any\nWhisper-compatible STT endpoint. Add to `~/.claude/channels/telegram/.env`:\n\n```\nTELEGRAM_STT_URL=http://localhost:8877/transcribe\n```\n\nWhen set, voice messages are downloaded, sent to the STT endpoint as a\nmultipart form upload, and the transcribed text is delivered as a regular\nchannel message prefixed with 🎤. The audio file is saved to the inbox\ndirectory for audit.\n\nThe STT endpoint must accept a `file` field (audio blob) and return\n`{\"text\": \"transcribed content\"}`. This is compatible with\n[faster-whisper-server](https://github.com/fedirz/faster-whisper-server),\nOpenAI's Whisper API, and similar services.\n\nIf `TELEGRAM_STT_URL` is not set, voice messages fall through to the\ndefault attachment mode (file_id delivered for manual download via\n`download_attachment`).\n\n## Text-to-speech (optional)\n\nReplies can be automatically converted to voice messages using any\nPiper-compatible TTS endpoint. Add to `~/.claude/channels/telegram/.env`:\n\n```\nTELEGRAM_TTS_URL=http://localhost:8878/tts\n```\n\nWhen set, every text reply is also sent as a Telegram voice message.\nThe TTS endpoint must accept `POST` with plain text body and return\n`audio/ogg` (Opus codec). This is compatible with\n[Piper](https://github.com/rhasspy/piper) wrapped in a simple HTTP server.\n\n`.ogg`/`.oga`/`.opus` files attached via the `files` parameter are\nautomatically sent as native Telegram voice messages (`sendVoice`)\ninstead of documents.\n\nIf `TELEGRAM_TTS_URL` is not set, replies are text-only (default behavior).\n\n## No history or search\n\nTelegram's Bot API exposes **neither** message history nor search. The bot\nonly sees messages as they arrive — no `fetch_messages` tool exists. If the\nassistant needs earlier context, it will ask you to paste or summarize.\n\nThis also means there's no `download_attachment` tool for historical messages\n— photos are downloaded eagerly on arrival since there's no way to fetch them\nlater.\n",
  "bytes": 6037,
  "sha": "2d4fe73ea7bb2ac1b8087f6db49fed3191890fadab51f692475825f173859e8d",
  "repo_slug": "h34r7l3s/telegram-voice-stt",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_h34r7l3s_telegram_voice_stt_telegram_voi_6fbb403c/readme"
}