claude-telegram-voice
Talk to Claude Code from your phone. Send voice messages in any language — they're transcribed automatically and forwarded to your session.
This is a fork of the official Telegram channel plugin with one addition: voice message transcription via OpenAI Whisper. Everything else works exactly like the original.
What it does
- Voice messages → automatically transcribed via OpenAI Whisper and forwarded as text. Supports 57+ languages with auto-detection.
- Text, photos, documents → forwarded to Claude Code as-is.
- Replies, reactions, file attachments → Claude can send all of these back to you on Telegram.
- Access control → pairing codes, allowlists, group support — same security model as the official plugin.
Voice transcription costs ~$0.006 per minute of audio.
Quick start
Prerequisites
- Claude Code v2.1.80+, logged in via claude.ai
- Bun runtime (
curl -fsSL https://bun.sh/install | bash)
- A Telegram bot token (free, from @BotFather)
- An OpenAI API key (for voice transcription — get one here)
1. Create a Telegram bot
Open Telegram, message @BotFather:
/newbot
Give it a name and username. Copy the token (looks like 123456789:AAHfiqksKZ8...).
2. Install the plugin
In Claude Code:
/plugin marketplace add BeinerChes/claude-telegram-voice
/plugin install telegram-voice@claude-telegram-voice
3. Configure
In Claude Code, save your bot token:
/telegram-voice:configure YOUR_BOT_TOKEN_HERE
Save your OpenAI API key (enables voice transcription):
/telegram-voice:configure openai sk-proj-YOUR_KEY_HERE
4. Start a session
claude --dangerously-load-development-channels plugin:telegram-voice@claude-telegram-voice
Note: The --dangerously-load-development-channels flag is required during the channels research preview. This is standard for all non-official channel plugins.
5. Pair your Telegram account
- DM your bot on Telegram — it replies with a 6-character code
- In Claude Code, run:
/telegram-voice:access pair <code>
- Done! Messages you send on Telegram now reach Claude.
6. Lock it down
Once paired, switch from pairing mode to allowlist so no one else can connect:
/telegram-voice:access policy allowlist
Usage
Once paired, just message your bot on Telegram:
| You send | Claude receives |
|---|
| Text message | The text, as-is |
| Voice message | [Voice]: <transcribed text> |
| Photo | The image (Claude can view it) |
| Document | File metadata (downloadable) |
| Sticker | Emoji representation |
Claude replies appear as bot messages in your Telegram chat.
Configuration files
All state lives in ~/.claude/channels/telegram/:
| File | Purpose |
|---|
.env | TELEGRAM_BOT_TOKEN and OPENAI_API_KEY |
access.json | Allowlist, pairing codes, group policies |
inbox/ | Downloaded photos and attachments |
Skills
| Command | What it does |
|---|
/telegram-voice:configure | Check status, save token, save OpenAI key |
/telegram-voice:configure <token> | Save bot token |
/telegram-voice:configure openai <key> | Save OpenAI API key |
/telegram-voice:access | View access policy and allowlist |
/telegram-voice:access pair <code> | Approve a pairing request |
/telegram-voice:access policy allowlist | Lock down to approved users only |
MCP tools (available to Claude)
| Tool | Description |
|---|
reply | Send text and file attachments back to Telegram |
react | Add emoji reactions to messages |
edit_message | Edit a previously sent bot message |
download_attachment | Download file attachments to local inbox |
How voice transcription works
- You send a voice message on Telegram
- The plugin downloads the
.ogg audio file
- Sends it to the OpenAI Whisper API for transcription
- Forwards the transcribed text to Claude as
[Voice]: your words here
- Cleans up the audio file
Whisper auto-detects the language — English, Russian, Spanish, Chinese, or any of the 57+ supported languages. No configuration needed.
If OPENAI_API_KEY is not set, voice messages arrive as (voice message) with no transcription. Everything else works normally.
Differences from the official plugin
Rich627
thedotmack
Lucklyric
anthropics