Telegram (Bot API)

Status: production-ready for bot DMs + groups via grammY. Long polling is the default mode; webhook mode is optional.

Quick setup

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

bashCopy
mayros gateway
mayros pairing list telegram
mayros pairing approve telegram <CODE>

Telegram side settings

Access control and activation

bashCopy
curl "https://api.telegram.org/bot<bot_token>/getUpdates"

Runtime behavior

• Telegram is owned by the gateway process.
• Routing is deterministic: Telegram inbound replies back to Telegram (the model does not pick channels).
• Inbound messages normalize into the shared channel envelope with reply metadata and media placeholders.
• Group sessions are isolated by group ID. Forum topics append :topic:<threadId> to keep topics isolated.
• DM messages can carry message_thread_id; Mayros routes them with thread-aware session keys and preserves thread ID for replies.
• Long polling uses grammY runner with per-chat/per-thread sequencing. Overall runner sink concurrency uses agents.defaults.maxConcurrent.
• Telegram Bot API has no read-receipt support (sendReadReceipts does not apply).

Feature reference

Troubleshooting

More help: Channel troubleshooting.

Telegram config reference pointers

Primary reference:

• channels.telegram.enabled: enable/disable channel startup.

• channels.telegram.botToken: bot token (BotFather).

• channels.telegram.tokenFile: read token from file path.

• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (default: pairing).

• channels.telegram.allowFrom: DM allowlist (numeric Telegram user IDs). open requires "*". mayros doctor --fix can resolve legacy @username entries to IDs.

• channels.telegram.groupPolicy: open | allowlist | disabled (default: allowlist).

• channels.telegram.groupAllowFrom: group sender allowlist (numeric Telegram user IDs). mayros doctor --fix can resolve legacy @username entries to IDs.

• channels.telegram.groups: per-group defaults + allowlist (use "*" for global defaults).

  • channels.telegram.groups.<id>.groupPolicy: per-group override for groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.requireMention: mention gating default.
  • channels.telegram.groups.<id>.skills: skill filter (omit = all skills, empty = none).
  • channels.telegram.groups.<id>.allowFrom: per-group sender allowlist override.
  • channels.telegram.groups.<id>.systemPrompt: extra system prompt for the group.
  • channels.telegram.groups.<id>.enabled: disable the group when false.
  • channels.telegram.groups.<id>.topics.<threadId>.*: per-topic overrides (same fields as group).
  • channels.telegram.groups.<id>.topics.<threadId>.groupPolicy: per-topic override for groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.topics.<threadId>.requireMention: per-topic mention gating override.

• channels.telegram.capabilities.inlineButtons: off | dm | group | all | allowlist (default: allowlist).

• channels.telegram.accounts.<account>.capabilities.inlineButtons: per-account override.

• channels.telegram.replyToMode: off | first | all (default: off).

• channels.telegram.textChunkLimit: outbound chunk size (chars).

• channels.telegram.chunkMode: length (default) or newline to split on blank lines (paragraph boundaries) before length chunking.

• channels.telegram.linkPreview: toggle link previews for outbound messages (default: true).

• channels.telegram.streaming: true | false (live stream preview; default: true).

• channels.telegram.mediaMaxMb: inbound/outbound media cap (MB).

• channels.telegram.retry: retry policy for outbound Telegram API calls (attempts, minDelayMs, maxDelayMs, jitter).

• channels.telegram.network.autoSelectFamily: override Node autoSelectFamily (true=enable, false=disable). Defaults to disabled on Node 22 to avoid Happy Eyeballs timeouts.

• channels.telegram.proxy: proxy URL for Bot API calls (SOCKS/HTTP).

• channels.telegram.webhookUrl: enable webhook mode (requires channels.telegram.webhookSecret).

• channels.telegram.webhookSecret: webhook secret (required when webhookUrl is set).

• channels.telegram.webhookPath: local webhook path (default /telegram-webhook).

• channels.telegram.webhookHost: local webhook bind host (default 127.0.0.1).

• channels.telegram.actions.reactions: gate Telegram tool reactions.

• channels.telegram.actions.sendMessage: gate Telegram tool message sends.

• channels.telegram.actions.deleteMessage: gate Telegram tool message deletes.

• channels.telegram.actions.sticker: gate Telegram sticker actions — send and search (default: false).

• channels.telegram.reactionNotifications: off | own | all — control which reactions trigger system events (default: own when not set).

• channels.telegram.reactionLevel: off | ack | minimal | extensive — control agent's reaction capability (default: minimal when not set).

• Configuration reference - Telegram

Telegram-specific high-signal fields:

• startup/auth: enabled, botToken, tokenFile, accounts.*
• access control: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*
• command/menu: commands.native, customCommands
• threading/replies: replyToMode
• streaming: streaming (preview), blockStreaming
• formatting/delivery: textChunkLimit, chunkMode, linkPreview, responsePrefix
• media/network: mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
• webhook: webhookUrl, webhookSecret, webhookPath, webhookHost
• actions/capabilities: capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
• reactions: reactionNotifications, reactionLevel
• writes/history: configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

Related

• Pairing
• Channel routing
• Multi-agent routing
• Troubleshooting