Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

feat(server,web): a Telegram bot that cannot hear a group now says so (#499)

Yaowei Zheng33766be489d1
diff --git a/changelog/unreleased/2026-08-26-telegram-group-privacy.md b/changelog/unreleased/2026-08-26-telegram-group-privacy.md
new file mode 100644
index 00000000..6db2669d
--- /dev/null
+++ b/changelog/unreleased/2026-08-26-telegram-group-privacy.md
@@ -0,0 +1,39 @@
+# A Telegram bot that cannot hear a group now says so
+
+- **Date:** 2026-08-26
+- **Type:** feature
+- **Scope:** `server`, `web`
+- **PR:** [#499](https://github.com/Prism-Shadow/penguin-harness/pull/499)
+
+[中文版](2026-08-26-telegram-group-privacy.zh.md)
+
+Messages sent to a bound Telegram bot in a group could go unanswered with nothing to show for it:
+no error, no status change, no record. The cause is Telegram's **Group Privacy**, on by default for
+every bot, under which the Bot API delivers to a bot that does not administer the group only
+commands addressed to it (`/command@this_bot`), general commands when it was the last bot to speak
+there, inline messages sent via it, and replies to its own messages. A plain sentence — and a plain
+`@mention` — is never delivered at all, so `getUpdates` returns nothing and the connection looks
+perfectly healthy. The setting belongs to the bot's owner in @BotFather; this change reports it, in
+the credential test and in the binding panel's troubleshooting fold.
+
+## The credential test reports the setting
+
+`getMe` answers `can_read_all_group_messages` ("True, if privacy mode is disabled for the bot",
+returned only in `getMe`). The Telegram credential-test response carries it as `groupPrivacy`, and
+a successful test whose bot still has Group Privacy on shows a second line beside the success one —
+the credentials passed, and the caveat is about group chats only.
+
+That line names the setting, never the outcome in any one group. Group Privacy is account-wide and
+Telegram overrides it wherever the bot is an administrator, so the notice says the bot receives no
+ordinary message in a group it does not administer. The field is reported only when the API
+actually answered the question; a response without it reports nothing rather than guessing.
+
+## The troubleshooting fold names both ways out
+
+The binding panel's Telegram troubleshooting fold gained an entry beside the one-program-per-token
+one, holding the remedies in full — the toast points at it rather than spelling them out. It leads
+with the one that leaves the group's membership alone:
+
+- make the bot an administrator of the group, since administrators always receive every message;
+- or turn Group Privacy off with `/setprivacy` in @BotFather, then remove the bot from the group
+ and add it back — a group it is already in does not pick up the change.
diff --git a/changelog/unreleased/2026-08-26-telegram-group-privacy.zh.md b/changelog/unreleased/2026-08-26-telegram-group-privacy.zh.md
new file mode 100644
index 00000000..333cc98a
--- /dev/null
+++ b/changelog/unreleased/2026-08-26-telegram-group-privacy.zh.md
@@ -0,0 +1,34 @@
+# 听不到群消息的 Telegram 机器人现在会说出来
+
+- **Date:** 2026-08-26
+- **Type:** feature
+- **Scope:** `server`, `web`
+- **PR:** [#499](https://github.com/Prism-Shadow/penguin-harness/pull/499)
+
+[English](2026-08-26-telegram-group-privacy.md)
+
+在群里向已绑定的 Telegram 机器人发消息,可能得不到任何回应,也没有任何线索:没有报错、状态不变、也不
+留记录。原因是 Telegram 的 **Group Privacy**——它对每个机器人都默认开启,在它生效时,Bot API 对一个不
+担任该群管理员的机器人只投递:明确指向它的命令(`/command@this_bot`)、它是群里最后一个发言的机器人时
+的通用命令、经由它发出的 inline 消息,以及对它自己消息的回复。一句普通的话——以及一个普通的 `@` 提及
+——根本不会被投递,因此 `getUpdates` 什么也取不到,连接看上去完全正常。该设置属于机器人拥有者,在
+@BotFather 中;本次改动把它报出来:在凭证测试里,也在绑定面板的常见问题折叠里。
+
+## 凭证测试报出这项设置
+
+`getMe` 会返回 `can_read_all_group_messages`(「True,表示该机器人的隐私模式已关闭」,仅在 `getMe` 中
+返回)。Telegram 凭证测试的响应以 `groupPrivacy` 携带它;当测试成功而机器人仍开着 Group Privacy 时,
+成功提示旁会另起一条——凭证确实通过了,这条提醒只关于群聊。
+
+这条提醒说的是那项设置,而不是某个具体群里的结果。Group Privacy 按账号计,而 Telegram 会在机器人担任
+管理员的群里覆盖它,因此提醒的说法是:在它不担任管理员的群里,它收不到普通消息。只有在 API 真的回答了
+这个问题时才会报出该字段;响应里没有这一项时就什么也不报,而不是去猜。
+
+## 常见问题折叠写清两条出路
+
+绑定面板的 Telegram 常见问题折叠里,在「一个 Token 只能被一个程序使用」旁边新增了一条,完整地写着修复
+办法——提示语只指向它,不再自己复述。它把不必改动群成员关系的那条放在最前:
+
+- 把机器人设为该群的管理员,管理员始终收到全部消息;
+- 或者到 @BotFather 用 `/setprivacy` 关闭 Group Privacy,然后把机器人移出该群再重新拉入——已在的群不
+ 会自动生效。
diff --git a/packages/docs/content/server-api.en.md b/packages/docs/content/server-api.en.md
index 11a088ab..ce1d5b3e 100644
--- a/packages/docs/content/server-api.en.md
+++ b/packages/docs/content/server-api.en.md
@@ -306,7 +306,7 @@ A Session can be connected to a messaging bot — Feishu and Telegram are the ch
| PUT | /messaging/telegram | Save the credential: `{botToken?, clearBotToken?, linePerMessage?}` — the whole credential is the one `<bot id>:<secret>` token from @BotFather (omitted/blank keeps the stored one; 400 `telegram_token_invalid` when the numeric id cannot be read; the clear flag works like Feishu's and the cleared config keeps its bot identity). Same save/enable split, the same 409 `account_enabled_elsewhere` when an enabled binding's token is swapped for one another Session has enabled, and otherwise the same absence of a cross-Session conflict on save |
| POST | /messaging/telegram/state | Same contract as the Feishu toggle (400 `telegram_token_required` without a stored token) |
| DELETE | /messaging/telegram | Remove this channel's config entirely (Bot Token included). API completeness only |
-| POST | /messaging/telegram/test | Credential probe (`getMe`) with the draft token falling back to the stored one → `{ok, latencyMs?, botUsername?, error?}` — success names the bot the token signs in as |
+| POST | /messaging/telegram/test | Credential probe (`getMe`) with the draft token falling back to the stored one → `{ok, latencyMs?, botUsername?, groupPrivacy?, error?}` — success names the bot the token signs in as, and reports `groupPrivacy: true` when @BotFather's Group Privacy is on (the default), under which the bot receives no ordinary message in any group it does not administer |
| POST | /messaging/telegram/test-message | Send a short fixed text to the last known chat; 409 `telegram_no_chat` until the bot has been messaged once in Telegram |
Masked secrets are omitted from responses when none is stored (a cleared config), and a config without a secret cannot be enabled. `linePerMessage` is the one saved field that is not a credential: with it set, every non-blank line of a relayed assistant reply is sent as its own message (blank lines dropped, each line still chunked under the size cap, and the remainder combined into one last message past a per-reply message cap); it defaults to false, an omitted value on a PUT keeps the stored one, and it never applies to the notices or the test message. The one cross-Session rule is per bot account per channel and applies to the connection only: one account has one event stream, so at most one Session may have it enabled. Feishu's account identity is the `app_id`, Telegram's is the numeric bot id in front of the token's colon (robust against token rotation). Reads and the two tests are open to any Project member; PUT, the state toggle and DELETE are owner-only (vault semantics — the binding writes carry or act on the secret). Secrets never round-trip. Deleting the Session removes all its configs, and inbound processing accepts text messages only (other types get a bilingual "text only" reply). Telegram connects by draining the backlog first: messages sent while no connection existed are skipped, matching Feishu, where missed events are simply gone.
diff --git a/packages/docs/content/server-api.zh.md b/packages/docs/content/server-api.zh.md
index 08087fc5..a03c48d6 100644
--- a/packages/docs/content/server-api.zh.md
+++ b/packages/docs/content/server-api.zh.md
@@ -305,7 +305,7 @@ Session 可以接入消息软件机器人——目前的渠道是飞书与 Teleg
| PUT | /messaging/telegram | 保存凭据:`{botToken?, clearBotToken?, linePerMessage?}`——整份凭据就是 @BotFather 签发的一条 `<机器人 id>:<密钥>` Token(省略或留空则保持已存值;读不出数字 id 时返回 400 `telegram_token_invalid`;清除标记与飞书同口径,清除后配置保留其机器人身份)。保存与启用的分离一致;把已启用绑定的 Token 换成另一个 Session 已启用的机器人时,同样返回 409 `account_enabled_elsewhere`,其余情况不存在跨 Session 的保存冲突 |
| POST | /messaging/telegram/state | 与飞书开关同一契约(无已存 Token 时返回 400 `telegram_token_required`) |
| DELETE | /messaging/telegram | 整体删除该渠道的配置(含 Bot Token)。仅为 API 完整性保留 |
-| POST | /messaging/telegram/test | 凭据探测(`getMe`),草稿 Token 缺省回落到已存值 → `{ok, latencyMs?, botUsername?, error?}`——成功时报出 Token 登录到的机器人 |
+| POST | /messaging/telegram/test | 凭据探测(`getMe`),草稿 Token 缺省回落到已存值 → `{ok, latencyMs?, botUsername?, groupPrivacy?, error?}`——成功时报出 Token 登录到的机器人;当 @BotFather 的 Group Privacy 处于开启状态(默认如此,此时机器人在它不担任管理员的群里收不到任何普通消息)时报出 `groupPrivacy: true` |
| POST | /messaging/telegram/test-message | 向最近一次收到消息的会话发送一条固定测试文本;在 Telegram 里给机器人发过消息之前返回 409 `telegram_no_chat` |
没有已存密钥的配置(被清除过的)不返回掩码字段,也无法启用。`linePerMessage` 是唯一一个不属于凭据的已存字段:开启后,转发的助手回复中每个非空行各自作为一条消息发出(空行忽略,单行仍按长度上限分段,超出每条回复的消息条数上限的部分合并为最后一条);默认为 false,PUT 省略该字段则保持已存值,且它不作用于通知与测试消息。唯一的跨 Session 规则按渠道内机器人账号计,且只作用于连接:一个账号只有一条事件流,因此至多一个 Session 能将其启用。飞书的账号身份是 `app_id`,Telegram 是 Token 冒号前的数字机器人 id(换发 Token 也不会改变)。读取与两个测试接口对任意 Project 成员开放;PUT、state 开关与 DELETE 仅限所有者(与 Vault 同口径——绑定写操作携带或作用于密钥)。密钥永不回传。删除 Session 会连带删除其全部渠道配置;入站仅处理文本消息(其他类型收到双语的“仅支持文本”回复)。Telegram 建立连接时先清空积压:无连接期间发来的消息会被跳过,与飞书“错过的事件即消失”同口径。
diff --git a/packages/server/src/api/types.ts b/packages/server/src/api/types.ts
index 40b849b2..6021156d 100644
--- a/packages/server/src/api/types.ts
+++ b/packages/server/src/api/types.ts
@@ -1786,6 +1786,16 @@ export interface TelegramTestResponse {
latencyMs?: number;
/** The bot's `@username`, when the API reports one. */
botUsername?: string;
+ /**
+ * True when @BotFather's **Group Privacy** is ON for this bot, which is the default. In
+ * every group where the bot is not an administrator it then receives only a command
+ * addressed to it or a reply to one of its own messages — an ordinary sentence is never
+ * delivered, so a binding that answers fine in a direct chat stays silent there. The
+ * setting is account-wide and Telegram overrides it for a group the bot administers, so
+ * this reports the setting and never the outcome in any particular group. Absent when the
+ * API did not report the setting; never inferred.
+ */
+ groupPrivacy?: boolean;
error?: string;
}
diff --git a/packages/server/src/http/routes/messaging.ts b/packages/server/src/http/routes/messaging.ts
index cb155f40..d0656135 100644
--- a/packages/server/src/http/routes/messaging.ts
+++ b/packages/server/src/http/routes/messaging.ts
@@ -495,6 +495,11 @@ export function sessionMessagingRoutes(deps: AppDeps): Hono<AppEnv> {
ok: result.ok,
...(result.latencyMs !== undefined ? { latencyMs: result.latencyMs } : {}),
...(result.accountLabel !== undefined ? { botUsername: result.accountLabel } : {}),
+ // The probe answers "does this bot read group messages"; the response states the
+ // BotFather setting behind it, which is the name the user has to go and look for.
+ ...(result.readsGroupMessages !== undefined
+ ? { groupPrivacy: !result.readsGroupMessages }
+ : {}),
...(result.error !== undefined ? { error: result.error } : {}),
} satisfies TelegramTestResponse);
});
diff --git a/packages/server/src/runtime/messaging/bridge.ts b/packages/server/src/runtime/messaging/bridge.ts
index 46a8db1f..cba282cb 100644
--- a/packages/server/src/runtime/messaging/bridge.ts
+++ b/packages/server/src/runtime/messaging/bridge.ts
@@ -375,12 +375,19 @@ export class MessagingBridge {
/**
* Credential probe for the test endpoints: ok/error with latency, never a throw. A
* channel whose check identifies the account (Telegram: the bot's @username) passes
- * that label through for the route's success feedback.
+ * that label through for the route's success feedback, along with anything else the
+ * probe learned that the user should act on (see MessagingAccountInfo).
*/
async testCredentials(
channel: string,
config: Record<string, unknown>,
- ): Promise<{ ok: boolean; latencyMs?: number; accountLabel?: string; error?: string }> {
+ ): Promise<{
+ ok: boolean;
+ latencyMs?: number;
+ accountLabel?: string;
+ readsGroupMessages?: boolean;
+ error?: string;
+ }> {
const startedAt = this.now();
try {
const client = await this.connectorFor(channel).createClient(config);
@@ -389,6 +396,9 @@ export class MessagingBridge {
ok: true,
latencyMs: this.now() - startedAt,
...(info?.accountLabel !== undefined ? { accountLabel: info.accountLabel } : {}),
+ ...(info?.readsGroupMessages !== undefined
+ ? { readsGroupMessages: info.readsGroupMessages }
+ : {}),
};
} catch (err) {
return { ok: false, error: err instanceof Error ? err.message : String(err) };
diff --git a/packages/server/src/runtime/messaging/connector.ts b/packages/server/src/runtime/messaging/connector.ts
index 238b490e..75843391 100644
--- a/packages/server/src/runtime/messaging/connector.ts
+++ b/packages/server/src/runtime/messaging/connector.ts
@@ -54,12 +54,29 @@ export interface MessagingConnection {
}
/**
- * A successful credential check's optional payload: a short human-readable label of the
- * account the credentials sign in as (Telegram: the bot's `@username`), surfaced in the
- * test endpoint's success feedback. Channels with no cheap label return null.
+ * A successful credential check's optional payload: whatever the probe learned that the test
+ * endpoint's feedback can act on. Every member is independently optional — a channel reports
+ * the ones its check happens to answer and omits the rest, so a check that learned nothing
+ * beyond "these credentials work" returns an empty object.
*/
export interface MessagingAccountInfo {
+ /** A short human-readable label of the account the credentials sign in as (Telegram: the bot's `@username`). */
accountLabel?: string;
+ /**
+ * Whether this ACCOUNT is set up to receive ordinary messages in the groups it belongs to
+ * — as opposed to only the ones a platform hands a bot by default.
+ *
+ * Telegram's privacy mode is the case that needs saying: it is on for every bot whose
+ * owner has not turned it off in @BotFather, and under it `getUpdates` simply omits
+ * everything in a group that is not a command addressed to this bot or a reply to one of
+ * its messages. Nothing errors — the messages are never delivered, so a binding that works
+ * perfectly in a direct chat looks dead in a group. It is one account-wide setting and
+ * Telegram overrides it in any group the bot administers, so `false` says the account is
+ * muted where it is an ordinary member, never that some particular group is silent. Absent
+ * when the channel has no such notion, or reports nothing about it: unknown must never be
+ * reported as a problem.
+ */
+ readsGroupMessages?: boolean;
}
/** Outbound half of one bound account. Every method throws on failure with a readable reason. */
diff --git a/packages/server/src/runtime/messaging/telegram-api.ts b/packages/server/src/runtime/messaging/telegram-api.ts
index aa2791df..d3c8f45f 100644
--- a/packages/server/src/runtime/messaging/telegram-api.ts
+++ b/packages/server/src/runtime/messaging/telegram-api.ts
@@ -18,11 +18,22 @@ export interface TelegramCredentials {
botToken: string;
}
-/** `getMe` result — the slice of the Bot API `User` object the connector consumes. */
+/**
+ * `getMe` result — the slice of the Bot API `User` object the connector consumes. The
+ * capability flag is documented as "Returned only in getMe", so this is the one call that
+ * can report it, and it may be absent from a response that predates it.
+ */
export interface TelegramBotUser {
id: number;
first_name?: string;
username?: string;
+ /**
+ * "True, if privacy mode is disabled for the bot." Privacy mode is ON for every bot whose
+ * owner has not turned it off in @BotFather, and it silently withholds ordinary group
+ * messages wherever the bot is not an administrator of the group — see the connector's
+ * checkCredentials.
+ */
+ can_read_all_group_messages?: boolean;
}
/**
diff --git a/packages/server/src/runtime/messaging/telegram-connector.ts b/packages/server/src/runtime/messaging/telegram-connector.ts
index fb87410d..c89153ae 100644
--- a/packages/server/src/runtime/messaging/telegram-connector.ts
+++ b/packages/server/src/runtime/messaging/telegram-connector.ts
@@ -203,7 +203,15 @@ export class TelegramConnector implements MessagingChannelConnector {
return {
async checkCredentials() {
const me = await bot.getMe();
- return me.username !== undefined ? { accountLabel: `@${me.username}` } : null;
+ return {
+ ...(me.username !== undefined ? { accountLabel: `@${me.username}` } : {}),
+ // Reported only when the API actually answered the question. A missing flag is
+ // "unknown", and telling a user their bot is muted in groups on the strength of an
+ // absent field would send them to BotFather for nothing.
+ ...(typeof me.can_read_all_group_messages === "boolean"
+ ? { readsGroupMessages: me.can_read_all_group_messages }
+ : {}),
+ };
},
async sendText(chatId, text) {
await bot.sendMessage({ chatId, text });
diff --git a/packages/server/test/messaging-telegram.test.ts b/packages/server/test/messaging-telegram.test.ts
index 996e8ce9..30de5c4d 100644
--- a/packages/server/test/messaging-telegram.test.ts
+++ b/packages/server/test/messaging-telegram.test.ts
@@ -86,7 +86,10 @@ class FakeBotClient implements TelegramBotClient {
return {
id: Number(telegramBotIdOf(this.creds.botToken) ?? "0"),
first_name: "Penguin Test",
- username: "penguin_test_bot",
+ ...(this.t.botUsername !== undefined ? { username: this.t.botUsername } : {}),
+ ...(this.t.readsAllGroupMessages !== undefined
+ ? { can_read_all_group_messages: this.t.readsAllGroupMessages }
+ : {}),
};
}
@@ -162,6 +165,10 @@ class FakeTelegramTransport {
failPolls = 0;
/** The webhook registered on the bot; the empty string means none, as the Bot API encodes it. */
webhookUrl = "";
+ /** getMe's `can_read_all_group_messages` (true = privacy mode OFF); undefined = the field is absent. */
+ readsAllGroupMessages: boolean | undefined = undefined;
+ /** getMe's `username`; undefined = the field is absent, which the Bot API's User allows. */
+ botUsername: string | undefined = "penguin_test_bot";
private nextUpdateId = 100;
createClient(creds: TelegramCredentials): FakeBotClient {
@@ -628,6 +635,51 @@ describe("telegram binding routes and connector loop", () => {
expect(runs.map((r) => r[0]!.text)).toEqual(["how is the build?", "second"]);
});
+ it("POST /test reports @BotFather's Group Privacy, and reports nothing when getMe is silent about it", async () => {
+ // Privacy mode ON is the Bot API default for every bot not added as a group admin. It is
+ // never an error — the bot answers a direct chat perfectly — so the test result is the
+ // only place the user learns why the same bot ignores a group.
+ fake.readsAllGroupMessages = false;
+ const on = (await (
+ await api.post(`${BASE(SID)}/test`, { botToken: TOKEN })
+ ).json()) as TelegramTestResponse;
+ expect(on.ok).toBe(true);
+ expect(on.groupPrivacy).toBe(true);
+
+ // Turned off in @BotFather: the flag says so, and the response says there is nothing to do.
+ fake.readsAllGroupMessages = true;
+ const off = (await (
+ await api.post(`${BASE(SID)}/test`, { botToken: TOKEN })
+ ).json()) as TelegramTestResponse;
+ expect(off.groupPrivacy).toBe(false);
+
+ // The field is documented as "returned only in getMe" and could be missing from a
+ // response this build did not anticipate. Unknown is reported as unknown: telling a user
+ // their bot is muted in groups on the strength of an absent field sends them to
+ // @BotFather for nothing.
+ fake.readsAllGroupMessages = undefined;
+ const silent = (await (
+ await api.post(`${BASE(SID)}/test`, { botToken: TOKEN })
+ ).json()) as TelegramTestResponse;
+ expect(silent.ok).toBe(true);
+ expect("groupPrivacy" in silent).toBe(false);
+ });
+
+ it("POST /test reports Group Privacy for a bot getMe names no username for", async () => {
+ // `username` is optional on the Bot API's User, and checkCredentials answered `null` for
+ // a response without one — which threw the privacy flag away along with the label. The
+ // two are independent: an unnamed bot is exactly as mute in a group as a named one.
+ fake.botUsername = undefined;
+ fake.readsAllGroupMessages = false;
+ const res = (await (
+ await api.post(`${BASE(SID)}/test`, { botToken: TOKEN })
+ ).json()) as TelegramTestResponse;
+ expect(res.ok).toBe(true);
+ expect(res.groupPrivacy).toBe(true);
+ expect(typeof res.latencyMs).toBe("number");
+ expect("botUsername" in res).toBe(false);
+ });
+
it("group messages thread the reply onto the inbound message; non-message updates are skipped", async () => {
await bindEnabled(SID);
// A non-message update (edited message, membership change, …): skipped entirely —
diff --git a/packages/web/src/features/messaging/messaging-binding-editor.tsx b/packages/web/src/features/messaging/messaging-binding-editor.tsx
index 5e5d30a7..a1df987a 100644
--- a/packages/web/src/features/messaging/messaging-binding-editor.tsx
+++ b/packages/web/src/features/messaging/messaging-binding-editor.tsx
@@ -38,6 +38,7 @@ import type {
MessagingBindingsResponse,
MessagingChannel,
MessagingRuntimeStatus,
+ TelegramTestResponse,
} from "@prismshadow/penguin-server/api";
import * as api from "../../api/endpoints";
import { S } from "../../lib/strings";
@@ -51,7 +52,7 @@ import { Input } from "../../components/ui/input";
import { PasswordInput } from "../../components/ui/password-input";
import { Segmented } from "../../components/ui/segmented";
import { Switch } from "../../components/ui/switch";
-import { toastError, toastSuccess } from "../../components/ui/toast";
+import { toastError, toastInfo, toastSuccess } from "../../components/ui/toast";
import {
bindingsToForm,
emptyMessagingForm,
@@ -179,6 +180,43 @@ export interface MessagingBindingEditorState {
sendTestMessage(): Promise<void>;
}
+/** One notice a credential test produces; the tone picks the toast that carries it. */
+export interface MessagingTestNotice {
+ tone: "success" | "info" | "error";
+ text: string;
+}
+
+/**
+ * The notices one Telegram credential-test response turns into, in the order they are shown
+ * (the updateCheckOutcome idiom: the classification is a pure function, the host only picks
+ * toasts for it).
+ *
+ * A success whose bot still has Group Privacy on produces TWO. The success line stands
+ * unchanged — the credentials really are fine, and the bot really will answer a direct chat —
+ * and the privacy notice rides beside it rather than lengthening it: it is about group chats
+ * only, and it is the one thing a user cannot discover by testing, since a bot that cannot
+ * hear a group produces silence and never an error.
+ */
+export function telegramTestNotices(res: TelegramTestResponse): MessagingTestNotice[] {
+ if (!res.ok) {
+ return [{ tone: "error", text: S.messaging.testFail(res.error ?? S.common.unknownError) }];
+ }
+ const ms = res.latencyMs ?? 0;
+ const notices: MessagingTestNotice[] = [
+ // The success line names the bot: the one detail a user can check against @BotFather.
+ {
+ tone: "success",
+ text:
+ res.botUsername !== undefined
+ ? S.messaging.testOkAs(res.botUsername, ms)
+ : S.messaging.testOk(ms),
+ },
+ ];
+ // Only an answered `true`: an absent field is unknown, and unknown is not a problem.
+ if (res.groupPrivacy === true) notices.push({ tone: "info", text: S.messaging.testPrivacyOn });
+ return notices;
+}
+
export function useMessagingBinding(
sessionId: string,
opts: {
@@ -295,15 +333,11 @@ export function useMessagingBinding(
const draft = formToTest(form);
if (draft.channel === "telegram") {
const res = await api.testTelegramBinding(sessionId, draft.body);
- if (res.ok) {
- const ms = res.latencyMs ?? 0;
- // The success line names the bot: the one detail a user can check against @BotFather.
- toastSuccess(
- res.botUsername !== undefined
- ? S.messaging.testOkAs(res.botUsername, ms)
- : S.messaging.testOk(ms),
- );
- } else toastError(S.messaging.testFail(res.error ?? S.common.unknownError));
+ for (const notice of telegramTestNotices(res)) {
+ if (notice.tone === "error") toastError(notice.text);
+ else if (notice.tone === "info") toastInfo(notice.text);
+ else toastSuccess(notice.text);
+ }
} else {
const res = await api.testFeishuBinding(sessionId, draft.body);
if (res.ok) toastSuccess(S.messaging.testOk(res.latencyMs ?? 0));
@@ -752,6 +786,7 @@ export function MessagingBindingHelp({ channel }: { channel: MessagingChannel })
<li>{S.messaging.troubleNoChat}</li>
<li>{S.messaging.troubleConnError}</li>
{channel === "telegram" && <li>{S.messaging.troubleOnePoller}</li>}
+ {channel === "telegram" && <li>{S.messaging.troubleGroupPrivacy}</li>}
</ul>
</HelpFold>
</div>
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index c12baa32..e8b47c2d 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -1851,6 +1851,9 @@ Scenarios:
/** Success feedback naming the account the credentials sign in as (Telegram: the bot's @username). */
testOkAs: (account: string, ms: number): string => `Connected as ${account} (${ms}ms)`,
testFail: (reason: string): string => `Connection failed: ${reason}`,
+ /** Second line on a successful Telegram test whose bot still has Group Privacy on; the remedies live in the troubleshooting fold, which outlasts a toast. */
+ testPrivacyOn:
+ "Group Privacy is on for this bot: it receives no ordinary messages in any group where it is not an administrator. See Troubleshooting below.",
sendTestMessage: "Send test message",
sendingTestMessage: "Sending…",
testMessageSent: "Test message sent",
@@ -1885,13 +1888,15 @@ Scenarios:
faqWhatBinding:
"The same bot can stay saved in several conversations, but only one of them may have its connection enabled at a time. To move it, turn the connection off where it is on and enable it here — no credential has to be deleted.",
faqTroubleTitle: "Troubleshooting",
- /** Troubleshooting entries (bot must be messaged once; connection errors point at credentials; one poller per Telegram token). */
+ /** Troubleshooting entries (bot must be messaged once; connection errors point at credentials; one poller per Telegram token; Telegram Group Privacy withholds group messages from a non-admin bot). */
troubleNoChat:
"“Send test message” disabled? The bot must have received one message first, so it knows which chat to send to.",
troubleConnError:
"Connection status shows an error? Check the credentials; for Feishu also confirm the API domain and the long-connection event subscription.",
troubleOnePoller:
"Telegram reports that another program is polling? A Bot Token serves exactly one program at a time — close the other PenguinHarness server or bot script using it, or give this conversation a bot of its own.",
+ troubleGroupPrivacy:
+ "The bot ignores everything you say in a Telegram group? Telegram's Group Privacy is on by default, and under it a bot that is not an administrator of the group receives only commands addressed to it (such as /start@your_bot) and replies to its own messages — ordinary group messages are never delivered at all, and the connection itself looks perfectly healthy. Making the bot an administrator of that group fixes it on its own, since administrators always receive every message. Otherwise turn Group Privacy off with /setprivacy in @BotFather, then remove the bot from the group and add it back — a group it is already in does not pick up the change.",
},
/** Subagents side panel: call-graph of the latest Task + the selected child conversation. */
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 3db82c16..3710c3a9 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -1812,6 +1812,9 @@ Benchmark:
/** Success feedback naming the account the credentials sign in as (Telegram: the bot's @username). */
testOkAs: (account: string, ms: number): string => `连接成功,机器人为 ${account}(${ms}ms)`,
testFail: (reason: string): string => `连接失败:${reason}`,
+ /** Second line on a successful Telegram test whose bot still has Group Privacy on; the remedies live in the troubleshooting fold, which outlasts a toast. */
+ testPrivacyOn:
+ "该机器人的 Group Privacy 处于开启状态:在它不担任管理员的群里,它收不到普通消息。修复办法见下方「常见问题」。",
sendTestMessage: "发送测试消息",
sendingTestMessage: "发送中…",
testMessageSent: "测试消息已发送",
@@ -1845,12 +1848,14 @@ Benchmark:
faqWhatBinding:
"同一个机器人可以同时保存在多个对话里,但同一时刻只能有一个对话启用它的连接。要换一个对话使用,先在原对话停用连接,再在这里启用——凭证不必删除。",
faqTroubleTitle: "常见问题",
- /** Troubleshooting entries (bot must be messaged once; connection errors point at credentials; one poller per Telegram token). */
+ /** Troubleshooting entries (bot must be messaged once; connection errors point at credentials; one poller per Telegram token; Telegram Group Privacy withholds group messages from a non-admin bot). */
troubleNoChat: "「发送测试消息」不可用?机器人要先收到过一条消息,才知道要发到哪个会话。",
troubleConnError:
"连接状态显示错误?检查凭证是否正确;飞书还需确认 API 域名与事件订阅方式(长连接)。",
troubleOnePoller:
"Telegram 提示已有其他程序在轮询?一个 Bot Token 同一时刻只能被一个程序使用——关闭正在占用它的另一个 PenguinHarness 服务端或机器人脚本,或为该会话单独建一个机器人。",
+ troubleGroupPrivacy:
+ "在 Telegram 群里发消息,机器人毫无反应?Telegram 的 Group Privacy 默认开启,此时不担任该群管理员的机器人只能收到明确指向它的命令(如 /start@your_bot)和对它自己消息的回复,普通群消息根本不会送达,连接本身也没有任何异常。把机器人设为该群的管理员即可单独解决,管理员始终收到全部消息。也可以到 @BotFather 用 /setprivacy 关闭 Group Privacy,然后把机器人移出该群再重新拉入——已在的群不会自动生效。",
},
/** Subagents side panel: call-graph of the latest Task + the selected child conversation. */
diff --git a/packages/web/test/messaging-binding-editor.test.ts b/packages/web/test/messaging-binding-editor.test.ts
index 7632d850..cd64aa2b 100644
--- a/packages/web/test/messaging-binding-editor.test.ts
+++ b/packages/web/test/messaging-binding-editor.test.ts
@@ -11,6 +11,8 @@
* connection error's detail reaches the reader whole rather than as a few words of a shared
* row.
*/
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
import { afterEach, describe, expect, it } from "vitest";
import { createElement } from "react";
import { renderToStaticMarkup } from "react-dom/server";
@@ -18,6 +20,7 @@ import type { MessagingChannel } from "@prismshadow/penguin-server/api";
import {
MessagingBindingBody,
MessagingBindingHelp,
+ telegramTestNotices,
type MessagingBindingEditorState,
type MessagingChannelFacts,
} from "../src/features/messaging/messaging-binding-editor";
@@ -217,6 +220,22 @@ describe("MessagingBindingHelp", () => {
expect(html).toContain(S.feishu.setupSteps[0]);
});
+ it("carries the Telegram-only troubleshooting entries, and neither of them on Feishu", () => {
+ const telegram = renderToStaticMarkup(
+ createElement(MessagingBindingHelp, { channel: "telegram" as MessagingChannel }),
+ );
+ // Group Privacy is on by default and produces silence, not an error, so the fold is the
+ // only place a user who has not run a credential test can find out about it.
+ expect(telegram).toContain(S.messaging.troubleGroupPrivacy);
+ expect(telegram).toContain(S.messaging.troubleOnePoller);
+
+ const feishu = renderToStaticMarkup(
+ createElement(MessagingBindingHelp, { channel: "feishu" as MessagingChannel }),
+ );
+ expect(feishu).not.toContain(S.messaging.troubleGroupPrivacy);
+ expect(feishu).not.toContain(S.messaging.troubleOnePoller);
+ });
+
it("puts each channel's tutorial link in its setup fold", () => {
const feishu = renderToStaticMarkup(
createElement(MessagingBindingHelp, { channel: "feishu" as MessagingChannel }),
@@ -233,3 +252,88 @@ describe("MessagingBindingHelp", () => {
expect(telegram).toContain(S.telegram.setupSteps[0]);
});
});
+
+describe("the Group Privacy copy, in both dictionaries", () => {
+ // `S` is the zh dictionary at import time, so each rule is asserted per dictionary — the
+ // two drifted apart once already (zh promised 三选一 and listed two options).
+ const entries = [
+ [en.messaging.troubleGroupPrivacy, "Making the bot an administrator"],
+ [zh.messaging.troubleGroupPrivacy, "把机器人设为该群的管理员"],
+ ] as const;
+
+ it("leads the fold entry with the admin route, then the @BotFather one", () => {
+ // Making the bot an administrator is the only remedy that fixes the group without
+ // touching its membership, and it is what a user whose bot already works has done — so
+ // it comes first, and the /setprivacy route (which requires a re-add) follows it.
+ for (const [entry, adminRemedy] of entries) {
+ expect(entry).toContain(adminRemedy);
+ expect(entry).toContain("/setprivacy");
+ expect(entry.indexOf(adminRemedy)).toBeLessThan(entry.indexOf("/setprivacy"));
+ }
+ });
+
+ it("points the toast at that fold instead of repeating the remedies in it", () => {
+ // The notice rides an `info` toast: four seconds, no hover-pause. So the toast carries
+ // the diagnosis and names the fold — by the fold's own title, which stays true if the
+ // fold is renamed — and the steps stay where they can be read.
+ for (const dict of [en, zh]) {
+ expect(dict.messaging.testPrivacyOn).toContain(dict.messaging.faqTroubleTitle);
+ expect(dict.messaging.testPrivacyOn).not.toContain("/setprivacy");
+ }
+ });
+});
+
+describe("telegramTestNotices", () => {
+ it("adds the privacy notice as a second line, leaving the success line untouched", () => {
+ // Two lines, not one longer one: the credentials passed and a direct chat will answer,
+ // so the success line is the truth and the privacy line is a separate caveat.
+ expect(
+ telegramTestNotices({
+ ok: true,
+ latencyMs: 12,
+ botUsername: "@penguin_bot",
+ groupPrivacy: true,
+ }),
+ ).toEqual([
+ { tone: "success", text: S.messaging.testOkAs("@penguin_bot", 12) },
+ { tone: "info", text: S.messaging.testPrivacyOn },
+ ]);
+ });
+
+ it("says nothing extra when privacy is off, or when getMe never reported it", () => {
+ expect(telegramTestNotices({ ok: true, latencyMs: 12, groupPrivacy: false })).toEqual([
+ { tone: "success", text: S.messaging.testOk(12) },
+ ]);
+ // Absent is unknown, and unknown is not a problem: a notice on a field the API never
+ // sent would send a user to @BotFather for nothing.
+ expect(telegramTestNotices({ ok: true, latencyMs: 12 })).toEqual([
+ { tone: "success", text: S.messaging.testOk(12) },
+ ]);
+ });
+
+ it("reports a failed test as one error line and nothing else", () => {
+ expect(telegramTestNotices({ ok: false, error: "Unauthorized", groupPrivacy: true })).toEqual([
+ { tone: "error", text: S.messaging.testFail("Unauthorized") },
+ ]);
+ });
+
+ it("is shown by testConnection, one toast per notice, each in its own tone", () => {
+ // The hook itself is out of reach from a node-only suite (`environment: "node"`, no
+ // jsdom), and dropping the info branch would silently lose the only line that reports
+ // Group Privacy — so the dispatch is pinned here (account-menu.test.ts convention).
+ const src = readFileSync(
+ fileURLToPath(
+ new URL("../src/features/messaging/messaging-binding-editor.tsx", import.meta.url),
+ ),
+ "utf8",
+ );
+ const loop = /for \(const notice of telegramTestNotices\(res\)\) \{[\s\S]*?\n {8}\}/.exec(src);
+ expect(
+ loop,
+ "testConnection should show every notice telegramTestNotices returns",
+ ).not.toBeNull();
+ expect(loop![0]).toContain("toastError(notice.text)");
+ expect(loop![0]).toContain("toastInfo(notice.text)");
+ expect(loop![0]).toContain("toastSuccess(notice.text)");
+ });
+});