From 0ff184397da86a64f613e96f62935428706925c9 Mon Sep 17 00:00:00 2001 From: Altay Date: Tue, 10 Mar 2026 21:56:30 +0300 Subject: [PATCH] docs(telegram): clarify group and sender allowlists (#42451) Merged via squash. Prepared head SHA: f30cacafb326a1ed0ef996424f049ae7b36ff1a6 Co-authored-by: altaywtf <9790196+altaywtf@users.noreply.github.com> Co-authored-by: altaywtf <9790196+altaywtf@users.noreply.github.com> Reviewed-by: @altaywtf --- CHANGELOG.md | 1 + docs/channels/telegram.md | 26 ++++++++++++++++++++++++++ src/telegram/bot-access.ts | 3 ++- 3 files changed, 29 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ad3c0eec26..2a5d12840ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -71,6 +71,7 @@ Docs: https://docs.openclaw.ai - Agents/failover: treat Gemini `MALFORMED_RESPONSE` stop reasons as retryable timeouts so preview-model enum drift falls back cleanly instead of crashing the run, without also reclassifying malformed function-call errors. (#42292) Thanks @jnMetaCode. - Discord/Telegram outbound runtime config: thread runtime-resolved config through Discord and Telegram send paths so SecretRef-based credentials stay resolved during message delivery. (#42352) Thanks @joshavant. - Secrets/SecretRef: reject exec SecretRef traversal ids across schema, runtime, and gateway. (#42370) Thanks @joshavant. +- Telegram/docs: clarify that `channels.telegram.groups` allowlists chats while `groupAllowFrom` allowlists users inside those chats, and point invalid negative chat IDs at the right config key. (#42451) Thanks @altaywtf. ## 2026.3.8 diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index b29ec3c59d5..7c32c29ab19 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -155,6 +155,7 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` is used for group sender filtering. If not set, Telegram falls back to `allowFrom`. `groupAllowFrom` entries should be numeric Telegram user IDs (`telegram:` / `tg:` prefixes are normalized). + Do not put Telegram group or supergroup chat IDs in `groupAllowFrom`. Negative chat IDs belong under `channels.telegram.groups`. Non-numeric entries are ignored for sender authorization. Security boundary (`2026.2.25+`): group sender auth does **not** inherit DM pairing-store approvals. Pairing stays DM-only. For groups, set `groupAllowFrom` or per-group/per-topic `allowFrom`. @@ -177,6 +178,31 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` + Example: allow only specific users inside one specific group: + +```json5 +{ + channels: { + telegram: { + groups: { + "-1001234567890": { + requireMention: true, + allowFrom: ["8734062810", "745123456"], + }, + }, + }, + }, +} +``` + + + Common mistake: `groupAllowFrom` is not a Telegram group allowlist. + + - Put negative Telegram group or supergroup chat IDs like `-1001234567890` under `channels.telegram.groups`. + - Put Telegram user IDs like `8734062810` under `groupAllowFrom` when you want to limit which people inside an allowed group can trigger the bot. + - Use `groupAllowFrom: ["*"]` only when you want any member of an allowed group to be able to talk to the bot. + + diff --git a/src/telegram/bot-access.ts b/src/telegram/bot-access.ts index d08a54616f0..60b3f5582a9 100644 --- a/src/telegram/bot-access.ts +++ b/src/telegram/bot-access.ts @@ -31,7 +31,8 @@ function warnInvalidAllowFromEntries(entries: string[]) { [ "Invalid allowFrom entry:", JSON.stringify(entry), - "- allowFrom/groupAllowFrom authorization requires numeric Telegram sender IDs only.", + "- allowFrom/groupAllowFrom authorization expects numeric Telegram sender user IDs only.", + 'To allow a Telegram group or supergroup, add its negative chat ID under "channels.telegram.groups" instead.', 'If you had "@username" entries, re-run onboarding (it resolves @username to IDs) or replace them manually.', ].join(" "), );