33e2d53be3
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>
131 lines
2.9 KiB
Markdown
131 lines
2.9 KiB
Markdown
---
|
|
summary: "Telegram Bot API integration: setup, forum topics, reply modes, and configuration"
|
|
read_when:
|
|
- Configuring Telegram bot integration
|
|
- Setting up forum topic threading
|
|
- Troubleshooting Telegram reply behavior
|
|
---
|
|
# Telegram Integration
|
|
|
|
CLAWDBOT connects to Telegram via the [Bot API](https://core.telegram.org/bots/api) using [grammY](https://grammy.dev/).
|
|
|
|
## Setup
|
|
|
|
1. Create a bot via [@BotFather](https://t.me/BotFather)
|
|
2. Copy the token
|
|
3. Add to your config:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"telegram": {
|
|
"mediaMaxMb": 10
|
|
}
|
|
}
|
|
```
|
|
|
|
Default: 5MB. Files exceeding this limit are rejected with a user-friendly message.
|