← 所有文章
指南

Telegram Bot API 10.2 升級清單：Rich Messages 媒體、Ephemeral 編輯同 Communities

Telegram 喺 2026 年 7 月 14 號推出 Bot API 10.2，今次改動嘅碼量大過個版號暗示嘅。Rich Messages 加咗媒體同 block 級建構器，ephemeral 訊息補齊晒完整嘅編輯/刪除方法集，Communities 帶入咗要儲存嘅新拓撲。對多平台團隊嚟講，穩陣嘅做法係上線前行勻張清單：鎖定版本、搬走受影響嘅方法、喺郁任何 production bot 之前將 inbound 歸一化留喺單一 webhook 度。

重點結論

  • 10.2 喺 2026 年 7 月 14 號推出，加咗 rich message 嘅 media、完整嘅 InputRichBlock* 建構器集、ephemeral 編輯/刪除方法，同 Communities 生命週期訊息——全部來自 core.telegram.org 官方文件。
  • 三處接近 breaking 嘅改動要做 code review：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 pipeline 唔使解析 rich block。
  • Communities 加嘅係路由狀態，唔係訊息合併。 Community 連結多個 supergroup、channel 同 bot；訊息依然屬於原本 chat ID，要按 chat 路由。
  • 喺 feature flag 後面做升級，同埋確認你個 Bot API library 已經出咗 10.2 相容版本，先好將 production 流量切過去。

Bot API 10.2 實際改咗咩

以下內容來自官方 Bot API changelog 嘅逐字紀錄，按團隊真正要落手嘅區域分組。

Rich Messages：媒體同 block 建構器

10.1 引入咗 Rich Messages——結構化、可串流 AI 產生嘅格式化文字。10.2 等佢哋承載到真實內容：

  • 新增 InputRichMessageMedia class 同 InputRichMessage 上面嘅 media 欄位，等 bot 可以「喺發送 rich message 嗰陣明確指定 markdown 或 html 格式度用嘅媒體」。
  • 新增 InputMediaVoiceNote class。
  • 新增 InputRichBlockListItem 同完整嘅輸入 block class 集：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 等你可以用 typed block 砌佢同附加媒體。任何直接建構 InputRichMessage 字面值嘅碼都要再 check，因為 library 升級之後可能期望 blocks 而唔係內聯字串。

Ephemeral 訊息：完整嘅編輯/刪除生命週期

ephemeral 訊息（淨係對一個用戶同 bot 可見嘅群訊息）都係早過出現，不過 10.2 補齊晒方法集：

  • 喺 BotCommand 上面新增 is_ephemeral。
  • 喺 Message class 上面新增 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 class。
  • CommunityChatAdded 同 CommunityChatRemoved 訊息 class，同佢哋喺 Message 上面嘅欄位。
  • ChatFullInfo 上面嘅 community 欄位。

呢啲生命週期訊息同 Communities 事件處理指南 描述嘅係同一介面。對升級清單嚟講規則更簡單：如果你個 switch 陳述式用 message.text 做 key，遇到未知類型會跌入預設分支，咁 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 library 鎖定到 10.2 相容版本（例如 .NET 上面嘅 Telegram.BotAPI 10.2.0）未型別化或舊版 client 會忽略新欄位，靜靜雞發降級訊息
2審查每處 sendRichMessage / InputRichMessage 建構新嘅 media 同 blocks 欄位改變咗 rich message 嘅組裝方式
3喺訊息處理器加入 community_chat_added / community_chat_removed未知訊息類型會跌入預設分支同被遺失
4決定係咪採用新嘅 ephemeral 編輯/刪除方法等客服 bot 可以修正私密回覆而唔使重發
5喺 chat metadata 儲存 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 要相容 client。 太舊嘅 Telegram client 可能 render 唔到 rich block；要為純文字設計降級方案。
  • ephemeral 訊息要群組管理員權限，同淨係觸得到一個用戶——佢唔係廣播工具。
  • Communities 係新功能同仲演緊。 唔好假設今日已經有 Community 級別嘅訊息聚合；按 chat ID 路由，同喺到達嗰陣儲存拓撲。
  • 官方 Bot API 依然淨係一個平台。 如果你個團隊仲要處理 WhatsApp、LINE 或 X 嘅 inbound，採用 10.2 淨係解決 Telegram 呢邊——跨平台 inbound 問題要另行處理。

常見問題

Bot API 10.2 幾時出？

Telegram 喺 2026 年 7 月 14 號 出 Bot API 10.2，依據係 core.telegram.org/bots/api-changelog 嘅官方 changelog。主要新增係 Rich Message 媒體同 block 建構器、完整嘅 ephemeral 訊息編輯/刪除方法集，同 Communities。

我一定要即刻升級咩？

無 deadline 強制升級接收功能。唯一有時限嘅係由 2026 年 7 月 20 號 起嘅 Mini App origin 強制檢查；如果你 run 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。