How to Connect Telegram to OpenClaw

Open Telegram and search for '@BotFather' — this is Telegram's official bot for creating and managing other bots. Start a chat and send the `/newbot` command. BotFather will ask for two things: a display name for your bot (this is what people see in chats, can include spaces, e.g., 'OpenClaw Assistant') and a username (must end in 'bot', no spaces, e.g., 'openclaw_assistant_bot'). Once you provide both, BotFather replies with your bot token in this format: `1234567890:AABBCCDDEEFF-gghhiijjkk_llmmnnoo`. Copy the entire token — this is your TELEGRAM_BOT_TOKEN. It functions as both the bot's identity and authentication credential. Store it securely and never post it publicly. While in BotFather, configure a few optional but useful settings: - `/setdescription` — sets the 'What can this bot do?' text users see before starting - `/setcommands` — registers command suggestions (e.g., `/help`, `/status`, `/ask`) so Telegram shows them as autocomplete options - `/setprivacy` — by default bots only see messages that mention them in groups. Set to DISABLED if you want the bot to see all group messages (needed for keyword triggers).

1# Your Telegram bot token format:
2# TELEGRAM_BOT_TOKEN=1234567890:AABBCCDDEEFF-gghhiijjkk_llmmnnoo
3
4# Verify your token works:
5curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
6
7# Expected response:
8# {"ok": true, "result": {"id": 1234567890, "is_bot": true, "first_name": "OpenClaw Assistant", "username": "openclaw_assistant_bot"}}
9
10# Get your own chat ID (send any message to your bot first, then run):
11curl "https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates"

Open OpenClaw's config file at `~/.openclaw/config.yaml` and add the Telegram integration block under the `integrations` key. The `bot_token` field takes your full TELEGRAM_BOT_TOKEN from BotFather. The `update_method` field controls how OpenClaw receives incoming messages: `polling` (OpenClaw repeatedly calls getUpdates to fetch new messages — works anywhere, no public URL needed) or `webhook` (Telegram pushes events to your OpenClaw server in real time — requires a public HTTPS URL). For the `polling` method, `poll_interval` sets how frequently OpenClaw checks for new updates in seconds. A value of 5-10 seconds gives near-real-time responsiveness for most use cases. The `timeout` field sets the long-polling timeout — using a longer value (like 30) means Telegram holds the connection open for up to 30 seconds waiting for new messages, which is more efficient than frequent short polls. The optional `allowed_chats` list restricts OpenClaw to specific chat IDs. Include your personal chat ID for testing, or leave it empty to respond to any chat the bot is added to.

1# ~/.openclaw/config.yaml
2integrations:
3  telegram:
4    bot_token: "YOUR_TELEGRAM_BOT_TOKEN"
5    update_method: polling      # Options: polling | webhook
6    poll_interval: 1            # Seconds between getUpdates calls (use with short timeout)
7    timeout: 30                 # Long-polling timeout in seconds (recommended)
8    allowed_chats:              # Optional: restrict to specific chat IDs
9      - 123456789               # Your personal chat ID
10      - -1001234567890          # Group chat IDs are negative numbers
11    parse_mode: HTML            # Default message formatting: HTML | Markdown | MarkdownV2
12    command_prefix: "/"         # Telegram conventional command prefix

Before building automation, confirm that OpenClaw can successfully send a message to a Telegram chat. The Telegram Bot API's `sendMessage` endpoint takes a `chat_id` and a `text` parameter — this is all you need for basic text messaging. For your first test, use your personal chat ID to send yourself a message. This confirms the bot token is valid and the chat_id is correct without needing a group setup. Telegram supports HTML and Markdown formatting in messages. Using `parse_mode=HTML`, you can include `<b>bold</b>`, `<i>italic</i>`, `<code>code</code>`, and `<a href="URL">links</a>` in messages. This is particularly useful for formatting OpenClaw-generated summaries, alerts, and reports. If the sendMessage call returns `{"ok": true}`, the message was delivered. If you see `{"ok": false}`, check the description field for the specific error — most commonly this is an invalid chat_id or the bot not being started by the user.

1# Test sending a message to yourself:
2curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage" \
3  -H "Content-Type: application/json" \
4  -d '{"chat_id": YOUR_CHAT_ID, "text": "Hello from OpenClaw! Integration is working."}'
5
6# Test with HTML formatting:
7curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage" \
8  -H "Content-Type: application/json" \
9  -d '{
10    "chat_id": YOUR_CHAT_ID,
11    "text": "<b>OpenClaw Status</b>\n\nBot is <i>online</i> and ready.\n\n<code>TELEGRAM_BOT_TOKEN</code> configured.",
12    "parse_mode": "HTML"
13  }'
14
15# Send to a group (note the negative chat_id):
16curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage" \
17  -H "Content-Type: application/json" \
18  -d '{"chat_id": -1001234567890, "text": "Bot connected to this group."}'

Now set up OpenClaw to receive and respond to incoming Telegram messages. With polling configured, OpenClaw fetches updates from the `getUpdates` endpoint and processes each message event. Telegram delivers updates as a JSON array. Each update contains an `update_id` (for deduplication), a `message` or `callback_query` or `inline_query` depending on the type, and within `message` you have `chat.id`, `from.id`, `text`, and `date`. Configure OpenClaw workflows to act on these incoming events. The most common pattern is a command handler: when a message starts with `/ask`, extract the rest of the text as a question, pass it to OpenClaw's AI, and reply with `sendMessage` back to the same `chat_id`. For groups, ensure you have set BotFather's privacy mode to DISABLED (using `/setprivacy` in BotFather) if you want the bot to see all messages — by default, bots in groups only receive messages that mention them directly or start with a slash command.

1# Sample getUpdates response structure (for understanding the data format):
2# {
3#   "ok": true,
4#   "result": [{
5#     "update_id": 123456789,
6#     "message": {
7#       "message_id": 42,
8#       "from": {"id": 987654321, "first_name": "Alice"},
9#       "chat": {"id": 987654321, "type": "private"},
10#       "date": 1709123456,
11#       "text": "/ask What is the weather in London?"
12#     }
13#   }]
14# }
15
16# ~/.openclaw/config.yaml — command handling workflow
17workflows:
18  telegram-command-handler:
19    trigger:
20      integration: telegram
21      event: message
22      conditions:
23        - field: message.text
24          starts_with: "/ask"
25    actions:
26      - type: ai-response
27        prompt: "Answer this question concisely: {{trigger.message.text | remove_prefix('/ask ')}}"
28      - type: integration-call
29        integration: telegram
30        endpoint: /sendMessage
31        method: POST
32        body:
33          chat_id: "{{trigger.message.chat.id}}"
34          text: "{{ai-response.output}}"
35          parse_mode: HTML
36          reply_to_message_id: "{{trigger.message.message_id}}"

Polling works well for most use cases, but if you need truly real-time message delivery (sub-second response time) and you have a server with a public HTTPS URL, webhooks are more efficient — Telegram pushes each update to your endpoint the moment it arrives rather than waiting for the next poll cycle. To use webhooks: your OpenClaw server must be accessible at a public HTTPS URL (self-signed certificates are not supported — use Let's Encrypt or a reverse proxy like Cloudflare Tunnel). Register your webhook URL with Telegram using the `setWebhook` API call. Telegram will then POST each update to that URL in real time. Only one update delivery method can be active at a time. If you call `setWebhook`, polling (`getUpdates`) stops working. To switch back to polling, call `deleteWebhook` first. For most personal and small-team setups, polling with a 30-second timeout is equivalent to webhooks in practice. RapidDev recommends polling unless you are building a production bot that handles hundreds of messages per minute.

1# Register webhook (run once — Telegram stores this):
2curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://your-openclaw-server.com/telegram/webhook",
6    "secret_token": "optional-secret-for-verification",
7    "allowed_updates": ["message", "callback_query"]
8  }'
9
10# Verify webhook is registered:
11curl "https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo"
12
13# Remove webhook (to switch back to polling):
14curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook"
15
16# Update ~/.openclaw/config.yaml for webhook mode:
17# integrations:
18#   telegram:
19#     bot_token: "YOUR_TOKEN"
20#     update_method: webhook
21#     webhook_path: /telegram/webhook
22#     webhook_secret: optional-secret-for-verification