Telegram

Telegram is the fastest channel to set up — no public URL, no OAuth, just a bot token from BotFather.

What You Get

Text, photo, voice message, and document support
Token-by-token response streaming (via message edits)
Typing indicator while the agent is working
Reply threading
Optional webhook mode with secret-token verification

1. Create the Bot

Open @BotFather in Telegram and run:

/newbot

Pick a display name and username (must end in bot). BotFather replies with an HTTP API token that looks like 123456789:AAH.... Keep it secret.

2. Store the Token

aibutler vault set telegram_bot_token 123456789:AAH...

3. Enable the Channel

Add telegram to the active channels list in config.yaml:

configurations:
  channels:
    active:
      - telegram

4. Restart

aibutler run

On startup you should see:

channel: telegram adapter registered

Message your bot on Telegram — it should reply within a second.

How It Works

AI Butler uses long polling by default (getUpdates), so no public URL is required — perfect for home servers behind NAT or firewalls. Updates are fetched every 30 seconds or on message arrival, whichever comes first.

Webhook Mode (Optional)

If you’re running behind a public HTTPS URL, you can switch to webhook mode for lower latency. Telegram’s webhook requires a secret token that AI Butler verifies on every request via the X-Telegram-Bot-Api-Secret-Token header:

aibutler vault set telegram_webhook_secret $(openssl rand -hex 32)

Then register the webhook with Telegram pointing at https://your-host/webhook/telegram.

Features

Feature	Supported
Text messages	Yes
Photos	Yes (largest size auto-selected)
Voice messages	Yes (OGG Opus, transcribed via STT)
Documents	Yes
Streaming replies	Yes (via `editMessageText`)
Typing indicator	Yes
Reply threading	Yes
Group chats	Yes
Inline mode	No

Troubleshooting

Bot doesn’t respond. Check that telegram_bot_token is set in the vault and that telegram is in the active channels list. Look for channel: telegram adapter registered in the logs on startup.

Getting 401 Unauthorized. The token is wrong or has been revoked. Create a new one with /revoke in BotFather.

Voice messages aren’t transcribed. Make sure a voice pipeline is configured — see AI Services for STT setup (Whisper, OpenAI, or self-hosted).