Files

mneves75 33e2d53be3 feat(telegram): wire replyToMode config, add forum topic support, fix messaging tool duplicates

Changes:
- Default replyToMode from "off" to "first" for better threading UX
- Add messageThreadId and replyToMessageId params for forum topic support
- Add messaging tool duplicate detection to suppress redundant block replies
- Add sendMessage action to telegram tool schema
- Add @grammyjs/types devDependency for proper TypeScript typing
- Remove @ts-nocheck and fix all type errors in send.ts
- Add comprehensive docs/telegram.md documentation
- Add PR-326-REVIEW.md with John Carmack-level code review

Test coverage:
- normalizeTextForComparison: 5 cases
- isMessagingToolDuplicate: 7 cases
- sendMessageTelegram thread params: 5 cases
- handleTelegramAction sendMessage: 4 cases
- Forum topic isolation: 4 cases

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-08 00:50:47 +00:00

2.9 KiB

Raw Blame History

summary, read_when

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