This page connects a Telegram bot to Apus 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.
Pairing
Default DM policy for Telegram is pairing.
Channel troubleshooting
Cross-channel diagnostics and repair playbooks.
Gateway configuration
Full channel config patterns and examples.
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 Control UI Mini App — open the Control UI inside Telegram with
/controlui. - 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
- Control UI Mini App
- Access control and activation
- Group bot identity
- Finding your Telegram user ID
- Runtime behavior
- Feature reference
- Device pairing commands (
device-pairplugin) - Photo albums
- Audio messages
- Video messages
- Locations and venues
- Stickers
- Error reply controls
- Troubleshooting
- Device pairing commands (
device-pairplugin) - Create the bot token in BotFather
- Configure token and DM policy
- Verify the channel
- 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.
apus 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-levelbindings[](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(modesoff | 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 absolutefile_pathroots) - webhook:
webhookUrl,webhookSecret,webhookPath,webhookCertPath,legacyWebhook(optional explicit forwarding endpoint; omitted orfalseuses only the Gateway port) - 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
Multi-account precedence: with two or more account IDs configured, set channels.telegram.defaultAccount (or include channels.telegram.accounts.default) to make default routing explicit. Otherwise Apus falls back to the first normalized account ID and apus doctor warns. Omitted account dmPolicy, groupPolicy, allowFrom, and groupAllowFrom inherit the channel root, not accounts.default.*. Explicit account policies win; if neither scope sets them, DMs use pairing and groups use allowlist.
Multi-agent account ownership
Each Telegram account needs a resolvable agent owner. To bind the default account
to main, add this entry to the top-level bindings array:
{ agentId: "main", match: { channel: "telegram", accountId: "default" } }
Use the configured agent and account IDs for your Gateway. A missing owner leaves that account blocked with the exact binding remediation in channel status; other accounts keep running. Add the binding and restart the Gateway.
When upgrading a legacy agents.list config, Doctor preserves the previous
implicit account owner in a binding before saving explicit ownership. Doctor
requires the original roster and never promotes a narrower conversation route
to account-wide ownership. Missing historical ownership requires an operator
choice; Doctor reports the exact binding to add without changing existing routes.
See migration repairs.
Related
Pairing
Pair a Telegram user to the gateway.
Reactions
Emoji reaction semantics for the `message` tool.
Groups
Group and topic allowlist behavior.
Channel routing
Route inbound messages to agents.
Security
Threat model and hardening.
Multi-agent routing
Map groups and topics to agents.
Troubleshooting
Cross-channel diagnostics.