1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
# Telegram โ Access & Delivery
A Telegram bot is publicly addressable. Anyone who finds its username can DM it, and without a gate those messages would flow straight into your assistant session. The access model described here decides who gets through.
By default, a DM from an unknown sender triggers **pairing**: the bot replies with a 6-character code and drops the message. You run `/telegram:access pair <code>` from your assistant session to approve them. Once approved, their messages pass through.
All state lives in `~/.claude/channels/telegram/access.json`. The `/telegram:access` skill commands edit this file; the server re-reads it on every inbound message, so changes take effect without a restart. Set `TELEGRAM_ACCESS_MODE=static` to pin config to what was on disk at boot (pairing is unavailable in static mode since it requires runtime writes).
## At a glance
| | |
| --- | --- |
| Default policy | `pairing` |
| Sender ID | Numeric user ID (e.g. `412587349`) |
| Group key | Supergroup ID (negative, `-100โฆ` prefix) |
| `ackReaction` quirk | Fixed whitelist only; non-whitelisted emoji silently do nothing |
| Config file | `~/.claude/channels/telegram/access.json` |
## DM policies
`dmPolicy` controls how DMs from senders not on the allowlist are handled.
| Policy | Behavior |
| --- | --- |
| `pairing` (default) | Reply with a pairing code, drop the message. Approve with `/telegram:access pair <code>`. |
| `allowlist` | Drop silently. No reply. Useful if the bot's username is guessable and pairing replies would attract spam. |
| `disabled` | Drop everything, including allowlisted users and groups. |
```
/telegram:access policy allowlist
```
## User IDs
Telegram identifies users by **numeric IDs** like `412587349`. Usernames are optional and mutable; numeric IDs are permanent. The allowlist stores numeric IDs.
Pairing captures the ID automatically. To find one manually, have the person message [@userinfobot](https://t.me/userinfobot), which replies with their ID. Forwarding any of their messages to @userinfobot also works.
```
/telegram:access allow 412587349
/telegram:access remove 412587349
```
## Groups
Groups are off by default. Opt each one in individually.
```
/telegram:access group add -1001654782309
```
Supergroup IDs are negative numbers with a `-100` prefix, e.g. `-1001654782309`. They're not shown in the Telegram UI. To find one, either add [@RawDataBot](https://t.me/RawDataBot) to the group temporarily (it dumps a JSON blob including the chat ID), or add your bot and run `/telegram:access` to see recent dropped-from groups.
With the default `requireMention: true`, the bot responds only when @mentioned or replied to. Pass `--no-mention` to process every message, or `--allow id1,id2` to restrict which members can trigger it.
```
/telegram:access group add -1001654782309 --no-mention
/telegram:access group add -1001654782309 --allow 412587349,628194073
/telegram:access group rm -1001654782309
```
**Privacy mode.** Telegram bots default to a server-side privacy mode that filters group messages before they reach your code: only @mentions and replies are delivered. This matches the default `requireMention: true`, so it's normally invisible. Using `--no-mention` requires disabling privacy mode as well: message [@BotFather](https://t.me/BotFather), send `/setprivacy`, pick your bot, choose **Disable**. Without that step, Telegram never delivers the messages regardless of local config.
## Mention detection
In groups with `requireMention: true`, any of the following triggers the bot:
- A structured `@botusername` mention
- A reply to one of the bot's messages
- A match against any regex in `mentionPatterns`
```
/telegram:access set mentionPatterns '["^hey claude\\b", "\\bassistant\\b"]'
```
## Delivery
Configure outbound behavior with `/telegram:access set <key> <value>`.
**`ackReaction`** reacts to inbound messages on receipt. Telegram accepts only a **fixed whitelist** of reaction emoji; anything else is silently ignored. The full Bot API list:
> ๐ ๐ โค ๐ฅ ๐ฅฐ ๐ ๐ ๐ค ๐คฏ ๐ฑ ๐คฌ ๐ข ๐ ๐คฉ ๐คฎ ๐ฉ ๐ ๐ ๐ ๐คก ๐ฅฑ ๐ฅด ๐ ๐ณ โคโ๐ฅ ๐ ๐ญ ๐ฏ ๐คฃ โก ๐ ๐ ๐ ๐คจ ๐ ๐ ๐พ ๐ ๐ ๐ ๐ด ๐ญ ๐ค ๐ป ๐จโ๐ป ๐ ๐ ๐ ๐ ๐จ ๐ค โ ๐ค ๐ซก ๐
๐ โ ๐
๐คช ๐ฟ ๐ ๐ ๐ ๐ฆ ๐ ๐ ๐ ๐ ๐พ ๐คทโโ ๐คท ๐คทโโ ๐ก
```
/telegram:access set ackReaction ๐
/telegram:access set ackReaction ""
```
**`replyToMode`** controls threading on chunked replies. When a long response is split, `first` (default) threads only the first chunk under the inbound message; `all` threads every chunk; `off` sends all chunks standalone.
**`textChunkLimit`** sets the split threshold. Telegram rejects messages over 4096 characters.
**`chunkMode`** chooses the split strategy: `length` cuts exactly at the limit; `newline` prefers paragraph boundaries.
## Skill reference
| Command | Effect |
| --- | --- |
| `/telegram:access` | Print current state: policy, allowlist, pending pairings, enabled groups. |
| `/telegram:access pair a4f91c` | Approve pairing code `a4f91c`. Adds the sender to `allowFrom` and sends a confirmation on Telegram. |
| `/telegram:access deny a4f91c` | Discard a pending code. The sender is not notified. |
| `/telegram:access allow 412587349` | Add a user ID directly. |
| `/telegram:access remove 412587349` | Remove from the allowlist. |
| `/telegram:access policy allowlist` | Set `dmPolicy`. Values: `pairing`, `allowlist`, `disabled`. |
| `/telegram:access group add -1001654782309` | Enable a group. Flags: `--no-mention` (also requires disabling privacy mode), `--allow id1,id2`. |
| `/telegram:access group rm -1001654782309` | Disable a group. |
| `/telegram:access set ackReaction ๐` | Set a config key: `ackReaction`, `replyToMode`, `textChunkLimit`, `chunkMode`, `mentionPatterns`. |
## Config file
`~/.claude/channels/telegram/access.json`. Absent file is equivalent to `pairing` policy with empty lists, so the first DM triggers pairing.
```jsonc
{
// Handling for DMs from senders not in allowFrom.
"dmPolicy": "pairing",
// Numeric user IDs allowed to DM.
"allowFrom": ["412587349"],
// Groups the bot is active in. Empty object = DM-only.
"groups": {
"-1001654782309": {
// true: respond only to @mentions and replies.
// false also requires disabling privacy mode via BotFather.
"requireMention": true,
// Restrict triggers to these senders. Empty = any member (subject to requireMention).
"allowFrom": []
}
},
// Case-insensitive regexes that count as a mention.
"mentionPatterns": ["^hey claude\\b"],
// Emoji from Telegram's fixed whitelist. Empty string disables.
"ackReaction": "๐",
// Threading on chunked replies: first | all | off
"replyToMode": "first",
// Split threshold. Telegram rejects > 4096.
"textChunkLimit": 4096,
// length = cut at limit. newline = prefer paragraph boundaries.
"chunkMode": "newline"
}
```
|