OpenClaw Telegram Setup: Complete Guide

Telegram is the most popular first channel for OpenClaw — and for good reason. The setup takes 5 minutes, the bot API is generous, and Telegram's features (inline buttons, voice messages, file sharing, groups) make it ideal for AI agent interaction. This guide covers everything from initial setup to advanced features.

Why Telegram First?

Compared to other channels:

• Fastest setup — Bot creation takes 2 minutes via @BotFather
• No business verification — Unlike WhatsApp, no Meta Business verification needed
• Rich features — Inline buttons, reactions, voice messages, file sharing, formatting
• No rate limits — Generous API limits for personal use
• Cross-platform — Works on mobile, desktop, and web

Step 1: Create Your Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Choose a display name (e.g., "My Agent")
4. Choose a username (must end in "bot", e.g., my_agent_bot)
5. BotFather gives you a token like: 7123456789:AAH...
6. Save this token securely — it's the key to your bot

Configure Bot Settings in BotFather

Before connecting to OpenClaw, set these in BotFather:

For group usage, also set:

Step 2: Connect to OpenClaw

That's it. Open Telegram, find your bot, and send a message. Your OpenClaw agent will respond using whatever AI model and personality you've configured.

Step 3: Test Basic Functionality

Send these test messages to verify everything works:

1. "Hello" — Verify basic response
2. "Tell me about yourself" — Verify SOUL.md is loaded
3. "Search the web for today's weather" — Verify skill access
4. Send a photo — Verify image handling
5. Send a voice message — Verify voice transcription

Setting Up for Group Chats

OpenClaw agents work beautifully in Telegram groups, but you need to configure behavior carefully:

Adding the Bot to a Group

1. Open the group → Add members → Search for your bot username
2. Grant the bot appropriate permissions (at minimum: send messages)
3. If you disabled privacy mode in BotFather, the bot sees all messages

Configuring Group Behavior

In your SOUL.md, add rules for group behavior:

Without these rules, your agent might respond to every message, which quickly becomes annoying in active groups. The key principle: in groups, your agent should behave like a considerate human participant — speaking when relevant, silent when not.

Advanced Telegram Features

Inline Buttons

OpenClaw supports Telegram's inline keyboard buttons. Your agent can present choices, confirmations, and navigation options as tappable buttons below messages. This is especially useful for:

• Approval workflows ("Approve | Reject | Defer")
• Quick responses ("Yes | No | More details")
• Navigation ("Next page | Previous page")
• Batch content review

Voice Messages

OpenClaw handles voice in both directions:

• Receiving: Voice messages sent to the bot are transcribed to text and processed normally
• Sending: Using the TTS skill, your agent can respond with voice messages — perfect for morning briefings or hands-free interaction

File and Media Handling

Your agent can receive and process:

• Photos and images (with vision analysis)
• Documents (PDF, text files, etc.)
• Voice messages and audio files
• Location shares

It can also send back:

• Generated images
• Audio messages (TTS)
• Documents and files from the workspace
• Formatted messages with markdown

Reactions

OpenClaw can send emoji reactions to messages. This is especially useful in group contexts where a simple reaction (👍, ✅, 🤔) is more appropriate than a full text response.

Telegram-Specific Tips

Message Formatting

Telegram supports markdown formatting, and OpenClaw takes advantage of it. Your agent's responses will include bold, italic, code blocks, and links when appropriate. If formatting looks broken, ensure your agent's model is outputting valid Telegram-compatible markdown.

Message Length

Telegram has a 4,096-character message limit. OpenClaw automatically splits longer responses into multiple messages. If your agent tends toward very long responses, add a brevity rule to SOUL.md.

Notification Management

If your agent sends proactive messages (morning briefings, alerts), consider:

• Using silent messages for non-urgent notifications
• Bundling multiple updates into single messages
• Configuring notification times to respect your sleep schedule

Troubleshooting

Bot Doesn't Respond

1. Check gateway status: openclaw gateway status
2. Check gateway logs: openclaw gateway logs
3. Verify the bot token is correct
4. Make sure you're messaging the right bot
5. Check if the AI model API key is valid

Bot Doesn't See Group Messages

By default, Telegram bots can only see /commands in groups. To see all messages:

1. Message @BotFather
2. Send /setprivacy
3. Select your bot
4. Choose Disable

Note: You may need to remove and re-add the bot to the group after changing this setting.

Slow Responses

Response time depends on your AI model provider's latency. If responses are consistently slow:

• Try a faster model (Haiku or Sonnet instead of Opus)
• Check your internet connection to the API provider
• Reduce context size (shorter SOUL.md, fewer memory files loaded)

Frequently Asked Questions