Telegram Setup

Complete guide to connecting Telegram with OpenClaw

New to channel setup? For a hands-on, step-by-step tutorial, check out our Channel Setup Tutorial. This page is a comprehensive reference covering all Telegram features and configuration options.

Telegram is a popular messaging platform with excellent bot support. OpenClaw connects to Telegram using the Bot API via grammY, providing DMs, groups, and rich media support.

Streaming & status (2026.2.21): Preview streaming is configured via a single boolean channels.telegram.streaming (legacy streamMode values are auto-mapped). You can enable configurable lifecycle status reactions (queued/thinking/tool/done/error) with emoji and timing overrides, shared with Discord. For cron and heartbeat, explicit topic targets (<chatId>:topic:<threadId>) are honored so scheduled sends land in the configured topic.

Quick Setup

Setting up Telegram requires creating a bot with BotFather:

  1. Create bot with @BotFather
  2. Get your bot token
  3. Configure in OpenClaw
  4. Start chatting!

Creating a Telegram Bot

Step 1: Talk to BotFather

  1. Open Telegram
  2. Search for @BotFather
  3. Start a chat

Step 2: Create Bot

  1. Send: /newbot
  2. Choose a name for your bot
  3. Choose a username (must end in 'bot')
  4. Copy the bot token

Step 3: Configure Bot

Optional: Set bot description and commands:

  • /setdescription - Set bot description
  • /setcommands - Set bot commands

Configuring OpenClaw

Basic Configuration

Telegram Config 
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN_HERE"
    }
  }
}

Setting Token

Add your bot token:

  1. Get token from BotFather
  2. Add to configuration file
  3. Or set via environment variable: TELEGRAM_BOT_TOKEN

Telegram Features

Direct Messages

  • Send and receive DMs
  • Rich media support
  • Voice notes
  • Location sharing
  • Reply threading

Group Chats

  • Join group chats
  • Mention-based activation (default)
  • Group allowlists
  • Reply tags
  • Photo albums
  • Send polls via the CLI: openclaw message poll (duration, silent delivery, anonymity options)

Media Support

  • Images and photos
  • Audio and voice notes
  • Video files
  • Documents
  • Stickers
  • Location sharing

Advanced Configuration

DM Allowlist

Allowlist Config 
{
  "channels": {
    "telegram": {
      "allowFrom": ["@username", "123456789"]
    }
  }
}

Group Configuration

Group Config 
{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        },
        "-1001234567890": {
          "requireMention": false,
          "activation": "always"
        }
      }
    }
  }
}

Per-topic routing (forum groups)

In Telegram forum groups, you can route each topic to a different agent so each topic has its own session, workspace, and memory. That keeps daily briefs, alerts, support, and content in separate “rooms” instead of one mixed thread.

Topics → agentId 
{
  "channels": {
    "telegram": {
      "groups": {
        "-100xxxxxxxxxx": {
          "topics": {
            "daily-brief": { "agentId": "nexus" },
            "radar": { "agentId": "scout" },
            "content": { "agentId": "quill" },
            "runtime": { "agentId": "forge" },
            "support": { "agentId": "guide" }
          }
        }
      }
    }
  }
}

Replace the group ID and topic names with your forum’s IDs and topic slugs. Each topic gets its own agent and session.

Security & Pairing

DM Pairing

By default, unknown senders require pairing:

  • Unknown contacts receive a pairing code
  • Approve with: openclaw pairing approve telegram <code>
  • Once approved, added to allowlist

Bot Token Security

Keep your bot token secure:

  • Never share your token
  • Store in configuration file (not in code)
  • Use environment variables if needed
  • Regenerate token if compromised

Troubleshooting Telegram

Bot Not Responding

If bot doesn't respond:

  1. Verify bot token is correct
  2. Check Gateway is running
  3. Check bot is enabled in config
  4. Review Gateway logs

Can't Receive Messages

If messages aren't received:

  1. Check allowlist configuration
  2. Verify pairing if required
  3. Check bot permissions
  4. Ensure bot is added to groups

Group Issues

If group features don't work:

  1. Ensure bot is added to group
  2. Check group allowlist
  3. Verify mention patterns
  4. Check group ID format

Best Practices

  • Use Allowlists - Control who can message you
  • Enable Mention Gating - For group chats
  • Secure Token - Keep bot token private
  • Monitor Logs - Check for issues
  • Test Thoroughly - Test in DMs before groups

Related guides