← 所有文章
指南

Telegram Bot API 10.2 升级清单：Rich Messages 媒体、Ephemeral 编辑与 Communities

Telegram 于 2026 年 7 月 14 日发布 Bot API 10.2，这次改动的代码量比版本号暗示的要大。Rich Messages 增加了媒体与 block 级构建器，ephemeral 消息补齐了完整的编辑/删除方法集，Communities 引入了需要存储的新拓扑结构。对多平台团队而言，稳妥的做法是上线前走一遍清单：锁定版本、迁移受影响的方法、在改动任何生产机器人之前把 inbound 归一化保留在单一 webhook 上。

关键结论

  • 10.2 于 2026 年 7 月 14 日发布，新增 rich message 的 media、完整的 InputRichBlock* 构建器集、ephemeral 编辑/删除方法，以及 Communities 生命周期消息——全部来自 core.telegram.org 的官方文档。
  • 三处接近 breaking 的改动需要代码评审：InputRichMessage 上的新 media/blocks 字段、多个 send* 方法上的 receiver_user_id/ephemeral_message_id 参数，以及 community_chat_added/community_chat_removed 消息类型。
  • Rich Messages 在官方 Bot API 上仅限 outbound。 inbound 用户消息仍以纯文本/markdown 到达——除非你自己构建富 UI，否则 inbound 流水线无需解析 rich block。
  • Communities 增加的是路由状态，而非消息合并。 Community 链接多个 supergroup、channel 与 bot；消息仍属于原始 chat ID，必须按 chat 路由。
  • 在 feature flag 后面做升级，并确认你的 Bot API 库已发布 10.2 兼容版本，再把生产流量切过去。

Bot API 10.2 实际改了什么

以下内容来自官方 Bot API changelog 的逐字记录，按团队真正需要动手的区域分组。

Rich Messages：媒体与 block 构建器

10.1 引入了 Rich Messages——结构化、可流式 AI 生成的格式化文本。10.2 让它们能承载真实内容：

  • 新增 InputRichMessageMedia 类与 InputRichMessage 上的 media 字段，让 bot 可以“在发送 rich message 时显式指定 markdown 或 html 格式中所用的媒体”。
  • 新增 InputMediaVoiceNote 类。
  • 新增 InputRichBlockListItem 与完整的输入 block 类集合：InputRichBlockParagraph、InputRichBlockSectionHeading、InputRichBlockPreformatted、InputRichBlockFooter、InputRichBlockDivider、InputRichBlockMathematicalExpression、InputRichBlockAnchor、InputRichBlockList、InputRichBlockBlockQuotation、InputRichBlockPullQuotation、InputRichBlockCollage、InputRichBlockSlideshow、InputRichBlockTable、InputRichBlockDetails、InputRichBlockMap、InputRichBlockAnimation、InputRichBlockAudio、InputRichBlockPhoto、InputRichBlockVideo、InputRichBlockVoiceNote、InputRichBlockThinking。
  • 在 InputRichMessage 上新增 blocks 字段，让 bot 可以“通过 block 实体指定 rich message 格式”。

实际影响：10.1 让你能“发送”rich message，10.2 让你能用类型化 block 组装它并附加媒体。任何直接构造 InputRichMessage 字面量的代码都应重新检查，因为库升级后可能期望 blocks 而非内联字符串。

Ephemeral 消息：完整的编辑/删除生命周期

ephemeral 消息（仅对一个用户和 bot 可见的群消息）同样更早出现，但 10.2 补齐了方法集：

  • 在 BotCommand 上新增 is_ephemeral。
  • 在 Message 类上新增 receiver_user 与 ephemeral_message_id。
  • 在 sendMessage、sendAnimation、sendAudio、sendDocument、sendLivePhoto、sendPhoto、sendSticker、sendVideo、sendVideoNote、sendVoice、sendContact、sendLocation、sendVenue 上新增 receiver_user_id 与 callback_query_id 参数。
  • 在 ReplyParameters 上新增 ephemeral_message_id（并在其存在时让 message_id 变为可选）。
  • 新增 editEphemeralMessageText、editEphemeralMessageMedia、editEphemeralMessageCaption、editEphemeralMessageReplyMarkup、deleteEphemeralMessage。

如果你的客服 bot 目前能在群里发私密回复却无法编辑它，10.2 正是补上这一缺口的升级。你仍需是群管理员，详见 ephemeral 消息指南。

Communities：新消息类型

Communities 是“围绕同一主题或受众链接在一起的若干 supergroup、channel 与 bot”。对 webhook 消费者而言，关键新增项是：

  • Community 类。
  • CommunityChatAdded 与 CommunityChatRemoved 消息类，以及它们在 Message 上的字段。
  • ChatFullInfo 上的 community 字段。

这些生命周期消息与 Communities 事件处理指南 描述的是同一接口。对升级清单而言规则更简单：如果你的 switch 语句以 message.text 为键，遇到未知类型会落入默认分支，那么 community_chat_added/community_chat_removed 会被悄悄丢弃。显式处理它们，才能记录 Community 拓扑变更。

通用改动

  • 新增 BotSubscriptionUpdated（以及 Update 上的 subscription 字段），表示用户付款订阅变更。
  • 加强 Mini App 安全：禁止来自不同 origin 的方法调用，自 2026 年 7 月 20 日 起自动启用（在 BotFather 中可 opt-out）。

升级清单

在把流量切到 10.2 bot 之前完成这些项。

序号动作重要性
1把 Bot API 库锁定到 10.2 兼容版本（如 .NET 上的 Telegram.BotAPI 10.2.0）未类型化或旧版客户端会忽略新字段，悄悄发送降级消息
2审查每一处 sendRichMessage / InputRichMessage 构造新的 media 与 blocks 字段改变了 rich message 的组装方式
3在消息处理器中加入 community_chat_added / community_chat_removed未知消息类型会落入默认分支并被丢失
4决定是否采用新的 ephemeral 编辑/删除方法让客服 bot 能修正私密回复而无需重发
5在 chat 元数据中存储 ChatFullInfo 的 community之后推理 Community 拓扑时需要
6在 2026 年 7 月 20 日前测试 Mini App origin 处理该日起跨 origin 调用开始被拦截
7把 inbound 归一化保留在单一 webhookRich block 仅限 outbound；inbound 仍以纯文本到达

10.2 对 inbound 团队没有改变什么

最重要的非变化是：来自用户的 inbound 消息仍以普通文本到达。 用户在 Telegram 聊天里打字，并不会在你的端上产生 RichMessage 对象——Rich Messages 是 bot 发送 能力。这与此前 Bot API 10.1 分析 的结论一致：inbound 的问题是跨平台格式归一化，而非解析 rich block。

也就是说，目标是接收和分流消息的团队，无需为采用 10.2 而重写 inbound 解析器。这次升级关乎的是你的 bot 回发什么。

UnifyPort 在其中的位置

UnifyPort 把 inbound Telegram 消息（连同 WhatsApp、LINE、X、Zalo、TikTok）以统一归一化的 message.received 事件流投递，因此 10.2 升级的 inbound 部分——接收用户消息、校验 HMAC-SHA256 签名、按会话路由——无论 Bot API 版本如何都保持不变。

webhook 事件目录是稳定的：message.received、message.updated、message.deleted、message.read、message.reaction，加上会话与账号生命周期事件。每次投递都带 X-Device-Event-Id、X-Device-Delivery-Id、X-Device-Timestamp，以及当 endpoint 配置了 signing_secret 时的 hex 编码 X-Device-Signature（"<时间戳>" + "." + "<原始 body>" 的 HMAC-SHA256）。你用原始 body 校验、解析 JSON、按 event.type 分支——webhook 投递与签名指南 记录了完整的校验流程。

如果你的升级目标纯粹是跨平台 inbound 可靠性，完全无需触碰官方 Bot API。如果你同时想用自己的 Telegram bot 代码发送 rich 或 ephemeral 回复，那才是 10.2 改动适用的地方——UnifyPort 的 Telegram 授权 介绍了连接账号所需的 api_id / api_hash / 手机号流程。

限制与权衡

  • Rich Messages 需要兼容客户端。 非常旧的 Telegram 客户端可能无法渲染 rich block；要为纯文本设计降级方案。
  • ephemeral 消息需要群管理员权限，且只能触达一个用户——它不是广播工具。
  • Communities 是新功能且仍在演进。 不要假设今天已存在 Community 级别的消息聚合；按 chat ID 路由，并在到达时存储拓扑。
  • 官方 Bot API 仍只是一个平台。 如果你的团队还要处理 WhatsApp、LINE 或 X 的 inbound，采用 10.2 只解决 Telegram 这一侧——跨平台 inbound 问题需要单独处理。

FAQ

Bot API 10.2 什么时候发布？

Telegram 于 2026 年 7 月 14 日 发布 Bot API 10.2，依据是 core.telegram.org/bots/api-changelog 的官方 changelog。主要新增是 Rich Message 媒体与 block 构建器、完整的 ephemeral 消息编辑/删除方法集，以及 Communities。

我必须立即升级吗？

没有截止日期强制升级接收功能。唯一有时限的是自 2026 年 7 月 20 日 起的 Mini App origin 强制检查；如果你运行 Mini App，请在该日期前测试跨 origin 行为。

10.2 之后 inbound 消息格式会变吗？

不会。Rich Messages 是 bot 的 outbound 能力。inbound 用户消息仍以纯文本或 markdown 到达，因此你的 inbound 解析器无需支持 rich block。

Communities 和群聊是一回事吗？

不是。Community 是一组链接的 supergroup、channel 与 bot。消息仍属于原始 chat，你按 chat ID 路由和存储。新增的 community_chat_added 与 community_chat_removed 消息类型用于追踪拓扑变更。

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

UnifyPort 把 Telegram inbound 以统一 webhook 上的归一化 message.* 与生命周期事件投递。对 Community 特有的拓扑事件，按 Communities 事件指南 描述的方式处理——保留 service-message 字段，并用 getChat 对账。

下一步

  • 查阅 webhook 事件目录，确认你的 inbound 处理器已覆盖标准 message.* 事件：见 provider message support 参考。
  • 如果你首次连接 Telegram 账号，Quickstart 会带你发送和接收第一条消息。

来源

  • Telegram Bot API changelog（官方）：https://core.telegram.org/bots/api-changelog — Bot API 10.2，2026-07-14。核验于 2026-07-30。
  • Telegram Bot API 参考（官方）：https://core.telegram.org/bots/api。核验于 2026-07-30。