OpenClaw Telegram Integration: Your AI Agent on Telegram

When someone DMs your bot for the first time, dmPolicy: "pairing" (the default) generates a pairing code they need to get approved. The code expires after 1 hour. Once approved, they have access.

For a personal bot where you're the only user, dmPolicy: "allowlist" with your numeric Telegram user ID is more durable:

{codeBlock2}

To find your Telegram user ID: DM your bot, run openclaw logs --follow, and read the from.id field in the logs.

DM Policy Options

channels.telegram.dmPolicy has four values:

• pairing (default) — new users go through a pairing approval flow
• allowlist — only numeric user IDs in allowFrom can DM the bot
• open — anyone can DM (requires allowFrom: ["*"])
• disabled — DMs are blocked entirely

For most setups: personal agent = allowlist with your ID. Team bot = pairing. Public bot = open with caution.

Group Access Control

Groups need two things configured: which groups are allowed, and which senders within those groups are allowed.

{codeBlock3}

groupPolicy controls sender filtering within the group:

• allowlist (default) — only users in groupAllowFrom can trigger the bot
• open — any group member can trigger the bot
• disabled — bot is silent in this group

The wildcard "*" in the groups object applies defaults to all groups:

{codeBlock4}

Get your group's chat ID by forwarding a message to @getidsbot on Telegram, or run openclaw logs --follow and look at chat.id.

Privacy Mode and Group Visibility

This is the most common group setup issue. By default, Telegram bots only see messages that:

• Start with / (commands)
• Mention the bot by @botname
• Are replies to the bot's messages

If you want the bot to see all group messages (needed for requireMention: false), go to BotFather, run /setprivacy for your bot, and set it to Disable. Then remove and re-add the bot in the group.

After this, openclaw channels status will tell you if your config expects unmentioned group messages but privacy mode doesn't allow it.

Forum Topics and Per-Topic Routing

Telegram forum supergroups (groups with topics enabled) are first-class in OpenClaw. Each topic gets its own isolated session:

{`session key: telegram:group:-1001234567890:topic:42`}

And you can route different topics to different agents:

{codeBlock5}

This is useful for team setups where one Telegram group acts as a workspace — each topic routes to a specialized agent with its own memory and context.

Streaming Replies

OpenClaw streams partial replies in real time on Telegram. In DMs, it uses Telegram's native sendMessageDraft API (available for all bots since Bot API 9.5, March 2026). In groups and topics, it sends a preview message and edits it in place until the reply is final.

Streaming is on by default (partial mode). To adjust:

{codeBlock6}

For most users, leave it at the default. Streaming makes the agent feel responsive instead of making you wait for the full reply.

Custom Bot Commands

You can add custom commands to the Telegram command menu (the / list that shows up when typing):

{codeBlock7}

These are menu entries only — they show up in the command list and get sent as messages when tapped. Your agent handles them like any other message. Custom commands can't override built-in OpenClaw commands.

Inline Buttons

OpenClaw supports Telegram inline keyboards. Configure the scope first:

{codeBlock8}

Then the message tool can send buttons:

{codeBlock9}

When a user taps a button, OpenClaw receives callback_data: deploy_yes as a text message and routes it to the agent session.

Reaction Notifications

When someone reacts to one of your bot's messages, OpenClaw can surface that as a system event:

{codeBlock10}

"own" means reactions to messages your bot sent. Useful for knowing when someone approved or rejected something the agent did.

Webhook Mode (for VPS Deployments)

Long polling works fine locally. On a VPS where you want to minimize outbound connections, webhook mode is cleaner:

{codeBlock11}

Point a reverse proxy (nginx/caddy) at port 8787, and set webhookUrl to the public HTTPS URL. The secret prevents unauthorized webhook calls.

Troubleshooting Common Issues

Bot doesn't respond in groups

Check three things: (1) Is the group in your groups config or has a "*" wildcard? (2) Is the sender in groupAllowFrom? (3) If requireMention: false, is privacy mode disabled in BotFather? Run openclaw logs --follow and look for skip reasons.

setMyCommands failed on startup

This means your machine can't reach api.telegram.org. Check DNS and HTTPS egress. Some VPS providers block Telegram by default.

Network instability on VPS

If you're getting fetch failed or getUpdates failed errors, the issue is often IPv6. Add this to your config:

{codeBlock12}

Or if you need a proxy: channels.telegram.proxy: "socks5://user:pass@host:1080".

allowFrom has usernames instead of IDs

If you previously used @username in allowFrom, run openclaw doctor --fix to resolve them to numeric IDs.

A Practical Config for a Personal Agent

Here's a complete config for a single-user personal AI agent on Telegram:

{codeBlock13}

This gives you a private bot that only responds to you, streams replies live, and shows custom commands in the menu. Clean and locked down.

What You Can Do Once It's Connected

Once Telegram is wired up, your agent runs in your pocket. Some patterns I use:

• Morning briefings sent automatically via cron at startup
• Forum topics routing to different specialized agents (dev, content, ops)
• Inline button confirmations before the agent takes sensitive actions
• Reaction acks (👍) so I know the agent received and processed a message
• Custom command shortcuts for frequent tasks like backups and deploys

Telegram's Bot API is genuinely one of the more capable channels to build on. Long polling is reliable, the forum topic isolation is surprisingly useful for multi-agent setups, and the streaming support keeps the UX snappy.

Want the complete guide? Get The OpenClaw Playbook — $9.99