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

Telegram Bot API 有一條基本規則：同一個 bot 唔應該同時用 getUpdates 輪詢同 setWebhook 推送。部署後如果收唔到訊息，先確認現時邊個接收端有效，再決定刪 webhook 後回到輪詢，或者停輪詢 worker 後設定 webhook。Telegram 官方亦指出 pending updates 只會暫時保存，所以切換客服入口時要有清晰步驟。

重點

• getUpdates 同 setWebhook 係兩種官方 Bot API 接收模式，唔係可以並行嘅兩層。
• 先 call getWebhookInfo，確認 webhook URL 是否仍然存在。
• 切回輪詢前，先 call 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 發 request。官方同時說明，只要 outgoing webhook 仍然設定，就不能用 getUpdates 接收 updates；要切返輪詢，使用 deleteWebhook。

情況	可能狀態	先做
輪詢無訊息	webhook URL 仲喺度	getWebhookInfo
webhook endpoint 無 request	舊輪詢 worker 未停，或 webhook 設定唔正確	停 worker，再查
內部隊列重複或漏處理	多個實例同時處理	先定唯一 owner
切換後湧入測試訊息	舊 pending updates 被保留	選擇處理或丟棄

步驟 1：檢查現時接收端

喺受控環境執行，BOT_TOKEN 放環境變數，唔好寫入 log：

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 變成普通帳號 inbox，亦唔會自動統一 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 官方將兩者定義為互斥接收方式。輪詢前刪 webhook；設定 webhook 前停輪詢。

drop_pending_updates 幾時設為 true？

只喺待處理 updates 可以丟棄時使用。正式客服訊息應保留，並用幂等儲存處理。

呢個等於連接 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