Telegram Channel

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dallay/corvus/llms.txt

Use this file to discover all available pages before exploring further.

​

Features

• Long-polling for real-time message delivery
• Typing indicators during processing
• Progressive message updates (streaming mode)
• Username and user ID allowlist
• Pairing code for self-service binding
• Media attachment support
• Forum/topic support
• Message splitting for long responses (4096 char limit)

​

Bot Setup with BotFather

​

1. Create Your Bot

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Follow the prompts:
   • Enter a name for your bot (e.g., “Corvus Assistant”)
   • Enter a username ending in bot (e.g., “corvus_ai_bot”)
4. BotFather will respond with your bot token:
   Use this token to access the HTTP API:
   123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
   

​

2. Configure Bot Settings

• Privacy Mode: Send /setprivacy to BotFather, select your bot, and choose Disable (allows bot to see all messages in groups)
• About Text: Send /setabouttext to set a description
• Profile Picture: Send /setuserpic to upload an avatar

​

3. Get Your Telegram User ID

1. Search for @userinfobot in Telegram
2. Send any message - it will reply with your user ID
3. Note the numeric ID (e.g., 123456789)

​

Configuration

[channels_config.telegram]
bot_token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
allowed_users = ["alice", "bob", "123456789"]
stream_mode = "full"
draft_update_interval_ms = 1000

​

Configuration Options

​

Streaming Mode

• "off" - Send complete response as a single message
• "full" - Send draft message and progressively update as the LLM generates text

​

Allowlist Patterns

​

Username Format

allowed_users = ["alice", "bob"]  # Both "alice" and "@alice" match

​

Numeric User ID

allowed_users = ["123456789", "987654321"]

​

Mixed Allowlist

allowed_users = ["alice", "123456789", "bob"]

​

Wildcard (Allow All)

allowed_users = ["*"]

​

Pairing Flow

​

Operator-Side Setup

1. Start Corvus with empty allowlist:
   corvus channel start
   
2. Corvus outputs a one-time pairing code:
   🔐 Telegram pairing required. One-time bind code: A1B2C3
      Send `/bind <code>` from your Telegram account.
   

​

User-Side Binding

1. User sends to the bot:
   /bind A1B2C3
   
2. Bot responds:
   ✅ Telegram account bound successfully. You can talk to Corvus now.
   
3. User’s identity is added to allowed_users in config and persisted.

​

Manual Binding

corvus channel bind-telegram alice

corvus channel bind-telegram 123456789

​

Testing and Verification

​

1. Start Channel Listener

corvus channel start

💬 Starting channels...
  ✅ Telegram connected

​

2. Health Check

corvus channel doctor

🩺 Corvus Channel Doctor

  ✅ Telegram  healthy

​

3. Send Test Message

1. Open Telegram and search for your bot username
2. Send /start or any message
3. If you’re in the allowlist, the bot should respond via the LLM
4. If not allowlisted, you’ll see:
   🔐 This bot requires operator approval.
   
   Copy this command to operator terminal:
   `corvus channel bind-telegram alice`
   
   After operator runs it, send your message again.
   

​

Advanced Features

​

Forum/Topic Support

{chat_id}:{message_thread_id}

​

Media Attachments

• [IMAGE:<path-or-url>] - Send as photo
• [DOCUMENT:<path-or-url>] - Send as document
• [VIDEO:<path-or-url>] - Send as video
• [AUDIO:<path-or-url>] - Send as audio
• [VOICE:<path-or-url>] - Send as voice message

Here's the chart you requested:

[IMAGE:/tmp/chart.png]

And the data file:

[DOCUMENT:/tmp/data.csv]

​

Message Splitting

First chunk...

(continues...)

(continued)

Second chunk...

(continues...)

(continued)

Final chunk.

​

Markdown Formatting

• *bold* - bold text
• _italic_ - italic text
• [link](url) - hyperlinks
• `code` - inline code
• code blocks

​

Troubleshooting

​

Bot Not Responding

1. Check allowlist:
   corvus channel list
   
2. Verify user is allowlisted:
   grep allowed_users ~/.corvus/config.toml
   
3. Check logs for authorization warnings:
   Telegram: ignoring message from unauthorized user: username=alice, user_id=Some("123456789"). 
   Allowlist Telegram username (without '@') or numeric user ID.
   

​

409 Conflict Error

Telegram polling conflict (409): Conflict: terminated by other getUpdates request

pkill -f "corvus channel start"
corvus channel start

​

Invalid Bot Token

Telegram API error (401): Unauthorized

1. Send /token to @BotFather
2. Select your bot
3. Copy the token and update config.toml

​

Rate Limiting

• 30 messages per second to different users
• 1 message per second to the same user
• 20 edit operations per minute

​

Security Best Practices

1. Use User IDs: Prefer numeric user IDs over usernames (usernames can be changed)
2. Never Share Token: Keep bot_token secret - it grants full bot access
3. Empty Allowlist by Default: Start with allowed_users = [] and explicitly add users
4. Monitor Logs: Watch for unauthorized access attempts
5. Rotate Tokens: Regenerate token via BotFather if compromised

​

Reference

• Source: clients/agent-runtime/src/channels/telegram.rs
• Telegram Bot API: https://core.telegram.org/bots/api
• BotFather: https://t.me/BotFather
• Line range: telegram.rs:1-1628