Telegram getUpdates 與 setWebhook 衝突：安全切換 Runbook

Telegram Bot API 的接收規則很清楚：同一個 bot 不能同時使用 getUpdates 輪詢與 setWebhook 推送。若部署後收不到訊息，先確認目前是哪個接收端有效，再決定刪除 webhook 後恢復輪詢，或停止輪詢 worker 後設定 webhook。Telegram 官方也說 pending updates 只會暫時保存，因此切換客服入口時要有步驟。

重點摘要

• getUpdates 和 setWebhook 是兩種官方 Bot API 接收模式，不是可以並行的兩層架構。
• 先呼叫 getWebhookInfo，確認是否仍有 webhook URL。
• 切回輪詢前先呼叫 deleteWebhook，並決定 drop_pending_updates 是否能安全丟棄。
• 若你還在選接收路徑，先讀 Telegram Bot API webhook vs unified inbound webhook。
• 若問題其實是憑證，請先看 Telegram API ID/API hash 與 bot token 的差異。

官方文件的邊界

Telegram 官方 Bot API 文件把 updates 接收分成兩種：getUpdates 是你的程式長輪詢 Telegram；webhook 則是 Telegram 對你的 HTTPS URL 發送請求。同一頁也說明，只要 outgoing webhook 已設定，就不能用 getUpdates 接收 updates；要切回輪詢時，使用 deleteWebhook。

狀況	可能狀態	先做什麼
輪詢沒有拿到訊息	webhook URL 還在	呼叫 getWebhookInfo
webhook 沒有收到請求	舊輪詢 worker 還在，或 webhook 未正確設定	停 worker，再檢查
內部流程重複或漏掉	多個服務實例同時處理	先指定唯一 owner
切換後出現大量測試訊息	舊 pending updates 被保留	選擇處理或丟棄

步驟 1：檢查目前接收端

在受控環境中執行，BOT_TOKEN 放在環境變數，不要寫進記錄：

curl "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

如果回應中的 url 非空，代表 webhook 仍然存在。若 url 是空的，Bot API webhook 沒有啟用，getUpdates 可以作為接收方式。

步驟 2：從 webhook 切回 getUpdates

先移除 webhook：

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/deleteWebhook" \
  -d "drop_pending_updates=false"

客服訊息通常不該丟棄，請保留 false 並讓單一輪詢 worker 幂等處理。只有 backlog 是測試流量或已明確決定重新開始時，才設定為 true。

接著啟動一個輪詢 worker，並在每次 getUpdates 回應後推進 offset：

curl "https://api.telegram.org/bot$BOT_TOKEN/getUpdates?timeout=30"

步驟 3：從 getUpdates 切到 setWebhook

先停止輪詢 worker，再設定正式 webhook：

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  -d "url=https://support.example.com/telegram/bot-webhook"

接收端應先快速回應、存下 update，再讓 CRM、AI 分流或客服指派非同步執行。這與 webhook-first inbound integration checklist 的「先儲存再路由」原則一致，只是 Telegram Bot API update 和 UnifyPort event schema 不同。

何時改用統一入站 webhook

這份 runbook 解決的是 Telegram bot 的接收模式切換。它不會把 bot 變成一般帳號收件匣，也不會自動統一 WhatsApp、LINE、TikTok、Zalo 或 X。

若你的團隊需要跨平台客服隊列，請建立 UnifyPort webhook。深度文件是 Create webhook endpoint：設定 HTTPS url、status: "active"，訂閱 message.received 或 ["*"]，需要驗證時設定 signing_secret。

{
  "id": "evt_b1a7c3e5f8",
  "type": "message.received",
  "provider": "telegram",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:37:00Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": { "id": "3003", "direction": "inbound", "sent_at": "2026-06-08T12:37:00Z", "text": "Can you check my order?" },
    "event": { "kind": "message_received" }
  }
}

若產品需要 bot 身分、bot command 或 Telegram 的 Update 物件，官方 Bot API 是正確選擇。若重點是現有 Telegram 帳號或多平台入站訊息，UnifyPort 的非官方接口較適合。

FAQ

getUpdates 和 setWebhook 可以同時用嗎？

不可以。Telegram 官方將它們視為互斥的 bot update 接收方式。輪詢前先刪 webhook；設定 webhook 前先停輪詢。

drop_pending_updates 何時設為 true？

只有待處理 updates 可以丟棄時才設為 true。正式客服訊息應保留並幂等處理。

這等於連接 Telegram 一般帳號嗎？

不是。Bot API 使用 bot token。UnifyPort 連接 Telegram 帳號後，會送出標準化的 message.received event。

Sources checked on 2026-09-09

• Telegram Bot API getUpdates: https://core.telegram.org/bots/api#getupdates
• Telegram Bot API setWebhook: https://core.telegram.org/bots/api#setwebhook
• Telegram Bot API deleteWebhook: https://core.telegram.org/bots/api#deletewebhook
• Telegram webhook guide: https://core.telegram.org/bots/webhooks
• UnifyPort Create webhook endpoint