telegram-voice-stt
Telegram channel with automatic voice transcription via configurable STT endpoint
Open source Repository Open in the app JSON README (API)
About
Telegram channel with automatic voice transcription via configurable STT endpoint
Details
- Kind
- Plugins
- Topic
- Communication
- Publisher
- h34r7l3s
- Origin
- marketplace
- Category
- ferramentas
- Last push
- 2026-03-25T01:26:08Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
h34r7l3s/telegram-voice-stt/telegram-voice-stt
README
# Telegram
Connect a Telegram bot to your Claude Code with an MCP server.
The 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.
## Prerequisites
- [Bun](https://bun.sh) — the MCP server runs on Bun. Install with `curl -fsSL https://bun.sh/install | bash`.
## Quick Setup
> Default pairing flow for a single-user DM bot. See [ACCESS.md](./ACCESS.md) for groups and multi-user setups.
**1. Create a bot with BotFather.**
Open a chat with [@BotFather](https://t.me/BotFather) on Telegram and send `/newbot`. BotFather asks for two things:
- **Name** — the display name shown in chat headers (anything, can contain spaces)
- **Username** — a unique handle ending in `bot` (e.g. `my_assistant_bot`). This becomes your bot's link: `t.me/my_assistant_bot`.
BotFather replies with a token that looks like `123456789:AAHfiqksKZ8...` — that's the whole token, copy it including the leading number and colon.
**2. Install the plugin.**
These are Claude Code commands — run `claude` to start a session first.
Install the plugin:
```
/plugin install telegram@claude-plugins-official
```
**3. Give the server the token.**
```
/telegram:configure 123456789:AAHfiqksKZ8...
```
Writes `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.
> To run multiple bots on one machine (different tokens, separate allowlists), point `TELEGRAM_STATE_DIR` at a different directory per instance.
**4. Relaunch with the channel flag.**
The server won't connect without this — exit your session and start a new one:
```sh
claude --channels plugin:telegram@claude-plugins-official
```
**5. Pair.**
With 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:
```
/telegram:access pair <code>
```
Your next DM reaches the assistant.
> 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.
**6. Lock it down.**
Pairing 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.
## Access control
See **[ACCESS.md](./ACCESS.md)** for DM policies, groups, mention detection, delivery config, skill commands, and the `access.json` schema.
Quick 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.
## Tools exposed to the assistant
| Tool | Purpose |
| --- | --- |
| `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). |
| `react` | Add an emoji reaction to a message by ID. **Only Telegram's fixed whitelist** is accepted (👍 👎 ❤ 🔥 👀 etc). |
| `edit_message` | Edit a message the bot previously sent. Useful for "working…" → result progress updates. Only works on the bot's own messages. |
Inbound messages trigger a typing indicator automatically — Telegram shows
"botname is typing…" while the assistant works on a response.
## Photos
Inbound photos are downloaded to `~/.claude/channels/telegram/inbox/` and the
local path is included in the `<channel>` notification so the assistant can
`Read` it. Telegram compresses photos — if you need the original file, send it
as a document instead (long-press → Send as File).
## Voice transcription (optional)
Voice messages can be automatically transcribed to text using any
Whisper-compatible STT endpoint. Add to `~/.claude/channels/telegram/.env`:
```
TELEGRAM_STT_URL=http://localhost:8877/transcribe
```
When set, voice messages are downloaded, sent to the STT endpoint as a
multipart form upload, and the transcribed text is delivered as a regular
channel message prefixed with 🎤. The audio file is saved to the inbox
directory for audit.
The STT endpoint must accept a `file` field (audio blob) and return
`{"text": "transcribed content"}`. This is compatible with
[faster-whisper-server](https://github.com/fedirz/faster-whisper-server),
OpenAI's Whisper API, and similar services.
If `TELEGRAM_STT_URL` is not set, voice messages fall through to the
default attachment mode (file_id delivered for manual download via
`download_attachment`).
## Text-to-speech (optional)
Replies can be automatically converted to voice messages using any
Piper-compatible TTS endpoint. Add to `~/.claude/channels/telegram/.env`:
```
TELEGRAM_TTS_URL=http://localhost:8878/tts
```
When set, every text reply is also sent as a Telegram voice message.
The TTS endpoint must accept `POST` with plain text body and return
`audio/ogg` (Opus codec). This is compatible with
[Piper](https://github.com/rhasspy/piper) wrapped in a simple HTTP server.
`.ogg`/`.oga`/`.opus` files attached via the `files` parameter are
automatically sent as native Telegram voice messages (`sendVoice`)
instead of documents.
If `TELEGRAM_TTS_URL` is not set, replies are text-only (default behavior).
## No history or search
Telegram's Bot API exposes **neither** message history nor search. The bot
only sees messages as they arrive — no `fetch_messages` tool exists. If the
assistant needs earlier context, it will ask you to paste or summarize.
This also means there's no `download_attachment` tool for historical messages
— photos are downloaded eagerly on arrival since there's no way to fetch them
later.