Telegram

The Telegram interface connects Aleph to the Telegram Bot API using the teloxide framework. It supports direct messages, group chats, file attachments, inline keyboards, Markdown formatting, forum topics, and tapback-style reactions.

Capabilities

Prerequisites

Configuration

Minimal Configuration

[[channels]]
id = "telegram"
channel_type = "telegram"
enabled = true

[channels.config]
bot_token = "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

Full Configuration Reference

[[channels]]
id = "telegram"
channel_type = "telegram"
enabled = true

[channels.config]
# Bot token from @BotFather (required); supports ${ENV_VAR} expansion
bot_token = "${TELEGRAM_BOT_TOKEN}"

# Bot username without @ (auto-detected on connect)
bot_username = "my_aleph_bot"

# DM policy for incoming messages: open | allowlist | pairing | disabled
dm_policy = "pairing"

# Group message policy: open | allowlist | disabled
group_policy = "open"

# Allowlist of phone numbers / user ids for DMs
allow_from = [123456789, 987654321]

# Allowlist for group chats
allowed_groups = [-1001234567890]

# Require @mention in group chats (default: true)
require_mention = true

# Bot's name for mention detection in groups
bot_name = "Aleph"

# Polling interval (default: 1)
polling_interval_secs = 1

# Send typing indicator while processing (default: true)
send_typing = true

# Maximum retries for failed messages (default: 3)
max_retries = 3

Environment Variable Mode

The simplest setup uses a single environment variable:

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

Adapter Structure

The Telegram interface is split across a small set of focused modules under src/gateway/interfaces/telegram/:

The adapter does not own pairing state. It forwards unknown senders to the inbound router, which is the single source for access / pairing / allowlist decisions (see Interfaces Overview).

Access, Pairing, and Allowlists — Single-Sourced on the Router

AccessController::check_message() returns one of three verdicts (src/gateway/interfaces/telegram/access.rs):

• Allowed — statically allowlisted, or DM policy is open / disabled trivially.
• NeedsPairing — DM policy is pairing and the sender is not yet known. The adapter hands the message to the router; the router owns pairing code minting, expiry, and approval (channel.pairing.list / approve / reject / revoke).
• Denied — silently dropped (group not allowed, DM policy disabled, etc.).

There is no per-channel pairing database anymore: 26.7.21 removed the channel-local pairing store. Pairing state lives in the gateway's PairingStore (SQLite-backed), and the operator resolves new pairings from the Panel via channel.pairing.approve / reject. The TelegramConfigV2 → ChannelConfig bridge feeds the router every DM/group/allowlist rule, so a change in config.toml is the same change the router enforces.

Long-Polling vs Webhook

Aleph supports two modes for receiving updates from Telegram:

Long-Polling (Default)

The bot periodically asks Telegram's servers for new updates. This is the default and works out of the box with no additional infrastructure.

Pros:

• No public URL or SSL certificate required
• Works behind NATs and firewalls
• Simple setup

Cons:

• Slightly higher latency (configurable via polling_interval_secs)
• Keeps a persistent connection to Telegram servers

Webhook Mode

Telegram pushes updates to your server via HTTPS POST requests. Enable by configuring webhook in the channel config.

Pros:

• Lower latency (instant delivery)
• More efficient for high-traffic bots

Cons:

• Requires a public HTTPS endpoint
• Needs a valid SSL certificate (or self-signed with the certificate field)

User and Group Allowlists

Finding User IDs

Telegram user IDs are numeric. To find a user's ID:

1. Have the user send a message to @userinfobot
2. Or use the getUpdates API to see raw message data

Allowlist Behavior

# Empty list = allow everyone (subject to dm_policy)
allow_from = []

# Specific users only
allow_from = [123456789, 987654321]

When dm_policy = "allowlist" and the sender is not in allow_from, the message is silently dropped. When dm_policy = "pairing" and the sender is not yet approved, the router mints a pairing code.

Group Chat Behavior

When Aleph receives a message in a group:

1. Check if the group ID is in allowed_groups (or if the list is empty)
2. Check if the sender is in allow_from (or if the list is empty)
3. If both pass, route the message to the agent

Media Handling

Receiving Media

Aleph extracts attachments from all supported Telegram media types:

Captions on media messages are extracted as the message text. If a message has both a caption and media, the caption becomes the text field.

Sending Media

Outbound attachments are dispatched based on MIME type:

• image/* — Sent as a photo (sendPhoto)
• audio/* — Sent as audio (sendAudio)
• video/* — Sent as video (sendVideo)
• Everything else — Sent as a document (sendDocument)

Attachments can be provided as:

• In-memory bytes (data field)
• Local file path (path field)
• Remote URL (url field)

Inline Keyboards

The Telegram interface supports inline keyboard buttons for interactive prompts. The approval system uses this to let users approve or deny tool executions directly from the chat:

Aleph wants to execute: shell_exec("ls -la")

[Allow Once] [Allow Always] [Deny]

When a user clicks a button, a callback query is routed back through the Gateway and processed by the approval bridge (TelegramChannelApprovalCapability). The loading indicator on the button is automatically dismissed via answerCallbackQuery. The bridge is two-way: Discord replies on the same flow edit the original message in place.

Session Routing

Each Telegram conversation gets a unique session key:

The exact format depends on your dm_scope setting (see Interfaces Overview).

Message Formatting

Aleph sends messages using Telegram's MarkdownV2 parse mode. The following formatting is supported:

Error Handling

The Telegram interface handles common failure scenarios:

Validation

The bot token is validated at two stages:

1. Format check (config load) — Token must be non-empty and contain a colon (format: <bot_id>:<hash>)
2. API check (channel start) — getMe is called to verify the token and retrieve the bot's username and ID

If either check fails, the channel reports a ConfigError or AuthFailed error and does not start polling.

Troubleshooting