/guides/telegram-bot

Telegram bot

Deploy free-claude-code as a Telegram bot. Remote autonomous coding with session persistence and voice message support.

Telegram bot

Control Claude Code remotely from Telegram. Same features as Discord: tree-based threading, session persistence, live progress, and voice messages.

Prerequisites

You need:

1. A Telegram account
2. The Telegram mobile or desktop app
3. free-claude-code installed and running

Step 1: Create a Telegram bot

1. Message @BotFather on Telegram
2. Send /newbot
3. Follow prompts:
   • Enter a name for your bot (displayed to users)
   • Enter a username (must end in bot, e.g., claudecode_proxy_bot)
4. BotFather will give you a token like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
5. Save this token

Step 2: Get your user ID

1. Message @userinfobot
2. It will reply with your user ID (a number like 123456789)
3. Save this ID

This restricts the bot to respond only to you.

Step 3: Configure free-claude-code

Edit .env:

MESSAGING_PLATFORM="telegram"
TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
ALLOWED_TELEGRAM_USER_ID="123456789"

Replace with your actual token and user ID.

Configure the workspace:

CLAUDE_WORKSPACE="./agent_workspace"
ALLOWED_DIR="/home/yourname/projects"

Step 4: Start the server

uv run uvicorn server:app --host 0.0.0.0 --port 8082

The bot connects to Telegram and will respond to your messages.

Using the bot

Basic usage

Message your bot directly:

Create a React component that displays a sortable table with pagination

The bot streams thinking tokens (if enabled), executes tools, and returns the result.

Threading

Reply to any bot message to continue that conversation:

[Your original request]
  ↳ [Bot response]
    ↳ [Your reply: "Add column filtering too"]

In Telegram, this creates a message thread. Each branch is isolated from others.

Commands

Voice messages

Send a voice message in Telegram. The bot:

1. Downloads the .ogg audio
2. Transcribes using configured Whisper backend
3. Processes the text as a normal prompt

Configure voice transcription:

VOICE_NOTE_ENABLED=true
WHISPER_DEVICE="cpu"
WHISPER_MODEL="base"

Install voice extras:

uv sync --extra voice_local     # Local Whisper
uv sync --extra voice           # NVIDIA NIM voice

For NVIDIA NIM voice:

WHISPER_DEVICE="nvidia_nim"
WHISPER_MODEL="openai/whisper-large-v3"
NVIDIA_NIM_API_KEY="nvapi-your-key"

Differences from Discord

Telegram is simpler for personal use. Discord scales better for team collaboration.

Security

• Restrict to your user ID: ALLOWED_TELEGRAM_USER_ID ensures only you can interact with the bot
• Use a strong bot token: If compromised, regenerate via BotFather with /revoke
• Set allowed directories: ALLOWED_DIR limits filesystem access

Troubleshooting

Bot doesn’t respond: Check logs for connection errors. Verify the token is correct.

“User not allowed” errors: Your Telegram user ID changed or was mistyped. Re-check with @userinfobot.

Voice messages fail: Verify voice extras are installed. Check WHISPER_DEVICE is configured.

Sessions lost: Ensure CLAUDE_WORKSPACE is persistent. Check disk space.

Switching from Discord

To switch an existing installation from Discord to Telegram:

1. Stop the server
2. Change MESSAGING_PLATFORM="telegram"
3. Add TELEGRAM_BOT_TOKEN and ALLOWED_TELEGRAM_USER_ID
4. Remove or comment out Discord settings
5. Restart the server

The proxy handles one platform at a time. For both simultaneously, run separate instances on different ports.