ClawdBotAI

Status: production-ready for bot DMs + groups via grammY. Long-polling by default; webhook optional.

Quick setup (beginner)

Create a bot with @BotFather and copy the token.
Set the token:
- Env: TELEGRAM_BOT_TOKEN=...
- Or config: channels.telegram.botToken: "..."
Start the gateway.
DM access is pairing by default; approve the pairing code on first contact.

Minimal config:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing"
    }
  }
}

1) Create a bot token (BotFather)

Open Telegram and chat with @BotFather.
Run /newbot, then follow the prompts (name + username ending in bot).
Copy the token and store it safely.

Optional BotFather settings:

/setjoingroups — allow/deny adding the bot to groups.
/setprivacy — control whether the bot sees all group messages.

2) Configure the token (env or config)

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Env option: TELEGRAM_BOT_TOKEN=... (works for the default account).

If both env and config are set, config takes precedence.

Token + privacy + permissions (Telegram side)

Group message visibility (Privacy Mode)

Telegram bots default to Privacy Mode, which limits which group messages they receive.

If your bot must see all group messages, you have two options:

Disable privacy mode with /setprivacy
Add the bot as a group admin (admin bots receive all messages).

Note: When you toggle privacy mode, Telegram requires removing + re‑adding the bot to each group for the change to take effect.

Group permissions (admin rights)

Admin status is set inside the group (Telegram UI). Admin bots always receive all group messages.

How it works (behavior)

Inbound messages are normalized into the shared channel envelope with reply context and media placeholders.
Group replies require a mention by default (native @mention or configured patterns).
Replies always route back to the same Telegram chat.
Long-polling uses grammY runner with per-chat sequencing.
Telegram Bot API does not support read receipts.

Formatting (Telegram HTML)

Outbound Telegram text uses parse_mode: "HTML". Markdown-ish input is rendered into Telegram-safe HTML.

Commands (native + custom)

Clawdbot registers native commands with Telegram's bot menu on startup.

Add custom commands via config:

{
  "channels": {
    "telegram": {
      "customCommands": [
        { "command": "backup", "description": "Backup data" }
      ]
    }
  }
}

Access control (DMs + groups)

DM access

Default: dmPolicy: "pairing" - unknown senders get a pairing code.

Approve with: clawdbot pairing approve telegram <code>

Finding your Telegram user ID

Message @userinfobot or check the pairing logs.

Group access

Configure per-group settings with channels.telegram.groups.

Troubleshooting

Bot not responding: Check clawdbot status and verify token is correct.
Pairing code not working: Codes expire after 1 hour. Request a new one.
Bot not seeing group messages: Disable Privacy Mode or make bot admin.
Token revoked: Regenerate via @BotFather and update config.

Telegram