Telegram

Deployment Steps

1. Create a Telegram Bot

Open Telegram and chat with @BotFather (verify the username is actually @BotFather)
Send the /newbot command
Follow the prompts to set the bot name and username (username must end with bot)
Copy and save the Bot Token (keep it secure; if leaked, revoke/regenerate via @BotFather)

2. Configure Bot Settings (Optional)

Configure via BotFather:

/setdescription - Set description
/setabouttext - Set about info
/setuserpic - Set avatar
/setjoingroups - Allow/deny adding bot to groups
/setprivacy - Control whether bot can see all group messages

Enter your Bot Token under Settings → Vibe Mode in the 302 AI Studio client, then click Update Configuration. The gateway will restart automatically, after which you can chat normally in Telegram.

Long polling mode is used by default; no public URL is required. DMs use pairing mode by default—the first contact requires approving a pairing code.

4. Send Test Message

Find your created bot in Telegram and send a message to test.

5. Pairing Authorization

By default, the bot will reply with a pairing code and pairing command.

If the bot asks you to run a pairing command (like openclaw pairing approve telegram <pairing_code>), copy the command, return to the 302 AI Studio client, and send the command to Open Claw to execute the pairing operation. Pairing codes expire after 1 hour.

After successful pairing, you can chat normally!

DM Policy

Policy	Description
`pairing`	Pairing mode (default): Unknown senders receive a pairing code, can use after approval
`allowlist`	Allowlist mode: Only specified user IDs can use
`open`	Open mode: Everyone can use
`disabled`	Disable DM

Getting User ID

There are multiple ways to get a Telegram user ID:

Method 1 (Recommended): Via Gateway Logs

Start the Gateway and DM your bot
Run openclaw logs --follow and look for from.id

Method 2: Via Bot API

DM your bot
Use your bot token to get updates and read message.from.id:

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

Method 3: Third-party Bots

DM @userinfobot or @getidsbot and use the returned user ID

Group Settings

If you need to use the bot in groups:

Add the bot to the group
If you need the bot to respond to all messages (not just @mentions), disable privacy mode in BotFather using /setprivacy, or make the bot a group admin

After toggling privacy mode, you need to remove and re-add the bot to the group for changes to take effect.

Group Message Visibility (Privacy Mode)

Telegram bots have privacy mode enabled by default, which limits which group messages they receive. If your bot must see all group messages, you have two options:

Disable privacy mode using /setprivacy
Add the bot as a group admin (admin bots can receive all messages)

Group Activation Mode

By default, the bot only responds to mentions (@botname) in groups.

Switch via Command (Session Level)

Send in the group:

/activation always - Respond to all messages
/activation mention - Require mention (default)

Commands only update session state and will revert to default behavior after restart.

Getting Group Chat ID

Forward any message from the group to @userinfobot or @getidsbot on Telegram to see the chat ID (negative number, like -1001234567890).

Feature Support

Feature	Status	Description
DM	✅ Supported	Shares agent's main session
Group Chat	✅ Supported	Each group maintains isolated session
Images	✅ Supported	Send and receive
Files	✅ Supported	Send and receive
Voice	✅ Supported	Voice memos and audio files
Video	✅ Supported	Send and receive
Stickers	✅ Supported	Static stickers support vision processing, animated/video stickers skipped
Inline Buttons	✅ Supported	Callback buttons
Reactions	✅ Supported	Receive and send reactions
Forum Topics	✅ Supported	Each topic maintains isolated session

Sticker Features

Receiving Stickers

When users send stickers, OpenClaw processes them based on type:

Static stickers (WEBP): Downloaded and processed via vision
Animated stickers (TGS): Skipped (Lottie format not supported)
Video stickers (WEBM): Skipped (video format not supported)

OpenClaw caches sticker descriptions to avoid redundant API calls, cache location: ~/.openclaw/telegram/sticker-cache.json

Command	Function
`/status`	View status
`/reset`	Reset session
`/model`	Switch model
`/activation`	Toggle group activation mode

Formatting

Outbound Telegram text uses parse_mode: "HTML"
Markdown-like input is rendered as Telegram-safe HTML (bold/italic/strikethrough/code/links)
Block-level elements are flattened to text with line breaks/bullets
If Telegram rejects HTML payload, OpenClaw retries with plain text

Start the Service

Complete this channel’s configuration in the 302 AI Studio client under Settings → Vibe Mode.

Limits

Limit	Default	Description
Text Chunk	4000 chars	Outbound text chunked at this length
Media Size	5 MB	Media download/upload limit
History	50 messages	Group history context count

Troubleshooting

Bot not responding

Check if the Bot Token is correct
Confirm the bot is started
Check if outbound HTTPS/DNS to api.telegram.org is blocked

No response in groups

Check Bot Privacy Mode settings (BotFather → /setprivacy)
If you need to respond to all messages, disable privacy mode or make the bot an admin
Confirm whether @mention is required
Use /activation always to test temporarily

Pairing code issues

Pairing codes expire after 1 hour
Approve pairing requests in 302 AI Studio client

Bot silently stops responding after startup

Some hosts resolve api.telegram.org to IPv6 first, which may hang if the server has no IPv6 egress
Fix by enabling IPv6 egress or forcing IPv4 resolution

setMyCommands failed error

Usually means outbound HTTPS/DNS to api.telegram.org is blocked
Check network connection and firewall settings

More Information

For more detailed configuration options, advanced features, and complete configuration reference, please refer to the official OpenClaw documentation.