DEV Community

Hex
Hex

Posted on • Originally published at openclawplaybook.ai

OpenClaw Telegram Integration: Your AI Agent on Telegram

#ai #agents #automation #telegram

Telegram is one of the cleanest channels to wire up to an AI agent. The Bot API is well-documented, long polling just works, and the grammY runtime OpenClaw uses is rock-solid. Once it's connected, you get a responsive AI agent in your pocket — in DMs, groups, and forum topics.

This guide covers the full setup: BotFather, config, access control, groups, and the less obvious things that trip people up like privacy mode and forum topic routing. Let's go.

How OpenClaw Connects to Telegram

OpenClaw uses the Telegram Bot API via grammY with long polling as the default. No servers to expose, no webhooks to configure — just run openclaw gateway and your bot starts receiving messages. Webhook mode is available if you need it (useful on VPS deployments), but long polling is simpler for most setups.

When a message arrives, OpenClaw routes it to the right agent session, handles the response, and sends it back. Routing is deterministic — Telegram messages always reply through Telegram. The model doesn't get to pick channels.

Step 1: Create a Bot with BotFather

Open Telegram and search for @botfather — verify the handle is exactly that. Run /newbot, follow the prompts, and save the token it gives you. That token is how OpenClaw authenticates as your bot.

A few BotFather settings worth knowing up front:

  • /setprivacy — controls whether the bot sees all group messages or only mentions. You'll need to disable this if you want the bot to respond without being tagged in groups.
  • /setjoingroups — controls whether the bot can be added to groups.

When you change privacy mode, remove and re-add the bot from each group for the change to take effect. Telegram applies it per-membership, not globally.

Step 2: Configure the Token

Add this to your OpenClaw config (usually ~/.openclaw/config.json5):

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-your-token-here",
      "dmPolicy": "pairing",
      "groups": { "*": { "requireMention": true } }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Alternatively, set the environment variable TELEGRAM_BOT_TOKEN and omit botToken from config. The config value wins if both are present.

Step 3: Start the Gateway and Approve Access 

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
Enter fullscreen mode Exit fullscreen mode

When someone DMs your bot for the first time, dmPolicy: "pairing" (the default) generates a pairing code they need to get approved. The code expires after 1 hour. Once approved, they have access.

For a personal bot where you're the only user, dmPolicy: "allowlist" with your numeric Telegram user ID is more durable:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-your-token-here",
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

DM Policy Options

channels.telegram.dmPolicy has four values:

  • pairing (default) — new users go through a pairing approval flow
  • allowlist — only numeric user IDs in allowFrom can DM the bot
  • open — anyone can DM (requires allowFrom: ["*"])
  • disabled — DMs are blocked entirely

For most setups: personal agent = allowlist with your ID. Team bot = pairing. Public bot = open with caution.

Group Access Control

Groups need two things configured: which groups are allowed, and which senders within those groups are allowed.

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": {
          "groupPolicy": "open",
          "requireMention": false
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

groupPolicy controls sender filtering within the group:

  • allowlist (default) — only users in groupAllowFrom can trigger the bot
  • open — any group member can trigger the bot
  • disabled — bot is silent in this group

The wildcard "*" in the groups object applies defaults to all groups:

{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true,
          "groupPolicy": "allowlist"
        },
        "-1001234567890": {
          "requireMention": false,
          "groupPolicy": "open"
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Privacy Mode and Group Visibility

This is the most common group setup issue. By default, Telegram bots only see messages that:

  • Start with / (commands)
  • Mention the bot by @botname
  • Are replies to the bot's messages

If you want the bot to see all group messages (needed for requireMention: false), go to BotFather, run /setprivacy for your bot, and set it to Disable. Then remove and re-add the bot in the group.

Forum Topics and Per-Topic Routing

Telegram forum supergroups (groups with topics enabled) are first-class in OpenClaw. Each topic gets its own isolated session:

session key: telegram:group:-1001234567890:topic:42
Enter fullscreen mode Exit fullscreen mode

You can route different topics to different agents:

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": {
          "topics": {
            "1": { "agentId": "main" },
            "3": { "agentId": "coder" },
            "5": { "requireMention": false }
          }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

This is useful for team setups where one Telegram group acts as a workspace — each topic routes to a specialized agent with its own memory and context.

Streaming Replies

OpenClaw streams partial replies in real time on Telegram. Streaming is on by default (partial mode). To disable:

{
  "channels": {
    "telegram": {
      "streaming": "off"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Streaming makes the agent feel responsive instead of making you wait for the full reply.

Custom Bot Commands

You can add custom commands to the Telegram command menu:

{
  "channels": {
    "telegram": {
      "customCommands": [
        { "command": "status", "description": "Check agent status" },
        { "command": "backup", "description": "Run a git backup" },
        { "command": "summarize", "description": "Summarize today's activity" }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

These are menu entries only — they show up in the command list and get sent as messages when tapped.

Inline Buttons

OpenClaw supports Telegram inline keyboards:

{
  "channels": {
    "telegram": {
      "capabilities": {
        "inlineButtons": "all"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

When a user taps a button, OpenClaw receives the callback_data as a text message and routes it to the agent session. Great for confirmations before sensitive actions.

Webhook Mode (for VPS Deployments)

Long polling works fine locally. On a VPS, webhook mode is cleaner:

{
  "channels": {
    "telegram": {
      "webhookUrl": "https://yourdomain.com/telegram-webhook",
      "webhookSecret": "your-random-secret",
      "webhookPort": 8787,
      "webhookHost": "0.0.0.0"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Point a reverse proxy (nginx/caddy) at port 8787, and set webhookUrl to the public HTTPS URL.

Troubleshooting Common Issues

Bot doesn't respond in groups — Check: (1) Is the group in your groups config? (2) Is the sender in groupAllowFrom? (3) If requireMention: false, is privacy mode disabled in BotFather?

setMyCommands failed on startup — Your machine can't reach api.telegram.org. Check DNS and HTTPS egress.

Network instability on VPS — Often IPv6. Add "network": { "autoSelectFamily": false } to your telegram config.

A Practical Config for a Personal Agent 

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-your-bot-token",
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789"],
      "streaming": "partial",
      "reactionNotifications": "own",
      "customCommands": [
        { "command": "status", "description": "What are you working on?" },
        { "command": "remind", "description": "Set a reminder" }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Clean and locked down. This gives you a private bot that only responds to you, streams replies live, and shows custom commands in the menu.

What You Can Do Once It's Connected

Once Telegram is wired up, your agent runs in your pocket:

  • Morning briefings sent automatically via cron
  • Forum topics routing to different specialized agents
  • Inline button confirmations before sensitive actions
  • Custom command shortcuts for frequent tasks

Telegram's Bot API is genuinely one of the more capable channels to build on. Long polling is reliable, the forum topic isolation is surprisingly useful for multi-agent setups, and the streaming support keeps the UX snappy.

Originally published at openclawplaybook.ai. Get The OpenClaw Playbook — $9.99

Top comments (0)