Telegram is one of the natively supported channels in OpenClaw, built on the grammY framework. Telegram's group and channel features are very powerful, offering a native Bot API, fine-grained permission control, and rich message formatting. This article dives deep into OpenClaw's advanced configuration options for Telegram group scenarios.
Telegram Group Types
Telegram has several different group types. Understanding their differences helps you configure your bot appropriately:
Regular groups: Small groups of up to 200 members. Bots can receive all messages (if Privacy Mode is disabled) or only commands and @mentions.
Supergroups: Large groups of up to 200,000 members with more management features. This is the group type used by most communities.
Channels: One-way broadcast channels where bots can post messages as administrators, but they are typically not used for interactive AI conversations.
Privacy Mode and Message Reception
Telegram Bots have Privacy Mode enabled by default, which means in groups the bot can only receive: messages starting with /, messages that directly @mention the bot, replies to the bot's messages, and service messages (such as member join/leave).
If you want the bot to receive all messages in a group, you need to disable Privacy Mode in BotFather. Send the /setprivacy command and select your bot, then set it to Disabled. Note that after this change, you need to remove the bot from the group and re-add it for the change to take effect.
Configure group behavior in openclaw.json:
{
"channels": {
"telegram": {
"enabled": true,
"token": "your-bot-token",
"groups": {
"privacyMode": false,
"triggerMode": "command_and_mention",
"commands": ["/ask", "/chat", "/help"]
}
}
}
}
Command System
Telegram's command system is the standard way to interact with bots. OpenClaw allows you to define multiple commands, each bound to different behaviors:
{
"channels": {
"telegram": {
"groups": {
"commands": {
"/ask": {
"description": "Ask the AI a question",
"behavior": "single_response"
},
"/chat": {
"description": "Start a multi-turn conversation",
"behavior": "conversation"
},
"/reset": {
"description": "Reset conversation context",
"behavior": "reset_context"
}
}
}
}
}
}
In single_response mode, the bot replies only once. In conversation mode, the bot continues tracking the user's subsequent messages (until timeout or manual reset). It's recommended to register these commands in BotFather using /setcommands so users can see the command list and descriptions when typing /.
Group Permission Control
OpenClaw provides multi-layered Telegram group permission controls:
{
"channels": {
"telegram": {
"groups": {
"allowedGroups": [-1001234567890, -1009876543210],
"userAllowlist": [123456789, 987654321],
"adminOnly": false,
"requirePairing": false
}
}
}
}
Group allowlist (allowedGroups): Uses Telegram group chat_id values to restrict the bot to specific groups only. Chat IDs are negative numbers and can be obtained by having the bot receive a message in the group.
User allowlist (userAllowlist): Restricts which user IDs can trigger the AI in groups. Messages from other users are ignored.
Admin only (adminOnly): When set to true, only group administrators can use AI features.
DM pairing (requirePairing): Requires users to first complete pairing verification via DM with the bot.
These options can be combined. For example, you can configure it so only paired users in specific groups can use the bot.
Inline Mode
Telegram Bots support Inline Mode, which allows users to invoke the AI in any chat by typing @botname question without adding the bot to the group. After enabling Inline Mode in BotFather, configure it in OpenClaw:
{
"channels": {
"telegram": {
"inlineMode": {
"enabled": true,
"cacheTime": 30
}
}
}
}
Inline Mode replies appear as inline query results. Users select a result and it is sent to the current conversation.
Multi-Bot Management
In large communities, you may need to deploy multiple AI bots, each serving a different role. OpenClaw supports running multiple Telegram bots within the same instance:
{
"channels": {
"telegram": [
{
"name": "general-assistant",
"token": "bot-token-1",
"model": "gpt-4"
},
{
"name": "code-helper",
"token": "bot-token-2",
"model": "claude-sonnet"
}
]
}
}
Each bot uses different token and model configurations and can coexist in the same group. Users invoke different AI assistants by @mentioning different bots.
Message Formatting and Markdown
Telegram supports both MarkdownV2 and HTML message formats. OpenClaw uses MarkdownV2 by default to format AI replies, supporting bold, italic, code blocks, links, and more. When AI replies contain complex formatting, OpenClaw automatically handles escape characters to ensure proper rendering in Telegram.
You can switch to HTML format or plain text via configuration:
{
"channels": {
"telegram": {
"parseMode": "MarkdownV2"
}
}
}
Rate Limiting and Queuing
The Telegram Bot API has rate limits: a maximum of 30 messages per second and 20 messages per minute in the same group. OpenClaw has a built-in message queue mechanism to handle these limits. In high-traffic groups, replies may experience brief delays, which is normal.
Troubleshooting
If the bot is not responding in a group, follow these steps: confirm the bot has been added to the group; check whether Privacy Mode settings match the trigger mode; verify the group ID is on the allowlist (if configured); and check the OpenClaw logs for error messages. Use the openclaw channels status command to quickly view the connection status of all channels.