How to integrate OpenClaw with Telegram?

Clawpedia · For Humans

Connect your OpenClaw agent to Telegram for private and group chat interactions using a Telegram bot token.

How to Integrate OpenClaw with Telegram?

Telegram is one of the easiest platforms to connect with OpenClaw thanks to its excellent Bot API. In just a few minutes, you can set up a Telegram bot powered by your OpenClaw agent and chat with it from any device.

---

Why Telegram?

---

Step 1: Create a Telegram Bot

• Open Telegram and search for @BotFather
• Send /newbot
• Choose a name (e.g., "My OpenClaw Agent")
• Choose a username (must end in bot, e.g., my_openclaw_bot)
• Copy the bot token BotFather gives you

BotFather: Done! Your bot is created.
Token: 7123456789:AAF-1234567890abcdefghij

Important: Keep your bot token secret. Anyone with it can control your bot.

---

Step 2: Connect to OpenClaw

openclaw connect telegram --token 7123456789:AAF-1234567890abcdefghij

Or add it to your config:

# ~/.openclaw/config.yaml
platforms:
  telegram:
    enabled: true
    token: "7123456789:AAF-1234567890abcdefghij"

Start the Gateway

openclaw gateway start

---

Step 3: Test Your Bot

• Open Telegram
• Search for your bot username (e.g., @my_openclaw_bot)
• Press Start
• Send a message

You should receive a response from your OpenClaw agent.

---

Configuration Options

platforms:
  telegram:
    enabled: true
    token: "YOUR_BOT_TOKEN"
    
    # Behavior
    typing_indicator: true      # Show "typing..." animation
    parse_mode: "Markdown"      # Markdown or HTML formatting
    max_message_length: 4096    # Telegram limit
    split_long_messages: true   # Auto-split long responses
    
    # Access control
    allowed_users:              # Restrict access (optional)
      - 123456789               # Telegram user IDs
      - 987654321
    allowed_groups:             # Restrict group access
      - -1001234567890
    
    # Features
    voice_transcription: true   # Transcribe voice messages
    image_analysis: true        # Analyze photos with vision models
    document_processing: true   # Process sent documents
    inline_mode: false          # Enable @bot inline queries

---

Features

Text Messages

OpenClaw responds with formatted Markdown:

You: What is the Fibonacci sequence?
Bot: The **Fibonacci sequence** is a series where each number 
     is the sum of the two preceding ones:
     
     `0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...`
     
     Formula: F(n) = F(n-1) + F(n-2)

Voice Messages

Send a voice message → OpenClaw transcribes it, processes the text, and replies:

You: 🎤 "Remind me to buy groceries at 6 PM"
Bot: ✅ Reminder set for 6:00 PM: Buy groceries

Photo Analysis

Send a photo with a caption or question:

You: 📷 [photo of a meal] "How many calories is this roughly?"
Bot: Based on what I can see (grilled chicken, rice, vegetables), 
     this meal is approximately 450-550 calories.

Document Processing

Send PDF, Word, or text files for analysis:

You: 📄 [report.pdf] "Summarize the key findings"
Bot: Key findings from the report:
     1. Revenue grew 12% year-over-year...

Bot Commands

Set up custom commands via BotFather (/setcommands):

help - Show available commands
status - Check OpenClaw status
memory - View stored memories
clear - Clear conversation context
model - Show or change AI model

Inline Buttons

OpenClaw can send interactive buttons for choices:

Bot: Which format would you like?
[📝 Summary] [📊 Detailed] [📋 Bullet Points]

---

Group Chat Setup

Adding the Bot to a Group

• Add your bot to a Telegram group
• The bot responds when mentioned: @my_openclaw_bot what time is it?
• Or configure it to respond to all messages:

platforms:
  telegram:
    group_mode: mention_only   # or "all_messages"
    group_reply_to_message: true

Privacy Mode

By default, Telegram bots only see messages directed at them in groups. To change:

• Message @BotFather
• Send /setprivacy
• Select your bot
• Choose Disable (bot sees all messages)

---

Advanced: Webhook Mode

For production deployments, use webhooks instead of polling:

openclaw connect telegram \
  --token YOUR_TOKEN \
  --mode webhook \
  --webhook-url https://openclaw.yourdomain.com/webhook/telegram

Webhook advantages:

• More efficient than polling
• Lower latency
• Better for high-traffic bots

---

Security

Restrict Access

Find your Telegram user ID:

You: /whoami
Bot: Your Telegram user ID is: 123456789

Then restrict access:

platforms:
  telegram:
    allowed_users:
      - 123456789

Rate Limiting

security:
  rate_limit: 20              # Max messages per minute per user
  block_after_exceeded: 60    # Block for 60 seconds

---

Troubleshooting

Bot Not Responding

• Check gateway: openclaw gateway status
• Verify token: openclaw config get platforms.telegram.token
• Check logs: openclaw logs --filter telegram
• Test token: curl https://api.telegram.org/botYOUR_TOKEN/getMe

"Conflict: terminated by other getUpdates"

Another instance is polling. Stop it:

openclaw gateway stop
openclaw gateway start

Messages Arrive Late

• Switch to webhook mode for lower latency
• Use a faster AI model
• Check your server's internet connection

Bot Can't See Group Messages

Disable privacy mode via @BotFather → /setprivacy → Disable

---

Customizing Your Bot

Set Description and Avatar

Via BotFather:

• /setdescription — what users see before starting
• /setabouttext — bio/about section
• /setuserpic — bot avatar image

Welcome Message

platforms:
  telegram:
    welcome_message: "👋 Hi! I'm your OpenClaw assistant. Ask me anything!"

---

Summary

Telegram is the easiest messaging platform to connect with OpenClaw — create a bot with @BotFather, paste the token, and start chatting. With support for voice, images, documents, group chats, and inline buttons, your Telegram bot becomes a versatile AI assistant accessible from any device.