Clawdbot Telegram Integration

Clawdbot Telegram Integration Overview

Clawdbot Telegram integration allows you to connect your personal AI assistant to Telegram using the Bot API via grammY. This is production-ready for bot DMs and groups, with long-polling by default and optional webhook support.

Why Use Clawdbot with Telegram?

Telegram offers powerful bot APIs and privacy features. Integrating Clawdbot with Telegram provides:

Quick Setup (Beginner)

1. Create a bot with @BotFather (direct link)
2. Confirm the handle is exactly @BotFather, then copy the token
3. Set the token via env (TELEGRAM_BOT_TOKEN=...) or config (channels.telegram.botToken)
4. Start the gateway
5. DM access is pairing by default; approve the pairing code on first contact

Minimal config:

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

Setting Up Clawdbot Telegram

Prerequisites

Before connecting Clawdbot to Telegram, ensure you have:

• Clawdbot installed on your device
• A Telegram account
• A Telegram Bot Token from @BotFather

Step 1: Create a Telegram Bot

Create a bot through Telegram's BotFather:

1. Open Telegram and chat with @BotFather (direct link)
2. Confirm the handle is exactly @BotFather
3. Run /newbot, then follow the prompts (name + username ending in bot)
4. 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

Step 2: Configure the Token

Set the token via environment variable or config:

Environment variable:

TELEGRAM_BOT_TOKEN=123:abc

Config file (~/.clawdbot/clawdbot.json):

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

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

Step 3: Start the Gateway

clawdbot gateway --port 18789

Telegram starts when a token is resolved (config first, env fallback).

Step 4: Verify Connection

Check your Clawdbot Telegram status:

clawdbot channels status telegram

Token + Privacy + Permissions

Token Creation (BotFather)

• /newbot creates the bot and returns the token (keep it secret)
• If a token leaks, revoke/regenerate it via @BotFather and update your config

Group Message Visibility (Privacy Mode)

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

1. Disable privacy mode with /setprivacy
2. 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.

Clawdbot Telegram Features

How It Works

• 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

Draft Streaming

Clawdbot can stream partial replies in Telegram DMs using sendMessageDraft.

Requirements:

• Threaded Mode enabled for the bot in @BotFather (forum topic mode)
• Private chat threads only
• channels.telegram.streamMode not set to "off"

Draft streaming is DM-only; Telegram does not support it in groups or channels.

Formatting (Telegram HTML)

• Outbound Telegram text uses parse_mode: "HTML"
• Markdown-ish input is rendered into Telegram-safe HTML
• Raw HTML from models is escaped to avoid Telegram parse errors

Commands

Clawdbot Telegram supports custom commands:

Clawdbot Telegram Configuration

Full Configuration Example

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

Access Control (DMs + Groups)

DM Access:

• dmPolicy: "pairing" — Unknown senders get a pairing code; approve with CLI
• dmPolicy: "allowlist" — Only respond to users in allowlist
• dmPolicy: "open" — Respond to all (not recommended)

Group Access:

• Set channels.telegram.groups keyed by group id or "*" for all groups
• Use requireMention: true to only respond when mentioned

Finding Your Telegram User ID

Use @userinfobot or similar bots to get your numeric Telegram user ID.

Clawdbot Telegram Credential Storage

Clawdbot stores Telegram credentials securely:

~/.clawdbot/credentials/telegram/bot_token
~/.clawdbot/credentials/telegram/session.json

Your Clawdbot Telegram data remains on your local machine.

Troubleshooting Clawdbot Telegram

Bot Not Responding

If your Clawdbot Telegram bot doesn't respond:

1. Verify token: clawdbot channels verify telegram
2. Check bot status with @BotFather
3. Review logs: cat /tmp/clawdbot/telegram.log

Group Activation

To activate Clawdbot in a group:

Via config (recommended):

{
  "channels": {
    "telegram": {
      "groups": {
        "<group_id>": { "requireMention": true }
      }
    }
  }
}

Via command (session-level): Use /activate in the group chat.

Getting the Group Chat ID

Forward a message from the group to @userinfobot or use the Telegram API.

Clawdbot Telegram Best Practices

1. Use Pairing Mode: Secure by default with pairing codes
2. Set Privacy Mode: Configure in @BotFather based on your needs
3. Handle Rate Limits: Implement proper rate limiting
4. Monitor Usage: Track Clawdbot Telegram bot analytics

Next Steps

• Clawdbot WhatsApp Integration - Connect Clawdbot to WhatsApp
• Clawdbot Discord Integration - Set up Clawdbot on Discord
• Clawdbot Setup Guide - Complete installation guide