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 標準事件文件。