2.9 KiB

Raw Blame History

summary

read_when

Telegram Bot API integration: setup, forum topics, reply modes, and configuration

Configuring Telegram bot integration

Setting up forum topic threading

Troubleshooting Telegram reply behavior

Telegram Integration

CLAWDBOT connects to Telegram via the Bot API using grammY.

Setup

Create a bot via @BotFather
Copy the token
Add to your config:

{
  "telegram": {
    "token": "123456789:ABCdefGHI..."
  }
}

Or set TELEGRAM_BOT_TOKEN in your environment.

Forum Topics (Supergroups)

Telegram supergroups can enable Topics (forum mode), which creates thread-like conversations within a single group. CLAWDBOT fully supports forum topics:

Automatic detection: When a message arrives from a forum topic, CLAWDBOT automatically routes it to a topic-specific session
Thread isolation: Each topic gets its own conversation context, so the agent maintains separate threads
Reply threading: Replies are sent to the same topic via message_thread_id

Session Routing

Forum topic messages create session keys in the format:

telegram:group:<chat_id>:topic:<topic_id>

This ensures conversations in different topics remain isolated even within the same supergroup.

Reply Modes

The replyToMode setting controls how the bot replies to messages:

Mode	Behavior
`"first"`	Reply to the first message in a conversation (default)
`"all"`	Reply to every message
`"off"`	Send messages without reply threading

Configure in your config:

{
  "telegram": {
    "replyToMode": "first"
  }
}

Default: "first" — This ensures replies appear threaded in the chat, making conversations easier to follow.

Access Control

DM Policy

Control who can DM your bot:

{
  "telegram": {
    "dmPolicy": "pairing",
    "allowFrom": ["123456789", "@username"]
  }
}

"pairing" (default): New users get a pairing code to request access
"allowlist": Only users in allowFrom can interact
"open": Anyone can DM the bot
"disabled": DMs are blocked

Group Policy

Control group message handling:

{
  "telegram": {
    "groupPolicy": "open",
    "groupAllowFrom": ["*"],
    "groups": ["-1001234567890"]
  }
}

groupPolicy: "open" (default), "allowlist", or "disabled"
groups: When set, acts as an allowlist of group IDs

Mention Requirements

In groups, you can require the bot to be mentioned:

{
  "telegram": {
    "requireMention": true
  }
}

When true, the bot only responds to messages that @mention it or match configured mention patterns.

Media Handling

Configure media size limits:

{
  "telegram": {
    "mediaMaxMb": 10
  }
}

Default: 5MB. Files exceeding this limit are rejected with a user-friendly message.

2.9 KiB Raw Blame History