​

Telegram (Bot API)

​

What it is

• A Telegram Bot API provider owned by the Gateway.
• Deterministic routing: replies go back to Telegram; the model never chooses providers.
• DMs share the agent’s main session; groups stay isolated (telegram:group:<chatId>).

​

Setup (fast path)

​

1) Create a bot token (BotFather)

1. Open Telegram and chat with @BotFather.
2. Run /newbot, then follow the prompts (name + username ending in bot).
3. Copy the token and store it safely.

• /setjoingroups — allow/deny adding the bot to groups.
• /setprivacy — control whether the bot sees all group messages.

​

2) Configure the token (env or config)

{
  telegram: {
    enabled: true,
    botToken: "123:abc",
    dmPolicy: "pairing",
    groups: { "*": { requireMention: true } }
  }
}

3. Start the gateway. Telegram starts when a telegram config section exists and a token is resolved.
4. DM access defaults to pairing. Approve the code when the bot is first contacted.
5. For groups: add the bot, decide privacy/admin behavior (below), then set telegram.groups to control mention gating + allowlists.

​

Token + privacy + permissions (Telegram side)

​

Token creation (BotFather)

• /newbot creates the bot and returns the token (keep it secret).
• If a token leaks, revoke/regenerate it via @BotFather and update your config.

​

Group message visibility (Privacy Mode)

• Disable privacy mode with /setprivacy or
• Add the bot as a group admin (admin bots receive all messages).

​

Group permissions (admin rights)

​

How it works (behavior)

• Inbound messages are normalized into the shared provider envelope with reply context and media placeholders.
• Group replies require a mention by default (native @mention or routing.groupChat.mentionPatterns).
• Multi-agent override: routing.agents.<agentId>.mentionPatterns takes precedence.
• Replies always route back to the same Telegram chat.
• Long-polling uses grammY runner with per-chat sequencing; overall concurrency is capped by agent.maxConcurrent.

​

Formatting (Telegram HTML)

• Outbound Telegram text uses parse_mode: "HTML" (Telegram’s supported tag subset).
• Markdown-ish input is rendered into Telegram-safe HTML (bold/italic/strike/code/links); block elements are flattened to text with newlines/bullets.
• Raw HTML from models is escaped to avoid Telegram parse errors.
• If Telegram rejects the HTML payload, Clawdbot retries the same message as plain text.

​

Limits

• Outbound text is chunked to telegram.textChunkLimit (default 4000).
• Media downloads/uploads are capped by telegram.mediaMaxMb (default 5).

​

Group activation modes

​

Via config (recommended)

{
  telegram: {
    groups: {
      "-1001234567890": { requireMention: false }  // always respond in this group
    }
  }
}

{
  telegram: {
    groups: {
      "*": { requireMention: false }  // all groups, always respond
    }
  }
}

{
  telegram: {
    groups: {
      "*": { requireMention: true }  // or omit groups entirely
    }
  }
}

​

Via command (session-level)

• /activation always - respond to all messages
• /activation mention - require mentions (default)

​

Getting the group chat ID

​

Topics (forum supergroups)

• Appends :topic:<threadId> to the Telegram group session key so each topic is isolated.
• Sends typing indicators and replies with message_thread_id so responses stay in the topic.
• Exposes MessageThreadId + IsForum in template context for routing/templating.
• Topic-specific configuration is available under telegram.groups.<chatId>.topics.<threadId> (skills, allowlists, auto-reply, system prompts, disable).

• Appends :topic:<threadId> to DM session keys for isolation.
• Uses the thread id for draft streaming + replies.

​

Access control (DMs + groups)

​

DM access

• Default: telegram.dmPolicy = "pairing". Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
• Approve via:
  • clawdbot pairing list --provider telegram
  • clawdbot pairing approve --provider telegram <CODE>
• Pairing is the default token exchange used for Telegram DMs. Details: Pairing

​

Group access

• No groups config = all groups allowed
• With groups config = only listed groups or "*" are allowed
• Example: "groups": { "-1001234567890": {}, "*": {} } allows all groups

• "open" (default) = all senders in allowed groups can message
• "allowlist" = only senders in telegram.groupAllowFrom can message
• "disabled" = no group messages accepted at all

​

Long-polling vs webhook

• Default: long-polling (no public URL required).
• Webhook mode: set telegram.webhookUrl (optionally telegram.webhookSecret + telegram.webhookPath).
  • The local listener binds to 0.0.0.0:8787 and serves POST /telegram-webhook by default.
  • If your public URL is different, use a reverse proxy and point telegram.webhookUrl at the public endpoint.

​

Reply threading

• [[reply_to_current]] — reply to the triggering message.
• [[reply_to:<id>]] — reply to a specific message id.

• first (default), all, off.

​

Audio messages (voice vs file)

• [[audio_as_voice]] — send audio as a voice note instead of a file.

​

Streaming (drafts)

• Private chats with topics enabled (forum topic mode for the bot).
• Incoming messages must include message_thread_id (private topic thread).
• Streaming is ignored for groups/supergroups/channels.

• telegram.streamMode: "off" | "partial" | "block" (default: partial)
  • partial: update the draft bubble with the latest streaming text.
  • block: update the draft bubble in larger blocks (chunked).
  • off: disable draft streaming.

• /reasoning stream streams reasoning into the draft bubble while the reply is generating, then sends the final answer without reasoning.
• If telegram.streamMode is off, reasoning stream is disabled. More context: Streaming + chunking.

​

Retry policy

​

Agent tool (messages + reactions)

• Tool: telegram with sendMessage action (to, content, optional mediaUrl, replyToMessageId, messageThreadId).
• Tool: telegram with react action (chatId, messageId, emoji).
• Reaction removal semantics: see /tools/reactions.
• Tool gating: telegram.actions.reactions and telegram.actions.sendMessage (default: enabled).

​

Delivery targets (CLI/cron)

• Use a chat id (123456789) or a username (@name) as the target.
• Example: clawdbot send --provider telegram --to 123456789 "hi".

​

Troubleshooting

• If you set telegram.groups.*.requireMention=false, Telegram’s Bot API privacy mode must be disabled.
  • BotFather: /setprivacy → Disable (then remove + re-add the bot to the group)
• clawdbot providers status shows a warning when config expects unmentioned group messages.
• clawdbot providers status --probe can additionally check membership for explicit numeric group IDs (it can’t audit wildcard "*" rules).
• Quick test: /activation always (session-only; use config for persistence)

• If telegram.groups is set, the group must be listed or use "*"
• Check Privacy Settings in @BotFather → “Group Privacy” should be OFF
• Verify bot is actually a member (not just an admin with no read access)
• Check gateway logs: clawdbot logs --follow (look for “skipping group message”)

• The /activation command updates session state but doesn’t persist to config
• For persistent behavior, add group to telegram.groups with requireMention: false

• Make sure your Telegram user ID is authorized (via pairing or telegram.allowFrom)
• Commands require authorization even in groups with groupPolicy: "open"

​

Configuration reference (Telegram)

• telegram.enabled: enable/disable provider startup.
• telegram.botToken: bot token (BotFather).
• telegram.tokenFile: read token from file path.
• telegram.dmPolicy: pairing | allowlist | open | disabled (default: pairing).
• telegram.allowFrom: DM allowlist (ids/usernames). open requires "*".
• telegram.groupPolicy: open | allowlist | disabled (default: open).
• telegram.groupAllowFrom: group sender allowlist (ids/usernames).
• telegram.groups: per-group defaults + allowlist (use "*" for global defaults).
  • telegram.groups.<id>.requireMention: mention gating default.
  • telegram.groups.<id>.skills: skill filter (omit = all skills, empty = none).
  • telegram.groups.<id>.allowFrom: per-group sender allowlist override.
  • telegram.groups.<id>.systemPrompt: extra system prompt for the group.
  • telegram.groups.<id>.enabled: disable the group when false.
  • telegram.groups.<id>.topics.<threadId>.*: per-topic overrides (same fields as group).
  • telegram.groups.<id>.topics.<threadId>.requireMention: per-topic mention gating override.
• telegram.replyToMode: off | first | all (default: first).
• telegram.textChunkLimit: outbound chunk size (chars).
• telegram.streamMode: off | partial | block (draft streaming).
• telegram.mediaMaxMb: inbound/outbound media cap (MB).
• telegram.retry: retry policy for outbound Telegram API calls (attempts, minDelayMs, maxDelayMs, jitter).
• telegram.proxy: proxy URL for Bot API calls (SOCKS/HTTP).
• telegram.webhookUrl: enable webhook mode.
• telegram.webhookSecret: webhook secret (optional).
• telegram.webhookPath: local webhook path (default /telegram-webhook).
• telegram.actions.reactions: gate Telegram tool reactions.
• telegram.actions.sendMessage: gate Telegram tool message sends.

• routing.groupChat.mentionPatterns (mention gating patterns).
• routing.agents.<agentId>.mentionPatterns overrides for multi-agent setups.
• commands.native, commands.text, commands.useAccessGroups (command behavior).
• messages.responsePrefix, messages.ackReaction, messages.ackReactionScope.