Telegram Bot

anna includes a Telegram bot that runs via long polling -- no webhook or public IP needed.

Setup

1. Create a bot via @BotFather
2. Add the token to ~/.anna/config.yaml:

channels:
  telegram:
    token: "BOT_TOKEN"

Or via environment: ANNA_TELEGRAM_TOKEN=BOT_TOKEN

3. Start the gateway:

anna gateway

Streaming Responses

The bot streams LLM responses in real time with two strategies:

Private Chats: Draft API (Bot API 9.3+)

Uses sendMessageDraft for smooth animated streaming without rate-limiting issues. If the API is not available, automatically falls back to edit mode.

Group Chats: Edit-in-Place

Sends an initial message and edits it periodically (every ~1 second) as tokens arrive. The streaming message is deleted once complete, then the final response is sent.

Tool Indicators

During tool execution, the stream shows status with emoji indicators:

Image Support

The bot accepts photo messages in private chats. When you send an image:

1. The bot downloads the highest-resolution version from Telegram's file API
2. Detects the MIME type and base64-encodes the image
3. Sends it as a multimodal message (image + optional caption text) to the model
4. The model analyzes the image and responds with text

Use cases: describe screenshots, analyze diagrams, read documents from photos, etc.

If the model returns images (e.g. from tool results), they are sent back as Telegram photos after the text response.

Note: Image support requires a vision-capable model (e.g. Claude 3+, GPT-4o).

Group Support

Configure how the bot responds in group chats:

channels:
  telegram:
    group_mode: "mention"   # Only respond when @mentioned (default)
    # group_mode: "always"  # Respond to all messages
    # group_mode: "disabled" # Ignore group messages entirely

Access Control

Restrict which Telegram users can interact with the bot:

channels:
  telegram:
    allowed_ids:
      - 136345060           # Your Telegram user ID

Leave empty to allow all users. Use the /whoami command in Telegram to get your user ID.

Notifications

The bot doubles as a notification backend. Configure a default chat for proactive messages:

channels:
  telegram:
    notify_chat: "123456789"   # Chat ID (use /whoami to get it)
    channel_id: "@my_channel"  # Optional broadcast channel

Used by:

• The notify agent tool (in gateway mode)
• Cron job result broadcasting

See notification-system.md for the full notification architecture.

Model Switching

Users can switch models mid-conversation via an inline keyboard triggered by the /model command in Telegram. The model list is paginated with text filtering support.

Configuration Reference