claude-telegram-voice

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

1. DM your bot on Telegram — it replies with a 6-character code
2. In Claude Code, run: /telegram-voice:access pair <code>
3. 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

1. You send a voice message on Telegram
2. The plugin downloads the .ogg audio file
3. Sends it to the OpenAI Whisper API for transcription
4. Forwards the transcribed text to Claude as [Voice]: your words here
5. 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