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, and Markdown formatting.

Capabilities

Prerequisites

cargo build --release --features telegram
# or for all interfaces:
cargo build --release --features all-interfaces

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"

# User allowlist -- empty means allow all users
# Use Telegram user IDs (not usernames)
allowed_users = [123456789, 987654321]

# Group/chat allowlist -- empty means allow all groups
allowed_groups = [-1001234567890]

# Allow direct messages (default: true)
dm_allowed = true

# Allow group messages (default: true)
groups_allowed = true

# Polling interval in seconds for long-polling mode (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

# Webhook configuration (optional -- defaults to long-polling)
# [channels.config.webhook]
# url = "https://your-domain.com/telegram/webhook"
# port = 8443
# path = "/telegram/webhook"
# certificate = "/path/to/cert.pem"    # For self-signed certificates
# secret_token = "your-webhook-secret"  # Verification token

Environment Variable Mode

The simplest setup uses a single environment variable:

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

Aleph will pick it up automatically via TelegramConfig::from_env().

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 adding a webhook section:

[channels.config.webhook]
url = "https://aleph.example.com/telegram/webhook"
port = 8443
secret_token = "a-random-secret-string"

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 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
allowed_users = []

# Specific users only
allowed_users = [123456789, 987654321]

When allowed_users is non-empty, messages from unlisted users are silently dropped. The same logic applies to allowed_groups for group chats.

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 allowed_users (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. This is primarily used by the tool approval system 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. The loading indicator on the button is automatically dismissed via answerCallbackQuery.

Keyboards can also be used for custom multi-choice responses built by the agent itself.

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