Telegram Bot API 10.2 Communities：处理群聊加入与移除事件

Telegram Bot API 10.2 的 Communities 可以把多个超级群组、频道和机器人关联到同一个主题下。当前聊天加入 Community 时，机器人会在普通 Message 中收到 community_chat_added；移除时则收到 community_chat_removed。这两个字段应当作为拓扑生命周期信号处理：及时缓存聊天与 Community 的关系，但仍按各自的 chat 路由消息，因为 Community 不会把所有聊天合并成一个消息流。

核心结论

• Telegram 在 2026 年 7 月 14 日发布 Communities，并为 Bot API 提供初步支持。
• community_chat_added 包含新的 Community 对象；community_chat_removed 目前不包含字段。
• 两者都是 Message 内的服务消息字段，不是新的顶层 Update 类型。
• 移除事件不会再次给出 Community 信息，因此必须在加入时保存关系。
• Telegram 社区拓扑与 WhatsApp、LINE、Zalo 等渠道的统一客服队列是两层不同的数据。

Bot API 10.2 为 Telegram Communities 增加了什么

Telegram 的官方公告把 Community 定义为围绕同一主题关联起来的一组群组、频道或机器人。成员可以直接发现并加入可见聊天，不必逐个寻找邀请链接；聊天也可以设为隐藏，仅对该聊天成员和 Community 管理员可见。默认情况下成员可以添加聊天，管理员也可以收紧权限，让新增内容先成为建议。

Bot API 10.2 明确把这称为“初步支持”。当前接口边界很小，但足以维护关系缓存：

Bot API 字段	能确认的事实	不能据此推断的内容
Message.community_chat_added	当前聊天已加入，并提供新的 Community 对象	Community 内所有聊天的完整历史
Message.community_chat_removed	当前聊天已被移除	它离开的是哪个 Community；当前对象为空
ChatFullInfo.community	getChat 查询结果中的当前 Community（如有）	跨聊天的统一收件箱或统一权限模型

这与群组内的 Telegram 临时机器人消息不同，后者控制谁能看见回复；也与 Bot API 10.1 Rich Messages不同，后者控制消息排版。Communities 描述的是聊天之间的拓扑关系。

如何处理 community_chat_added 与 community_chat_removed

1. 先确保 Bot API 客户端不会丢弃新字段

把使用的类型定义或 SDK 升级到支持 Bot API 10.2 的版本。如果框架在反序列化时会移除未知的 Message 字段，即使 Telegram 已经投递事件，应用也可能看不到 Communities 信号。

若你限制了 allowed_updates，至少保留 message；当 Community 中有频道时，也应在测试环境验证 channel_post。官方把这些字段定义在共享的 Message 类型上，并没有为它们新增顶层 Update。不要在看见真实测试事件前假定某个框架自定义的事件名。

2. 收到加入事件后立即持久化

下面的 Node.js 处理器只读取官方当前明确记录的字段，并原样保存整个 Community 对象，不假设它的内部属性：

async function handleTelegramUpdate(update, store) {
  const message = update.message ?? update.channel_post;
  if (!message) return;

  if (message.community_chat_added) {
    await store.upsertCommunityMembership({
      chatId: String(message.chat.id),
      community: message.community_chat_added.community,
      updateId: update.update_id,
      observedAt: new Date(message.date * 1000).toISOString(),
    });
  }

  if (Object.hasOwn(message, "community_chat_removed")) {
    await store.removeCommunityMembership({
      chatId: String(message.chat.id),
      updateId: update.update_id,
    });
  }
}

把 update_id 作为幂等键。Telegram 说明它通常按顺序增长，可用于去重和恢复处理顺序；尚未消费的更新最多保留 24 小时，因此 webhook 队列不能代替你自己的历史记录。

3. 移除时按 chat ID 查旧关系

CommunityChatRemoved 当前是空对象，这是实现时最容易忽略的边界。移除处理器必须使用 message.chat.id 找到此前缓存的关系，不能尝试从移除对象中读取不存在的 Community ID。

加入和移除都应幂等：重复加入只更新同一条关系；关系已经删除后再次收到移除事件应当安全地无操作。如果管理员需要审计变化时间，可保存原始更新或精简后的审计记录。

4. 用 getChat 核对当前状态

Bot API 10.2 在 ChatFullInfo 中增加了可选的 community 字段，getChat 会返回这个类型。webhook 重连、SDK 升级或发现 update_id 缺口时，可以用它核对缓存；没有异常时不必持续轮询所有聊天。

在非生产 Community 中至少验证：添加超级群组、移除群组、重复投递同一个 update_id、通过 getChat 对账，以及真实管理员角色下的可见和隐藏聊天。

Community 拓扑不要与消息路由混在一起

Community 让 Telegram 内相关聊天更容易被发现和组织，但不会合并消息历史、权限、chat ID 或机器人访问权。

需求	应使用的数据源
Telegram 聊天加入或离开 Community	官方 Bot API 10.2 服务消息与 getChat
机器人接收 Telegram 聊天中的普通消息	官方 Bot API 更新及其访问权限
团队接收多个平台普通账号的客户消息	UnifyPort message.received 等标准入站层

对于同时经营 WhatsApp、LINE、Zalo、TikTok 或 X 的出海团队，这个区别尤其重要。Telegram Community 只能组织 Telegram 内的表面，不能自动统一其他平台。Telegram 原生自动化与跨渠道队列指南进一步解释了两者的边界。

UnifyPort 适合放在哪一层

UnifyPort 不会创建 Telegram Communities，也不提供 CommunityChatAdded、Community 可见性或官方 Bot API 生命周期管理。需要这些能力时，应直接使用 Telegram 官方 API。

UnifyPort 承接的是另一个需求：让 Telegram 以及其他受支持平台的普通账号入站消息进入同一标准事件流。受支持的消息会以 message.received 到达，统一信封包含 id、type、provider、account_id、occurred_at 和 data。webhook endpoint 配置 signing_secret 后，投递会携带 X-Device-Timestamp 与 X-Device-Signature，用于 HMAC-SHA256 验证。

建议分开存储：Telegram Community 关系放在拓扑表；客户会话按 provider、account 和 conversation 放在消息队列。不要把 community_chat_added 转换成 message.received，它们描述的不是同一个事实。

限制与取舍

Bot API 10.2 提供的是初步生命周期信息，不是完整的 Community 管理 API。移除对象为空，官方文档也没有承诺历史成员关系查询。因此应用需要自己的缓存，并按真实聊天类型测试更新信封。

机器人、Community 关系、Telegram 角色和隐藏聊天应使用官方 Bot API。非官方接口不能授予这些官方权限，也不能把 Community 权限扩展到其他平台。反过来，Community 本身也不能替代跨平台的统一入站队列。

常见问题

Bot API 10.2 中的 Telegram Community 是什么？

它把多个 Telegram 超级群组、频道或机器人关联到同一主题下。Bot API 10.2 通过 Community、community_chat_added、community_chat_removed 和 ChatFullInfo.community 提供初步生命周期信息。

community_chat_added 在 webhook 的哪个位置？

它位于 Update 中的 Bot API Message 内，不是新的顶层 Update 字段；该对象包含当前聊天加入的 Community。

community_chat_removed 包含哪些数据？

当前不包含字段。应当用当前 message.chat.id 删除此前保存的关系。

Communities 会合并所有聊天的消息吗？

不会。它组织发现和成员关系，每个聊天仍有独立消息、权限、标识符和机器人访问要求。

UnifyPort 能接收 Community 生命周期事件吗？

当前 UnifyPort API Reference 没有把这两个 Telegram 字段定义为标准事件。Community 生命周期走官方 Bot API；UnifyPort 只承接其文档中已明确支持的标准入站消息层。

下一步

如果真实目标是跨渠道客服队列，先核对各平台消息支持矩阵，再按 message.received API Reference 实现入站处理，不要与 Telegram Community 状态混用。

来源

官方来源核验于 2026 年 7 月 26 日：

• Telegram：Communities 发布公告
• Telegram Bot API 10.2 changelog 与 Community 类型
• Telegram：CommunityChatAdded
• Telegram：CommunityChatRemoved
• Telegram：setWebhook 与更新投递