Telegram Bot API 10.2 Communities：處理聊天室加入及移除事件
Telegram Bot API 10.2 的 Communities 可以把多個超級群組、頻道及機械人連結到同一主題。當目前聊天室加入 Community，機械人會在一般 Message 內收到 community_chat_added；移除時則收到 community_chat_removed。應把兩者當作拓撲生命週期訊號：先儲存聊天室與 Community 的關係，訊息仍按各自 chat 路由，因為 Community 不會把所有聊天合併成同一訊息流。
重點
- 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 提供甚麼 Community 資料
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 日。