← 所有文章
指南

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 問題需要另行處理。

常見問題

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。