Step-by-Step Fix
1. Check the OpenClaw Run Log for the Telegram Error
In the OpenClaw dashboard, open the failing run and find the Telegram send step in the log. Look for the API response:
{"ok": false, "error_code": 401, "description": "Unauthorized"}
or
{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}
The error_code and description fields tell you exactly what Telegram rejected.
2. Verify Your Bot Token
Go to Telegram and open BotFather (@BotFather):
- Type
/mybotsand select your bot from the list - Select API Token to see if the token is active
- If revoked or compromised, select Revoke API token to generate a new one
- Copy the new token in the format
123456789:ABCdefGHI...
Update the token in OpenClaw:
- Go to your workflow settings > Environment Variables
- Update
TELEGRAM_BOT_TOKENwith the new token - Save the workflow
3. Verify the Chat ID
Wrong chat IDs are a common silent failure — Telegram returns 400 Bad Request without a clear explanation.
To find the correct chat ID:
For private chats:
- Forward a message from the user to @userinfobot on Telegram — it returns the user's numeric ID
For groups:
- Add @RawDataBot or @userinfobot to the group temporarily
- Send any message in the group — the bot replies with the group's chat ID (a negative number like
-987654321)
For channels:
- The channel chat ID starts with
-100followed by the channel's numeric ID - Example: if your channel's invite link references
joinchannel/xyz123, the ID is found by using the @username format
Update TELEGRAM_CHAT_ID in OpenClaw with the correct numeric value, including the negative sign for groups and channels.
4. Confirm the Bot Has the Right Permissions
The bot must be:
- Added to the target group/channel: If you recently created the bot or the target group, ensure the bot was explicitly added
- Granted posting permissions in channels: Open the channel info, go to Administrators, and confirm your bot is listed as an admin with Post Messages permission enabled
- Not blocked by the recipient: In private chats, if the user blocked the bot, the API returns 403 Forbidden
To test that the bot can reach the chat, send a test message using curl:
curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
-d "chat_id=$TELEGRAM_CHAT_ID&text=Test+from+OpenClaw"
A successful response shows "ok": true and the message details.
5. Handle Rate Limit Errors (429)
If the run log shows a 429 error with retry_after: N, your automation is sending messages too quickly. Fix by adding delays in your agent:
- Between messages to the same chat: Add a 3-second delay (minimum) between Telegram send calls
- Batch sending: If sending to multiple chats, space calls by at least 50ms each (for the 30/second global limit)
In your OpenClaw workflow, add a sleep step between Telegram send operations or configure a message queue that spaces out delivery.
6. Handle Markdown Formatting Errors
If your message body contains Markdown but Telegram's API expects plain text (or vice versa), the delivery will fail with a 400 error. Check your send call's parse_mode parameter:
- Use
parse_mode=MarkdownV2for Markdown-formatted messages - Escape special characters:
.,!,-,(,)must be prefixed with\in MarkdownV2 - Use
parse_mode=HTMLif you prefer HTML formatting - Omit
parse_modeentirely for plain text messages
7. Check for Service-Level Issues
If all configuration appears correct but delivery still fails, check Telegram's status at telegram.org or on their official Twitter account. Telegram experiences occasional API outages that affect bot delivery. Also check OpenClaw's status page for any outbound network issues in their infrastructure that could block calls to Telegram's API.
Why This Happens
OpenClaw runs agent workflows in containers with outbound internet access, but each container starts without pre-configured Telegram credentials. The bot token and chat ID must be explicitly provided as environment variables in your workflow, as there is no shared credential store between your local environment and the OpenClaw worker. Rate limit failures occur when automation sends messages faster than Telegram allows — Telegram's limits are enforced per bot and per chat, not per server IP, so distributing your requests across multiple servers does not help.
Common Mistakes to Avoid
- Using a group invite link as the chat ID: The chat ID is a numeric value, not a link or username. Use @RawDataBot or @userinfobot to get the correct numeric ID.
- Not adding the bot to the target group/channel before testing: A bot must be a member of (and an admin in) any group or channel it sends messages to. Simply creating the bot does not grant it access to your existing chats.
- Hardcoding the bot token in the agent script: Use environment variables for the token so you can rotate it without editing your agent's code.
- Using MarkdownV2 without escaping special characters: In Telegram's MarkdownV2 mode, unescaped
.,!, and-in message text cause a 400 parse error that looks like a delivery failure.
FAQ
Q: Can I send Telegram messages to multiple chats from a single OpenClaw run?
Yes. A single bot can send messages to multiple chats, groups, or channels in one run. Each sendMessage call is independent and requires its own chat ID. Store each target chat ID as a separate environment variable (e.g., TELEGRAM_CHAT_ID_ALERTS, TELEGRAM_CHAT_ID_REPORTS) and loop through them in your agent. Be aware of Telegram's global rate limit of 30 messages per second across all chats — add spacing between calls to avoid 429 errors.
Q: My Telegram bot worked for weeks and then suddenly stopped. What changed?
Sudden failures in a previously working bot usually have one of three causes: the bot was removed from a group or channel by another admin, the bot token was manually revoked in BotFather (someone on your team may have done this), or Telegram's API had a format change that affects how your agent constructs the request. Check BotFather first (/mybots → API Token) to confirm the token is active. Then verify the bot is still a member of the target group by opening the group info in Telegram.
Q: How do I send rich media (images, documents) via Telegram in OpenClaw?
Use the sendPhoto or sendDocument API endpoints instead of sendMessage. For sendPhoto, pass the image as a URL (if publicly accessible) or as a multipart form upload. The request structure is similar to sendMessage but uses the photo or document parameter instead of text. Make sure your parse_mode is not set when sending media-only messages, as some Telegram clients will reject media with an invalid parse_mode for the file type. Test with a simple curl command in a bash step before integrating into your full agent flow.
Related Issues
- OpenClaw cron job failing – find logs and root cause
- OpenClaw agent not responding – stuck run
- OpenClaw tool calls failing – timeouts and not available
- OpenClaw rate limits affecting runs
Additional FAQ
Q: What is the fastest way to diagnose a login problem? The fastest diagnostic is to open an incognito or private browser window and attempt to sign in there. Incognito windows run without extensions and use fresh cookies, which isolates the two most common causes: a browser extension interfering with authentication, or corrupted session cookies. If login works in incognito, the issue is your main browser profile. If it still fails, the problem is your network, your account, or a platform-side incident.