General Discussion Backend

Telegram Bot API 10.2 移轉指南：豐富訊息、短暫編輯與社群功能

Telegram Bot API 10.2 看起來只是小幅版本更新，但實際上同時改變了多個生產環境機器人的核心部分……

Dev.to · Jul 30, 2026

Telegram Bot API 10.2 Migration Guide: Rich Messages, Ephemeral Edits, and Communities

Telegram Bot API 10.2 看起來只是小幅版本更新，但實際上同時改變了多個生產環境機器人的核心部分：

豐富訊息新增了具型別區塊與內嵌媒體
短暫訊息新增了完整的編輯與刪除生命週期
社群功能新增了拓撲事件與中繼資料
Mini App 加強了來源保護

Telegram 於 2026 年 7 月 14 日發布 Bot API 10.2。最安全的升級方式並非立即啟用所有新功能，而是先更新資料模型與事件分派器，再以功能旗標逐一測試每個輸出能力。

本指南將官方 Bot API 10.2 更新日誌轉化為實作檢查清單。

先繪製影響地圖

在修改程式碼前，請先將升級拆分為四個面向。

面向	主要變更	主要風險
豐富訊息	`media`、`blocks` 與新的 `InputRichBlock*` 型別	無效 payload 或 SDK 序列化不完整
短暫訊息	傳送、回覆、編輯與刪除生命週期	遺失使用者專屬訊息識別碼
社群	新的生命週期欄位與 `ChatFullInfo.community`	預設處理器遺漏拓撲事件
Mini App	跨來源方法保護	原可正常運作的跨來源呼叫遭到拒絕

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

合理的 rollout 順序為：

升級函式庫與型別
接收並儲存新欄位
新增分派器涵蓋
執行回歸測試
分別啟用輸出功能

1. 鎖定相容的 Bot API 函式庫

檢查您的 Telegram 函式庫是否已釋出相容 Bot API 10.2 的版本。

更新正式環境前，請先檢查：

產生的 API 型別
可選欄位的序列化
方法名稱與參數命名
Webhook 更新型別
重試與錯誤行為
對未知訊息欄位的支援

請勿假設升級套件會自動啟用新行為。有些函式庫可能先暴露新型別，但尚未完整支援所有方法。

請鎖定特定版本，而非使用開放範圍的相依性：

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

進入全螢幕模式退出全螢幕模式

請在分支中執行升級，並保留前一版本的相依性以便回滾。

2. 審核豐富訊息建構

Bot API 10.2 新增：

InputRichMessageMedia
InputMediaVoiceNote
media 於 InputRichMessage
blocks 於 InputRichMessage
完整 InputRichBlock* 建構器

根據 Bot API 參考文件，InputRichMessage 必須使用以下其中一種內容表示：

html
markdown
blocks

若您動態產生 payload，請在呼叫 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(
      "豐富訊息必須只包含 html、markdown 或 blocks 其中一種",
    );
  }
}

進入全螢幕模式退出全螢幕模式

新的 media 欄位用於在 HTML 或 Markdown 中嵌入媒體參考，例如：

tg://photo?id=product_photo

進入全螢幕模式退出全螢幕模式

啟用媒體前請先審核：

媒體識別碼在 payload 內是唯一的
參考的媒體確實存在於 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;
};

進入全螢幕模式退出全螢幕模式

函式庫呼叫可能如下（確切方法命名取決於您的 SDK）：

await bot.editEphemeralMessageText({
  chat_id: chatId,
  receiver_user_id: receiverUserId,
  ephemeral_message_id: ephemeralMessageId,
  text: "您的請求已更新。",
});

進入全螢幕模式退出全螢幕模式

請一併審核回覆建構。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);
}

進入全螢幕模式退出全螢幕模式

請勿用 Community ID 取代原始聊天 ID。

Community 描述拓撲，訊息仍需依其原始聊天識別碼儲存與路由。

實務上的中繼資料模型可同時保留兩者：

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

進入全螢幕模式退出全螢幕模式

當拓撲發生變化時：

持久化生命週期事件
更新關係狀態
以 getChat 調和目前資訊
保留稽核紀錄
繼續依原始聊天 ID 路由訊息

5. 處理額外的更新型別

Bot API 10.2 亦新增 BotSubscriptionUpdated 與 Update 上的 subscription 欄位。

即使您的機器人目前未使用付款訂閱，仍請確保 webhook 解碼器不會僅因出現此欄位而拒絕更新。

安全模式為：

解析已知頂層欄位
盡可能保留未知欄位
記錄事件類別（不含敏感 payload）
將不支援的更新路由至可觀察的備援處理器
避免讓整個 webhook 請求失敗

對每個未知更新都回傳非成功回應，會產生不必要的重試。

6. 重新檢查 Mini App 來源

Telegram 於 2026 年 7 月 20 日自動啟用更嚴格的 Mini App 來源保護，除非機器人透過 BotFather 選擇退出。

請審核：

已設定的 Mini App 網域
重新導向目的地
嵌入式驗證頁面
付款或支援頁面
導覽後的呼叫
Mini App 內開啟的第三方內容
開發與測試環境網域

請勿在未釐清哪個頁面發起呼叫的情況下，為了解決來源失敗而大範圍停用保護。

請分別測試正式環境網域與各個允許的非正式環境。

7. 避免不必要的輸入重寫

新的 InputRichMessage 建構器主要影響輸出路徑。

這不代表每個普通的輸入使用者訊息都必須突然被解析為豐富區塊樹。

您的輸入工作應聚焦於：

辨識新的社群服務訊息欄位
接收 subscription 更新
保留新的可選欄位
保留可觀察的未知事件備援
維持現有的文字、媒體與回呼處理

這是相容性更新，而非要您替換正常運作的輸入正規化管線。

8. 以獨立功能旗標部署

請使用獨立旗標，而非單一全域「Bot API 10.2」開關。

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

進入全螢幕模式退出全螢幕模式

這讓您可以立即接收社群事件，同時延後新的輸出格式。

安全的 rollout 流程如下：

升級相依性
        ↓
接收新的 webhook 欄位
        ↓
部署時停用輸出旗標
        ↓
驗證正常輸入流量
        ↓
內部啟用單一輸出功能
        ↓
監控錯誤與 payload
        ↓
逐步擴展

進入全螢幕模式退出全螢幕模式

至少監控：

Telegram API 錯誤碼
序列化失敗
未知更新次數
社群拓撲變更
短暫訊息編輯/刪除失敗
豐富訊息備援使用率
Webhook 重試量

9. 建立回滾路徑

正式環境 rollout 前，請記錄：

先前的函式庫版本
新的資料庫欄位
功能旗標預設值
payload 格式差異
可逆與不可逆的遷移
回滾負責人
監控閾值

若新欄位為可選，請優先使用附加式資料庫變更。不要讓先前的應用程式版本無法讀取 rollout 期間建立的紀錄。

回滾應停用新傳送，但仍接受已送達的 webhook 欄位。

最終升級檢查清單

[ ] 已鎖定 Bot API 函式庫版本
[ ] 已檢查新的 SDK 型別與序列化
[ ] 現有輸入回歸測試通過
[ ] 已強制執行僅一種豐富訊息表示法
[ ] 已驗證豐富訊息媒體參考
[ ] 已提供純文字備援
[ ] 已持久化短暫訊息識別碼
[ ] 已測試短暫訊息編輯與刪除失敗路徑
[ ] 社群生命週期事件已有明確處理器分支
[ ] 社群拓撲與聊天路由分開儲存
[ ] subscription 更新不會破壞 webhook 解碼
[ ] 已檢查 Mini App 正式與測試來源
[ ] 輸出功能使用獨立旗標
[ ] 未知更新仍可觀察
[ ] 已記錄相依性與功能回滾步驟

只要將 Bot API 10.2 視為多個小型遷移，而非單一大型功能上線，就能夠順利管理。

請先更新相容層。等到底層欄位、路由規則與回滾路徑準備好後，再啟用豐富訊息、短暫訊息編輯與社群感知行為。

官方參考文件

原文發表於 UnifyPort。

本文由 AI 協助語言與結構，作者再進行技術審核與驗證。

Read the original source Next news

#Backend

Telegram Bot API 10.2 移轉指南：豐富訊息、短暫編輯與社群功能

先繪製影響地圖

1. 鎖定相容的 Bot API 函式庫

2. 審核豐富訊息建構

3. 保留短暫訊息識別碼

4. 將社群事件加入分派器

5. 處理額外的更新型別

6. 重新檢查 Mini App 來源

7. 避免不必要的輸入重寫

8. 以獨立功能旗標部署

9. 建立回滾路徑

最終升級檢查清單

官方參考文件

0 Comments