Telegram Bot 無回應？從 Token 到 Webhook 的完整故障排查指南

你的 Telegram Bot 突然不回覆訊息了？訊息發出後沒有反應，用戶開始抱怨，而你卻不知道問題出在哪裡。這種情況在經營 Telegram Bot 的團隊中並不少見。無論是用於客服、自動化通知或社群管理，Bot 無回應都會直接影響業務運作。

本文將從最基礎的 Token 檢查 開始，逐步深入到 Webhook 配置、Telegram 限流、伺服器網路以及程式碼邏輯，提供一個完整的故障排查指南。你可以按照順序檢查，也可以直接跳到懷疑的環節。最後附有一張速查清單，方便列印或截圖保存。

為什麼我的 Telegram Bot 不回覆訊息？

Bot 無響應的現像多種多樣：

• 訊息已讀未回：使用者看到訊息已送達，但 Bot 永遠不回覆。
• 超時無反應：發送訊息後等待數秒甚至數十秒，Bot 才會回應或一直無回應。
• 僅部分使用者無回應：某些使用者或群組可以正常交互，有些則不行。

這些症狀背後，原因通常集中在五個方面：Token 問題、Webhook 配置錯誤、Telegram 限流、伺服器網路故障 或 程式碼邏輯缺陷。下面我們逐一檢查。

第一步：檢查 Bot Token 是否有效

Token 是 Bot 的身份憑證，Telegram Bot API 透過 Token 識別你的 Bot。如果 Token 無效，Bot 根本無法與 Telegram 伺服器通訊。

如何驗證 Token 有效性

最簡單的方法是透過 getMe API 測試。在終端機或 Postman 中執行以下 curl 指令（將 YOUR_BOT_TOKEN 替換為實際 Token）：

curl https://api.telegram.org/botYOUR_BOT_TOKEN/getMe

如果傳回類似以下 JSON，表示 Token 有效：

{"ok": true, "result": {"id": 123456789, "is_bot": true, "first_name": "MyBot", "username": "my_bot"}}

如果傳回 {"ok": false, "error_code": 401, "description": "Unauthorized"}，則 Token 無效或過期。

Token 被重置的常見場景與處理

Token 被重置的常見原因包括：

• Token 洩漏：如果你將 Token 提交到了公開程式碼倉庫（如 GitHub），Telegram 會自動偵測並重設 Token。
• 手動重設：透過 BotFather 使用 /setprivacy 或 /token 指令重設 Token。
• Bot 刪除後重新建立：此時 Token 完全改變。

處理方式很簡單：一旦 Token 被重置，必須同步更新所有部署環境——包括本地開發環境、生產伺服器、以及你使用的任何 SaaS 管理控制台（如 TG-Staff）。如果只更新了一處，其他環境仍會使用舊 Token，導致部分服務無回應。

第二步：檢查 Webhook 設定（適用輪詢模式可跳過）

如果你的 Bot 使用 Webhook 模式（Telegram 伺服器主動推播訊息到你的伺服器），Webhook 設定錯誤是導致無回應的常見原因。如果你使用 輪詢模式（Bot 主動拉取訊息），可以跳過本節。

Webhook URL 必須為 HTTPS 且公網可達

Telegram 對 Webhook 有嚴格限制：

• 必須使用 HTTPS：自簽名憑證不被接受，必須使用受信任的 CA 所簽發的憑證。
• URL 必須公網可達：不能使用 localhost 或內網 IP。
• 連接埠限制：僅支援 443、80、88、8443 四個連接埠。

如果你的伺服器在 NAT 或防火牆後面，Webhook 請求可能無法到達。

如何用 getWebhookInfo 診斷問題

使用以下 API 取得目前 Webhook 配置：

curl https://api.telegram.org/botYOUR_BOT_TOKEN/getWebhookInfo

返回結果中，重點關注以下欄位：

• has_custom_certificate：是否使用了自訂憑證（通常應為 false，除非你有特殊需求）。
• last_error_date：最近一次錯誤的 Unix 時間戳。如果非空，表示有錯誤發生。
• last_error_message：錯誤描述，例如 “SSL error”、“Connection timeout” 等。
• max_connections：最大連線數（預設 40），若設定過低可能會影響並發。
• allowed_updates：允許的更新類型，如果設定錯誤可能收不到某些訊息。

例如，last_error_message 為 “SSL error” 表示憑證問題；“Connection timeout” 表示你的伺服器無法接收請求。

清除錯誤 Webhook 的步驟

如果發現 Webhook 設定錯誤，建議先清除再重新設定：

1. 清除 Webhook：

   curl -X POST https://api.telegram.org/botYOUR_BOT_TOKEN/deleteWebhook

2. 重新設定 Webhook：

   curl -X POST https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook?url=https://yourdomain.com/webhook

清除後，Telegram 會停止推播訊息，直到你重新設定。這可以避免舊的錯誤配置持續影響。

第三步：排除 Telegram 限流與平台側限制

即使 Token 和 Webhook 都正確，Telegram 的速率限制也可能導致 Bot 無回應。

限流（Rate Limiting）的症狀與應對

Telegram Bot API 的限流規則：

• 每個群組聊天：最多 30 則訊息/秒。
• 每個使用者：最多 1 則訊息/秒。
• 全域：如果請求量過大，API 會回傳 429 Too Many Requests，並附帶 retry_after 欄位（秒數）。

症狀：部分訊息成功傳送，部分失敗；日誌中出現 429 錯誤。

應對方法：

• 實現 指數退避重試：收到 429 後，等待 retry_after 指定的秒數再重試。
• 控制群發頻率：不要在同一秒內向大量使用者發送訊息。如果需要大量群發，建議使用內建限流的 SaaS 工具。

Bot 被使用者/群組封鎖或主動退出

• 使用者封鎖 Bot：使用者可以在 Telegram 中手動封鎖 Bot，之後 Bot 發送的訊息會被靜默丟棄（不會報錯）。
• 群組移除 Bot：Bot 被踢出群組後，所有訊息都會失敗。
• Bot 主動退出：如果程式碼中呼叫了 leaveChat，Bot 會退出群組。

檢查方法：嘗試在目標群組中傳送訊息，如果傳回 {"ok": false, "error_code": 403}，表示 Bot 已被移除或使用者封鎖。

第四步：檢查伺服器與網路連結性

即使 Token 和 Webhook 設定正確，伺服器無法連接 Telegram 伺服器也會導致無回應。

測試伺服器到 Telegram API 的連通性

在伺服器上執行：

ping api.telegram.org

或使用 curl 測試：

curl -I https://api.telegram.org

如果回傳 Connection timed out 或 Network is unreachable，表示伺服器無法存取 Telegram。可能原因：

• 防火牆規則：出站連接埠 443 被封鎖。
• DNS 解析失敗：api.telegram.org 無法解析（嘗試使用 IP 位址直接存取）。
• 出網 IP 被限制：某些雲端服務商的 IP 段可能被 Telegram 限制（少見，但曾經發生過）。

SSL 憑證過期或無效

Webhook 強依賴有效 SSL 憑證。憑證過期後，Telegram 會停止推播訊息，並在 getWebhookInfo 的 last_error_message 中提示 “SSL error”。

檢查證書有效期限：

openssl s_client -connect yourdomain.com:443 -servername yourdomain.com

查看輸出中的 notAfter 欄位。如果憑證即將過期，使用 Let’s Encrypt 等工具自動續約。

第五步：檢查 Bot 程式碼邏輯與運行時狀態

排除外部因素後，檢查程式碼本身是否有問題。

日誌與異常捕獲

檢查應用程式日誌中是否有以下內容：

• unhandled exception：未捕獲的異常導致 Bot 進程崩潰。
• TimeoutError：請求 Telegram API 逾時。
• NullPointerException 或類似錯誤：程式碼中處理訊息時發生錯誤。

建議使用結構化日誌（如 JSON 格式），方便搜尋分析。例如，在 Python 中使用 logging 模組輸出時間戳記、日誌等級、訊息內容和異常堆疊。

依賴函式庫版本與 API 變更

Telegram Bot API 偶爾會廢棄舊欄位或方法。如果你使用的 SDK 版本過舊，可能無法相容於最新 API。

檢查方法：

• 查看使用的 SDK（如 python-telegram-bot、node-telegram-bot-api）是否仍在維護。
• 比較 SDK 版本與 Telegram Bot API 最新版本（可存取 Telegram Bot API 文件 查看變更日誌）。
• 如果 SDK 已停止維護，建議遷移到活躍的替代庫。

故障排查速查清單（Checklist）

將以下清單列印或截圖保存，下次 Bot 無回應時快速對照檢查：

序號	檢查項目	驗證方法	常見原因
1	Token 有效性	呼叫 getMe API	Token 洩漏、重設、複製貼上錯誤
2	Webhook URL 正確性	呼叫 getWebhookInfo	URL 不是 HTTPS、連接埠錯誤、憑證無效
3	伺服器連結性	ping api.telegram.org	防火牆、DNS 問題、出網 IP 被封
4	限流狀態	檢查日誌中的 429 錯誤	群發頻率過高、未實現重試邏輯
5	使用者/群組權限	嘗試傳送訊息	使用者屏蔽 Bot、Bot 被踢出群組
6	程式碼日誌	檢查應用程式日誌	未擷取異常、逾時、記憶體洩漏
7	SSL 憑證	openssl s_client	憑證過期、自簽章憑證
8	API 版本	比較 SDK 與 API 文件	依賴函式庫過時、API 廢棄欄位

---

總結

Telegram Bot 無回應通常不是單一原因導致，而是多個因素疊加的結果。透過系統化排查－從 Token 檢查 開始，到 Webhook 設定、限流狀態、伺服器網路、再到 程式碼邏輯－你可以快速定位問題並恢復服務。

如果你希望簡化 Bot 管理流程，減少檢驗工作量，可以試試 TG-Staff。它提供即時雙向聊天、視覺化命令流程、自動翻譯等功能，並在控制台中內建了 Bot 連線狀態監控和錯誤提示。註冊即享 3 天免費試用，無需信用卡。

如需更詳細的文檔，請造訪 官方文檔。遇到問題也可以直接聯絡客服 Bot：@tgstaff_robot，取得一對一排查幫助。