Telegram 群組升級為超級群組：安全更新 Chat ID

Telegram 群組遷移為超級群組後，機器人後續傳送應使用新的聊天識別碼。Bot API 的服務訊息可包含 migrate_to_chat_id 或 migrate_from_chat_id，失敗的 API 回應也可能包含 parameters.migrate_to_chat_id。請明確記錄新舊 ID 的對應：更新未來的傳送目標，但保留歷史訊息原本所屬的聊天識別碼。

重點

• 群組遷移改變的是目標身分，不代表 webhook 傳遞失敗。
• 讀取結構化遷移欄位，不要比對錯誤文字或猜測新 ID。
• 歷史紀錄保留原始聊天身分；新傳送在執行前解析目前目標。
• UnifyPort 公開的標準事件結構未承諾相同的遷移對應，不能直接套用 Bot API 欄位。

migrate_to_chat_id 與 migrate_from_chat_id 的意義

Telegram 官方 Bot API 文件 在 Message 中定義了兩個選用欄位，並在 ResponseParameters 中定義了遷移目標欄位：

證據	舊聊天	新聊天
訊息包含 migrate_to_chat_id	該訊息的 chat.id	message.migrate_to_chat_id
訊息包含 migrate_from_chat_id	message.migrate_from_chat_id	該訊息的 chat.id
失敗回應包含 parameters.migrate_to_chat_id	原請求使用的數字聊天 ID	parameters.migrate_to_chat_id

處理錯誤回應時，必須保留原請求的上下文。如果請求使用的是使用者名稱，而非已儲存的數字 ID，不能僅憑錯誤回應推定舊聊天的數字識別碼。

Telegram 提醒，遷移 ID 可能超過 32 個有效位元，但最多為 52 個有效位元；有號 64 位元整數或雙精度浮點數可以安全儲存。請檢查整條資料流程，避免任何 32 位元轉換。應用程式內部的索引鍵也可採用十進位字串，但必須完整保留正負號與數值。

本文假設接收端已收到更新。若尚未決定身分與傳輸方式，請先閱讀 Telegram Bot API webhook 與統一入站 webhook 的比較。

將遷移視為別名，而非改寫歷史

建議在應用程式中分開儲存「業務對話」與「平台傳送目標」。在租戶及機器人整合的範圍內維護新舊 ID 對應，並保留建立關係的證據。這是本地儲存設計，不是新增的 Telegram API 欄位。

不要大量替換歷史訊息紀錄中的聊天 ID。Telegram 的 message_id 是在所屬聊天內唯一，而非全域唯一。將舊訊息重新標示為新聊天的訊息，可能造成錯誤關聯。傳送目標之間的別名，不代表訊息 ID 之間存在官方保證的轉換。

建議依序處理：

1. 驗證來源並持久儲存收到的更新；若證據來自 API 錯誤，則保存實際回應及原請求。
2. 根據上表擷取新舊聊天識別碼。
3. 儲存系統允許時，在同一交易中寫入對應並更新目前路由。
4. 相同對應重複出現時不再觸發動作；衝突或循環對應則暫停並交由人工檢查，不要無聲覆寫。
5. 保持歷史紀錄不變；佇列工作真正傳送前，再解析目前目標。

對應更新與目標解析應透過應用程式鎖定或等效並行控制協調。否則，某個工作程序可能剛讀到舊 ID，另一個就提交了遷移。即使有本地協調，也要保留這類競爭情況的錯誤處理。

恢復佇列工作，而非盲目重試

失敗回應中的 parameters.migrate_to_chat_id 提供了新目標。先持久儲存，再判斷是否重試，並確認工作是否仍適合執行。網路逾時是另一種情況：既不能證明發生遷移，也不能證明訊息未送出。

若工作引用較早的訊息，不要直接把舊 message_id 搭配新聊天 ID。應確認引用有效，或交由人工處理；不要默默把依賴上下文的動作改成另一則普通訊息。

需要記錄傳送結果時，可參考 webhook 回應內回覆與獨立 sendMessage 請求。確認入站傳遞成功，不等於出站工作已完成。

以下是建議的驗收測試，不是實測結果：

• 重複遷移證據只保留一筆對應，不建立第二個傳送工作。
• 延遲抵達的舊聊天更新仍保留原始歸屬，不將目前目標改回舊 ID。
• 衝突對應會暫停相關工作。
• 名稱相同但無關的群組不會被合併。
• 識別碼經過序列化與資料庫讀寫後未遭截斷。

UnifyPort 的能力邊界

UnifyPort 的非官方介面透過 message.received 提供 provider、account_id 與 data.conversation.id。這些識別碼應保存在獨立命名空間，不要假設能直接換成 Bot API chat ID。

公開事件文件未定義 migrate_to_chat_id、migrate_from_chat_id，也未保證提供新舊遷移關係。group.updated 或 conversation.updated 都不能被當作這類保證。針對已連結的 Telegram 訊息帳號，請依對話列表介面回傳的 conversation_id 核對。名稱相同不是對話延續的證據；無法確認的對應需要人工審查。

接收事件時設定 signing_secret，並遵循 webhook 傳遞驗證文件。UnifyPort 不提供 REST 訊息歷史讀取 API，也不保證重播遺漏事件。查詢目前對話列表不能重建遺失訊息，也不能提供文件未定義的遷移關係。

常見問題

群組升級後要修改 webhook URL 嗎？

新 chat ID 是路由問題，本身不代表 webhook 網址需要更換。先檢查收到的更新與儲存的傳送目標。

能從舊 ID 推算新 ID 嗎？

請使用 Telegram 提供的遷移欄位，不要增加前綴或修改數字來組成目標。

是否應將所有歷史訊息移到新 chat ID？

不應改寫原始聊天與訊息的組合。可以在業務層連結兩個對話，但不能宣稱訊息識別碼也完成轉換。

UnifyPort 會自動提供這些 Bot API 遷移欄位嗎？

公開契約沒有承諾這種行為。請按照其自身 API 核對已連結帳號的對話識別碼，並審查不確定的對應。

下一步與來源

檢查傳送端在何處解析目標，尤其是佇列工作。需要核對已連結帳號的對話時，從對話列表文件開始。

• Telegram Bot API：Message 與 ResponseParameters，核對日期：2026-09-21。
• UnifyPort 標準事件文件。