Telegram Bot API 10.2 Communities：處理聊天室加入與移除事件
Telegram Bot API 10.2 的 Communities 能把多個超級群組、頻道與機器人連結在同一主題下。當目前聊天室加入 Community，機器人會在一般 Message 裡收到 community_chat_added；移除時則收到 community_chat_removed。應把它們視為拓撲生命週期訊號：先保存聊天室與 Community 的關係，但訊息仍按各自 chat 處理，因為 Communities 不會產生一條共用訊息串流。
重點整理
- Telegram 在 2026 年 7 月 14 日推出 Communities 與 Bot API 的初步支援。
community_chat_added帶有新的Community物件；community_chat_removed目前是空物件。- 兩者都是
Message內的服務訊息欄位，不是新的頂層Update類型。 - 移除事件不會重複提供 Community，因此加入時就要保存對應關係。
- Telegram 社群拓撲與 WhatsApp、LINE、Zalo 等平台的跨渠道客服佇列應分開建模。
Bot API 10.2 對 Telegram Communities 開放了哪些資料
依照 Telegram 的官方公告，Community 可連結多個群組、頻道或機器人。成員可以直接探索並加入可見聊天室；聊天室也可設為隱藏，只讓該聊天室成員與 Community 管理員看到。預設成員可以加入其他聊天室，管理員則可限制權限，讓新增項目先變成建議。
Bot API 10.2 明確稱這是「初步支援」。目前可用的介面如下：
| Bot API 介面 | 可以確認 | 不能據此推論 |
|---|---|---|
Message.community_chat_added | 目前聊天室已加入，並取得新的 Community 物件 | Community 所有聊天室的完整歷史 |
Message.community_chat_removed | 目前聊天室已移除 | 離開哪個 Community；物件目前沒有欄位 |
ChatFullInfo.community | getChat 回傳的目前 Community（若有） | 共用收件匣或統一權限 |
這與Telegram 群組內的臨時機器人訊息不同，後者處理可見對象；也與 Bot API 10.1 Rich Messages不同，後者處理訊息格式。Communities 描述的是聊天室之間的關係。
如何處理 community_chat_added 與 community_chat_removed
1. 確認 SDK 不會丟掉新欄位
先更新 Bot API 型別或函式庫。如果框架反序列化時會移除未知的 Message 欄位，Telegram 即使已投遞事件，應用程式仍可能完全看不到 Community 訊號。
如果有設定 allowed_updates，至少保留 message；Community 內含頻道時，也要在測試環境驗證 channel_post。官方把 Community 欄位放在共用 Message 類型，並未新增頂層 Update。
2. 加入事件一到就保存
以下 Node.js 範例只使用官方已記載的欄位，並原樣保存完整 Community 物件：
async function handleTelegramUpdate(update, store) {
const message = update.message ?? update.channel_post;
if (!message) return;
if (message.community_chat_added) {
await store.upsertCommunityMembership({
chatId: String(message.chat.id),
community: message.community_chat_added.community,
updateId: update.update_id,
observedAt: new Date(message.date * 1000).toISOString(),
});
}
if (Object.hasOwn(message, "community_chat_removed")) {
await store.removeCommunityMembership({
chatId: String(message.chat.id),
updateId: update.update_id,
});
}
}將 update_id 當作冪等鍵。Telegram 說明尚未消費的更新最多保留 24 小時，所以 webhook 佇列不能取代自己的歷史資料庫。
3. 移除時用 chat ID 找回舊關係
CommunityChatRemoved 目前沒有任何欄位。移除處理器必須用 message.chat.id 找到先前保存的關係，而不是嘗試從空物件讀取 Community ID。重複加入應更新同一筆資料；重複移除則應安全地不做任何事。
4. 用 getChat 對帳
getChat 回傳的 ChatFullInfo 現在有可選的 community 欄位。webhook 重連、SDK 升級或發現 update_id 缺口時，可用它核對快取，不必持續輪詢所有聊天室。
測試至少要包含：加入超級群組、移除、重送同一 update_id、getChat 對帳，以及實際管理員角色下的可見和隱藏聊天室。
社群拓撲與訊息路由要分開
Community 改善 Telegram 內的探索與組織，但不會合併訊息歷史、權限、chat ID 或機器人存取權。
| 需求 | 正確資料來源 |
|---|---|
| 聊天室加入或離開 Telegram Community | 官方 Bot API 10.2 服務訊息與 getChat |
| 機器人接收一般 Telegram 訊息 | 官方 Bot API 更新與聊天室權限 |
| 團隊接收多平台一般帳號的客戶訊息 | UnifyPort message.received 等標準入站層 |
如果團隊同時服務 WhatsApp、LINE、Zalo、TikTok 或 X，Telegram Community 並不會把這些平台一起標準化。Telegram 原生自動化與跨渠道佇列指南說明了兩層架構的差異。
UnifyPort 的正確位置
UnifyPort 不會建立 Telegram Communities，也不提供 CommunityChatAdded、Community 可見性或官方 Bot API 生命週期。需要這些功能時應使用 Telegram 官方 API。
UnifyPort 適合另一條路徑：讓 Telegram 與其他支援平台的一般帳號入站訊息進入同一標準事件串流。支援的訊息會以 message.received 到達，信封包含 id、type、provider、account_id、occurred_at 與 data。webhook endpoint 設有 signing_secret 時，會用 X-Device-Timestamp 與 X-Device-Signature 驗證 HMAC-SHA256。
請把 Community membership 存在 Telegram 拓撲表，把客戶對話按 provider、account、conversation 存入佇列。不要把 community_chat_added 轉成 message.received。
限制與取捨
Bot API 10.2 提供的是初步生命週期資訊，不是完整 Community 管理 API。移除物件為空，官方也未承諾歷史關係查詢，因此應用程式需要自己的快取與測試。
官方 Bot API 適合機器人、Community 關係、Telegram 角色與隱藏聊天室。非官方介面無法授予這些官方權限；反過來，Community 也不能替代 Telegram 以外的統一入站佇列。
常見問題
Bot API 10.2 的 Telegram Community 是什麼？
它把多個 Telegram 超級群組、頻道或機器人連結到同一主題，並透過 Community、加入/移除服務訊息與 ChatFullInfo.community 提供初步生命週期資料。
community_chat_added 在 webhook 哪裡？
它位於 Update 中的 Bot API Message，不是新的頂層 Update 欄位，內容包含目前聊天室加入的 Community。
community_chat_removed 包含什麼？
目前沒有欄位。請用目前的 message.chat.id 刪除先前保存的關係。
Communities 會合併所有訊息嗎？
不會。每個聊天室仍保有自己的訊息、權限、識別碼與機器人存取要求。
UnifyPort 會收到 Community 生命週期事件嗎？
目前 UnifyPort API Reference 沒有把這兩個 Telegram 欄位列為標準事件。Community 生命週期請走官方 Bot API。
下一步
若真正目標是跨渠道客服佇列，先查看平台訊息支援矩陣，再依 message.received API Reference實作，避免與 Telegram Community 狀態混在一起。
來源
官方來源核對日期：2026 年 7 月 26 日。