OpenClaw Manual OpenClaw

OpenClaw Telegram Channel

Messaging
Easy

Connect OpenClaw to Telegram using the grammY Bot API framework. Create a Telegram bot via @BotFather, grab the token, and your AI assistant is live on Telegram in minutes. Supports long-polling by default with optional webhook mode. One of the easiest channels to set up, with rich features including inline buttons, stickers, reactions, and group chat support.

Quick Info
Difficulty Easy
Category Messaging
Features Supported 6 / 6

Telegram Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Supported

Threads

Supported

Voice Messages

Supported

Group Chat

Supported

Telegram Prerequisites

  • A Telegram account
  • A Bot Token from @BotFather (send /newbot to @BotFather)
  • OpenClaw Gateway running and configured
  • Node.js 18+ installed on your server

Telegram Quick Setup

1

Create a bot with @BotFather

Open Telegram, search for @BotFather, and send /newbot. Follow the prompts to name your bot and get the API token. Save this token — you'll need it for the config.

2

Add Telegram channel config

Add the Telegram channel configuration to ~/.openclaw/openclaw.json. Paste the bot token from @BotFather into the botToken field. Set the dmPolicy (pairing, allowlist, or open) to control who can message your assistant.

3

Start Gateway and test

Launch the Gateway process. Search for your bot on Telegram and send it a message. If using the default pairing policy, approve the sender via 'openclaw pairing approve telegram <code>'. OpenClaw should respond through the AI assistant.

Telegram Configuration Example

config.json 
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
      "dmPolicy": "pairing"
    }
  }
}

Telegram Deep Dive

Architecture Overview

OpenClaw connects to Telegram through the grammY framework — a modern, TypeScript-first Telegram Bot API library. The bot uses long-polling by default, which means it periodically asks the Telegram servers for new updates. This works out of the box with no extra setup. Alternatively, you can switch to webhook mode for production deployments. In webhook mode, Telegram pushes updates directly to your server endpoint, which is more efficient and reduces latency.
Long-polling works behind NATs and firewalls with no configuration. Webhook mode requires a publicly accessible HTTPS endpoint.
Store your bot token via the TELEGRAM_BOT_TOKEN environment variable or in your config under channels.telegram.botToken.

Creating Your Bot with @BotFather

BotFather is Telegram's official tool for creating and managing bots. Here's the step-by-step process: 1. Open Telegram and search for @BotFather 2. Send /newbot to start the creation process 3. Choose a display name for your bot (e.g., "My AI Assistant") 4. Choose a username ending in 'bot' (e.g., "my_ai_assistant_bot") 5. BotFather will give you an API token — save it securely After creation, you can customize your bot further with BotFather commands: • /setdescription — Set the bot's description shown in the profile • /setabouttext — Set the 'About' section text • /setuserpic — Upload a profile picture • /setprivacy — Toggle privacy mode for group messages
Keep your bot token secret. Anyone with the token can control your bot. If compromised, use /revoke in BotFather to generate a new one.

DM Policies

DM (Direct Message) policies control who can interact with your AI assistant in private chats. OpenClaw supports four policies: • pairing (default) — New users must go through a pairing flow. They send a message, receive a pairing code (valid for 1 hour), and you approve or deny via the CLI. Once approved, they can chat freely. • allowlist — Only numeric user IDs explicitly listed in allowFrom can message the bot. Everyone else is silently ignored. • open — Anyone who messages the bot gets a response. Use with caution in production. • disabled — DM functionality is completely turned off. The bot will not respond to any private messages.
openclaw.json 
{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",
      "allowFrom": [123456789, 987654321]
    }
  }
}
To find a user's numeric Telegram ID, you can use @userinfobot or check the Gateway logs when they message your bot.

Group Chat Management

OpenClaw supports Telegram group chats with flexible access control through two independent mechanisms: 1. Group allowlist — Decide which groups are allowed. Either all groups or only those listed in channels.telegram.groups. 2. Group policy — Control sender permissions within allowed groups: • open — Any group member can trigger the bot • allowlist — Only approved senders can interact • disabled — Group messages are completely ignored By default, bots require @mentions in groups. You can change this behavior: • Use the /activation always command (session-only) to respond to all messages • Set requireMention: false in config for persistent always-respond behavior
openclaw.json 
{
  "channels": {
    "telegram": {
      "groupPolicy": "open",
      "requireMention": false,
      "groups": ["-1001234567890"]
    }
  }
}
For forum-style groups (topics), OpenClaw isolates each topic using the thread ID and can apply per-topic configuration overrides.
For the bot to see all group messages without being an admin, you must disable privacy mode via /setprivacy in BotFather, then remove and re-add the bot to affected groups.

Message Formatting & Streaming

OpenClaw handles message formatting and delivery with several options: Formatting: Outbound text uses Telegram's HTML parser with automatic conversion from markdown-style formatting. If HTML parsing fails, messages are retried as plain text. Streaming: Draft bubbles support partial reply streaming in DMs with threaded topics enabled. Two modes available: • partial (default) — Progressive updates to a single message as the AI generates • block — Chunked updates sent as complete blocks Text chunks default to 4,000 characters (Telegram's limit). Enable chunkMode: "newline" to respect paragraph boundaries instead of hard-splitting.
openclaw.json 
{
  "channels": {
    "telegram": {
      "streamMode": "partial",
      "chunkMode": "newline"
    }
  }
}

Inline Buttons

OpenClaw supports Telegram's interactive inline keyboard buttons. When enabled, the AI can present buttons below messages for users to click. Clicking a button sends the callback data back to the agent as a formatted message. Available modes: • off — Buttons disabled (default) • dm — Enable in private chats only • group — Enable in group chats only • all — Enable everywhere • allowlist — Restricted by sender authorization
openclaw.json 
{
  "channels": {
    "telegram": {
      "capabilities": {
        "inlineButtons": "all"
      }
    }
  }
}

Stickers & Media

OpenClaw handles Telegram stickers and media files: Stickers: Static stickers are downloaded and processed through vision analysis. Descriptions are cached to avoid repeated API calls. Animated and video stickers skip processing. Agents can send stickers using stored file IDs and search cached stickers by description, emoji, or set name. Media: Media uploads and downloads cap at 5 MB by default. The bot supports sending and receiving images, documents, audio files, and video.
Enable the sticker action in your agent config to allow sending stickers via file ID or cached search.

Reactions

OpenClaw supports Telegram's reaction system for both receiving and sending emoji reactions: Incoming reactions generate system events prepended to agent context. You can configure which reactions trigger notifications: • off — No reaction notifications • own — Only reactions to bot messages • all — All reactions in the chat The bot can also send reactions. Configure the reaction capability level: • off — No reactions • ack — Acknowledgment reaction while processing (default) • minimal — Basic reactions • extensive — Full emoji range
openclaw.json 
{
  "channels": {
    "telegram": {
      "reactionNotifications": "own",
      "reactionLevel": "ack"
    }
  }
}

Commands & Tools

Native bot commands (like /status, /reset) are registered automatically with Telegram's bot command menu, making them easily discoverable by users. Custom commands can be added through config but function only as menu entries. The agent also supports tool actions: • Sending messages to specific chats • Reacting with emojis to messages • Deleting messages • Replying to specific messages using [[reply_to:<id>]] tags
Use [[reply_to_current]] in the agent response to reply directly to the user's current message.
Force voice note format by including [[audio_as_voice]] in replies or setting asVoice: true in tool calls.

Webhook Mode

For production deployments, webhook mode is recommended over long-polling. In webhook mode, Telegram pushes updates directly to your server, reducing latency and resource usage. To enable webhooks, set the webhookUrl and webhookSecret in your config. The local endpoint binds to 0.0.0.0:8787 by default.
openclaw.json 
{
  "channels": {
    "telegram": {
      "webhookUrl": "https://your-domain.com/telegram/webhook",
      "webhookSecret": "your-random-secret-string"
    }
  }
}
When switching from polling to webhook mode, the Gateway will automatically register the webhook URL with Telegram on startup.
Webhook mode requires a publicly accessible HTTPS endpoint. Make sure your server has a valid SSL certificate.

Telegram Configuration Reference

enabled
Type: boolean Default: true

Enable or disable the Telegram channel

botToken
Type: string Default: ""

Telegram Bot API token from @BotFather. Can also use TELEGRAM_BOT_TOKEN env var

dmPolicy
Type: string Default: "pairing"

Controls who can DM the bot. Options: pairing, allowlist, open, disabled

allowFrom
Type: number[] Default: []

Numeric Telegram user IDs allowed to message the bot (when dmPolicy is allowlist)

groupPolicy
Type: string Default: "allowlist"

Group chat policy. Options: disabled, open, allowlist

groups
Type: string[] Default: []

List of allowed group chat IDs. If empty and groupPolicy is not disabled, all groups are allowed

requireMention
Type: boolean Default: true

Whether the bot requires @mention to respond in groups

streamMode
Type: string Default: "partial"

Streaming mode for AI responses. Options: partial (progressive updates), block (chunked), off (disabled)

chunkMode
Type: string Default: "split"

How to handle long responses. Options: split (hard character limit), newline (respect paragraphs)

webhookUrl
Type: string Default: ""

HTTPS URL for webhook mode. If set, switches from polling to webhook

webhookSecret
Type: string Default: ""

Secret token for webhook verification

reactionNotifications
Type: string Default: "off"

Which reactions trigger notifications. Options: off, own, all

reactionLevel
Type: string Default: "ack"

Bot reaction capability. Options: off, ack, minimal, extensive

capabilities.inlineButtons
Type: string Default: "off"

Inline button mode. Options: off, dm, group, all, allowlist

configWrites
Type: boolean Default: true

Auto-migrate chat IDs during supergroup upgrades. Set to false to disable

mediaCap
Type: number Default: 5

Maximum media file size in MB for uploads and downloads

historyLimit
Type: number Default: 50

Maximum number of history messages to retain per user/group conversation

retryPolicy
Type: object Default: { "maxRetries": 3, "backoff": "exponential" }

Retry policy with exponential backoff for failed API calls

proxyUrl
Type: string Default: ""

Proxy URL for Telegram API calls. Useful for restricted network environments

forceIPv4
Type: boolean Default: false

Force IPv4 resolution for api.telegram.org. Enable if IPv6 egress causes silent failures

Telegram Frequently Asked Questions

Telegram Troubleshooting

Bot ignores non-mention messages in groups

Privacy mode is enabled by default in Telegram bots. When active, the bot only receives messages that @mention it or start with a slash command.

Disable privacy mode in BotFather: send /setprivacy to @BotFather, select your bot, and choose 'Disable'. Then remove the bot from the group and add it back. Also set requireMention: false in your OpenClaw config if you want the bot to respond to all messages.
Bot is not responding to any messages

The bot token may be incorrect, the Gateway may not be running, or there's a network connectivity issue.

Verify the bot token is correct by testing with the Telegram Bot API directly: curl https://api.telegram.org/bot<token>/getMe. Check Gateway logs for connection errors. For IPv6 routing issues causing silent failures, force IPv4 resolution for api.telegram.org or verify DNS returns working addresses.
Webhook is not receiving updates

The webhook URL is not publicly accessible, SSL certificate is invalid, or the webhook was not registered properly.

Verify the webhook URL is accessible from the internet (test with curl). Ensure your SSL certificate is valid and not self-signed. Check the webhook status with: curl https://api.telegram.org/bot<token>/getWebhookInfo. Restart the Gateway to re-register the webhook.
Messages are being truncated or split incorrectly

Telegram has a 4,000-character message limit. Long AI responses are automatically chunked.

Set chunkMode to 'newline' to split at paragraph boundaries instead of hard character limits. You can also adjust the maximum text chunk size in your config.
View Full Documentation Back to All Channels

Related Channels

WhatsApp

Medium

Connect OpenClaw via QR code using Baileys protocol

Setup Guide

Discord

Easy

OpenClaw bot integration using discord.js

Setup Guide

Signal

Hard

OpenClaw privacy-focused connection via signal-cli

Setup Guide