Telegram Bot API 10.2 迁移指南：富消息、临时消息编辑和社区功能

Telegram Bot API 10.2 看似只是一个小版本更新，但它同时改变了生产环境机器人的多个部分：

• 富消息支持类型化块和嵌入媒体
• 临时消息支持完整的编辑和删除生命周期
• 社区功能引入新的拓扑事件和元数据
• Mini App 获得更严格的来源保护

Telegram 于 2026 年 7 月 14 日发布了 Bot API 10.2。最安全的升级方式不是立即启用所有新功能。首先更新您的数据模型和事件分发器，然后在功能开关后面测试每个出站功能。

本指南将 官方 Bot API 10.2 变更日志 转化为实施清单。

从影响图开始

在修改代码之前，请将升级分为四个领域。

领域	主要变更	主要风险
富消息	media、blocks 和新的 InputRichBlock* 类型	无效载荷或不完整的 SDK 序列化
临时消息	发送、回复、编辑和删除生命周期	丢失用户特定的消息标识符
社区	新的生命周期字段和 ChatFullInfo.community	在默认处理程序中丢弃拓扑事件
Mini App	跨来源方法保护	之前可用的跨来源调用被拒绝

您不必在同一部署中启用所有功能。

合理的推出顺序是：

1. 升级库和类型
2. 接受并存储新字段
3. 添加分发器覆盖
4. 运行回归测试
5. 单独启用出站功能

1. 固定兼容的 Bot API 库版本

检查您的 Telegram 库是否已发布与 Bot API 10.2 兼容的版本。

在更新生产环境之前，请检查：

• 生成的 API 类型
• 可选字段的序列化
• 方法名称和参数大小写
• Webhook 更新类型
• 重试和错误行为
• 对未知消息字段的支持

不要假设升级包会自动启用新行为。某些库可能在完全支持所有方法之前就暴露新类型。

固定所选版本，而不是使用开放式依赖范围：

{
  "dependencies": {
    "your-telegram-library": "PINNED_COMPATIBLE_VERSION"
  }
}

Enter fullscreen mode Exit fullscreen mode

在分支中运行升级，并保留之前的依赖版本以便回滚。

2. 审计富消息构建

Bot API 10.2 新增：

• InputRichMessageMedia
• InputMediaVoiceNote
• media 于 InputRichMessage
• blocks 于 InputRichMessage
• 完整的 InputRichBlock* 构建器集

根据 Bot API 参考，InputRichMessage 必须使用以下内容表示形式之一：

• html
• markdown
• blocks

如果您动态生成载荷，请在调用 API 前验证此规则。

function validateRichMessage(input: {
  html?: string;
  markdown?: string;
  blocks?: unknown[];
  media?: unknown[];
}) {
  const representations = [
    input.html,
    input.markdown,
    input.blocks,
  ].filter((value) => value !== undefined);

  if (representations.length !== 1) {
    throw new Error(
      "A rich message must contain exactly one of html, markdown, or blocks",
    );
  }
}

Enter fullscreen mode Exit fullscreen mode

新的 media 字段与嵌入在 HTML 或 Markdown 中的媒体引用一起使用，例如：

tg://photo?id=product_photo

Enter fullscreen mode Exit fullscreen mode

在启用媒体之前请检查以下内容：

• 媒体标识符在载荷内是唯一的
• 引用的媒体确实存在于 media 数组中
• 机器人有权限发送该媒体类型
• 提供纯文本回退
• 您的 SDK 在序列化期间保留所有新字段

在依赖升级期间，不要静默地将现有的 Markdown 构建器转换为块构建器。请将其视为单独的功能变更。

3. 保留临时消息身份

Bot API 10.2 完善了临时消息生命周期，新增：

• editEphemeralMessageText
• editEphemeralMessageMedia
• editEphemeralMessageCaption
• editEphemeralMessageReplyMarkup
• deleteEphemeralMessage

它还在 Message 中添加了 receiver_user 和 ephemeral_message_id。

普通消息 ID 不足以管理临时消息。请存储完整的路由身份：

type EphemeralMessageReference = {
  chatId: string;
  receiverUserId: number;
  ephemeralMessageId: number;
};

Enter fullscreen mode Exit fullscreen mode

库调用可能类似于以下内容，尽管确切的方法命名取决于您的 SDK：

await bot.editEphemeralMessageText({
  chat_id: chatId,
  receiver_user_id: receiverUserId,
  ephemeral_message_id: ephemeralMessageId,
  text: "Your request has been updated.",
});

Enter fullscreen mode Exit fullscreen mode

还要检查回复构建。在 Bot API 10.2 中，当 ephemeral_message_id 存在时，ReplyParameters.message_id 变为可选。

您的实现应测试：

• 发送给目标用户
• 编辑文本
• 编辑媒体或标题
• 更新回复标记
• 删除消息
• 拒绝来自错误用户上下文的编辑
• 处理过期或未知的标识符
• 防止重试创建重复回复

临时消息是用户特定的。切勿将其视为群组广播机制。

4. 向分发器添加社区事件

社区将超级群组、频道和机器人围绕共享主题或受众联系起来。

Bot API 10.2 引入：

• Community
• CommunityChatAdded
• CommunityChatRemoved
• message.community_chat_added
• message.community_chat_removed
• ChatFullInfo.community

仅检查 message.text 的处理程序可能会静默丢弃这些服务消息。

添加显式分支：

function handleMessage(message: TelegramMessage) {
  if (message.community_chat_added) {
    recordCommunityChatAdded(message);
    return;
  }

  if (message.community_chat_removed) {
    recordCommunityChatRemoved(message);
    return;
  }

  if (message.text) {
    handleTextMessage(message);
    return;
  }

  handleUnknownMessageType(message);
}

Enter fullscreen mode Exit fullscreen mode

不要使用社区 ID 代替原始聊天 ID。

社区描述拓扑。消息仍需根据其原始聊天身份进行存储和路由。

实用的元数据模型可以同时保留两者：

type CommunityChatRelation = {
  communityId: string;
  chatId: string;
  relationStatus: "active" | "removed";
  observedAt: string;
};

Enter fullscreen mode Exit fullscreen mode

当拓扑发生变化时：

1. 持久化生命周期事件
2. 更新关系状态
3. 使用 getChat 协调当前信息
4. 保留审计记录
5. 继续按原始聊天 ID 路由消息

5. 处理额外的更新类型

Bot API 10.2 还添加了 BotSubscriptionUpdated 和 Update 上的 subscription 字段。

即使您的机器人目前不使用支付订阅，也要确保 webhook 解码器不会仅仅因为存在此字段就拒绝更新。

安全模式是：

• 解析已知的顶级字段
• 尽可能保留未知字段
• 在不包含敏感载荷数据的情况下记录事件类别
• 将不支持的更新路由到可观察的回退
• 避免使整个 webhook 请求失败

对每个未知更新返回非成功响应可能会造成不必要的重试。

6. 重新检查 Mini App 来源

除非机器人通过 BotFather 选择退出，否则 Telegram 于 2026 年 7 月 20 日自动启用了更严格的 Mini App 来源保护。

审计：

• 配置的 Mini App 域名
• 重定向目标
• 嵌入式身份验证页面
• 支付或支持页面
• 导航后进行的调用
• Mini App 内打开的第三方内容
• 开发和暂存域名

不要在不了解哪个页面发起调用的情况下，通过广泛禁用保护来解决来源失败。

分别测试生产域名和每个允许的非生产环境。

7. 避免不必要的入站重写

新的 InputRichMessage 构建器主要影响出站路径。

这并不意味着每个普通的入站用户消息都必须突然被解析为富块树。

您的入站工作应专注于：

• 识别新的社区服务消息字段
• 接受 subscription 更新
• 保留新的可选字段
• 保留可观察的未知事件回退
• 维护现有的文本、媒体和回调处理

这是一次兼容性更新，而不是替换正常工作的入站规范化管道的理由。

8. 在单独的功能开关后面部署

使用独立开关而不是一个全局的“Bot API 10.2”开关。

const telegramFeatures = {
  richMessageBlocks: false,
  richMessageMedia: false,
  ephemeralEdits: false,
  communityTopology: true,
};

Enter fullscreen mode Exit fullscreen mode

这让您可以立即接受社区事件，同时延迟新的出站格式。

安全推出如下所示：

Upgrade dependency
        ↓
Accept new webhook fields
        ↓
Deploy with outbound flags disabled
        ↓
Verify normal inbound traffic
        ↓
Enable one outbound feature internally
        ↓
Monitor errors and payloads
        ↓
Expand gradually

Enter fullscreen mode Exit fullscreen mode

至少监控：

• Telegram API 错误代码
• 序列化失败
• 未知更新数量
• 社区拓扑变化
• 临时编辑/删除失败
• 富消息回退使用情况
• Webhook 重试量

9. 构建回滚路径

在生产推出之前，记录：

• 之前的库版本
• 新的数据库字段
• 功能开关默认值
• 载荷格式差异
• 可逆和不可逆迁移
• 回滚负责人
• 监控阈值

如果新字段是可选的，请优先使用增量数据库更改。不要使之前的应用程序版本无法读取在推出期间创建的记录。

回滚应禁用新的发送，同时仍接受已传递的 webhook 字段。

最终升级清单

• [ ] Bot API 库版本已固定
• [ ] 已检查新的 SDK 类型和序列化
• [ ] 现有的入站回归测试通过
• [ ] 强制执行恰好一种富消息表示形式
• [ ] 已验证富消息媒体引用
• [ ] 提供纯文本回退
• [ ] 已持久化临时消息标识符
• [ ] 已测试临时编辑和删除失败路径
• [ ] 社区生命周期事件具有显式处理程序分支
• [ ] 社区拓扑与聊天路由分开存储
• [ ] subscription 更新不会破坏 webhook 解码
• [ ] 已检查 Mini App 生产和暂存来源
• [ ] 出站功能使用单独的开关
• [ ] 未知更新保持可观察
• [ ] 已记录依赖和功能回滚步骤

当 Bot API 10.2 被视为几次小的迁移而不是一个大型功能发布时，它是可管理的。

首先更新兼容层。只有在底层字段、路由规则和回滚路径准备就绪后，才启用富消息、临时编辑和社区感知行为。

官方参考

• Telegram Bot API 10.2 变更日志
• Telegram Bot API 参考

---

最初发布于 UnifyPort。

本文在语言和结构方面得到了 AI 协助准备，然后由作者进行了技术审查和验证。