Telegram

This page connects a Telegram bot to OpenClaw and sets who is allowed to message it.

Telegram is production-ready for bot DMs and groups via grammY. Long polling is the default transport. Webhook mode is optional.

What each page covers

• Telegram setup — install the bot, set the token, approve the first DM, and add the bot to a group.
• Telegram access control — DM policy, group allowlists, mention gating, and per-chat tool policy.
• Telegram message behavior — runtime model, stream previews, native commands, reply tags, and send limits.
• Telegram threads and sessions — forum topic session keys, per-topic agents, and ACP bindings.
• Telegram rich messages and approvals — Bot API 10.3 rich messages, inline buttons, message actions, and exec approvals.
• Telegram media and attachments — photo albums, voice and video notes, locations, venues, and stickers.
• Telegram events and operations — reaction notifications, config writes, and error reply policy.
• Telegram transports — long polling and webhook mode compared.
• Telegram Dashboard Mini App — open the Control UI inside Telegram with /dashboard.
• Telegram troubleshooting — silent groups, missing commands, rejected tokens, and unstable polling.

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /channels/telegram#troubleshooting still resolves. Each entry points at the page that now holds the content.

• Quick setup
• Telegram side settings
• Dashboard Mini App
• Access control and activation
• Group bot identity
• Finding your Telegram user ID
• Runtime behavior
• Feature reference
• Device pairing commands (device-pair plugin)
• Photo albums
• Audio messages
• Video messages
• Locations and venues
• Stickers
• Error reply controls
• Troubleshooting
• Device pairing commands (device-pair plugin)
• Create the bot token in BotFather
• Configure token and DM policy
• Restart the gateway
• Approve your first DM
• Add the bot to a group
• Privacy mode and group visibility
• Group permissions
• Helpful BotFather toggles
• DM policy
• Group policy and allowlists
• Mention behavior
• Live stream preview (message edits)
• Rich message formatting
• Native commands and custom commands
• Inline buttons
• Telegram message actions for agents and automation
• Reply threading tags
• Forum topics and thread behavior
• Photo albums, audio, video, and stickers
• Reaction notifications
• Ack reactions
• Config writes from Telegram events and commands
• Long polling vs webhook
• Limits and CLI targets
• Exec approvals in Telegram
• Bot does not respond to non mention group messages
• Bot not seeing group messages at all
• Commands work partially or not at all
• Startup reports unauthorized token
• Polling or network instability

Configuration reference

Primary reference: Configuration reference - Telegram.

openclaw doctor --fix removes retired tuning settings (timeoutSeconds, mediaGroupFlushMs, pollingStallThresholdMs, retry, and errorCooldownMs) from their former configuration scopes. Account names and sender-specific tool-policy keys are preserved, even when they match a retired setting name.

High-signal Telegram fields

• startup/auth: enabled, botToken, tokenFile (must be a regular file; symlinks are rejected), accounts.*
• access control: dmPolicy, allowFrom, direct.*.tools, direct.*.toolsBySender, groupPolicy, groupAllowFrom, groups, groups.*.topics.*, top-level bindings[] (type: "acp")
• group introductions: joinIntro, accounts.*.joinIntro (default: true)
• topic defaults: groups.<chatId>.topics."*" applies to unmatched forum topics; exact topic IDs override it
• exec approvals: execApprovals, accounts.*.execApprovals
• command/menu: commands.native, commands.nativeSkills, customCommands
• threading/replies: replyToMode, threadBindings
• streaming: streaming (modes off | partial | block | progress), streaming.preview.toolProgress
• formatting/delivery: textChunkLimit, streaming.chunkMode, richMessages, markdown.tables (off | bullets | code | block), linkPreview, responsePrefix
• media/network: mediaMaxMb, network.autoSelectFamily, network.dangerouslyAllowPrivateNetwork, proxy
• custom API root: apiRoot (Bot API root only; do not include /bot<TOKEN>), trustedLocalFileRoots (self-hosted Bot API absolute file_path roots)
• webhook: webhookUrl, webhookSecret, webhookPath, webhookHost, webhookPort, webhookCertPath
• actions/capabilities: capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker|createForumTopic|editForumTopic
• reactions: reactionNotifications, reactionLevel
• errors: errorPolicy, silentErrorReplies
• writes/history: configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

Related