搭建 Telegram 客服系統常見故障排障指南：Token、Webhook、坐席登入與分流失效

建立一套穩定的 Telegram 客服系統 是許多跨國團隊、Web3 專案方和社群經營者的剛需。但在實際部署過程中，從 Bot Token 失效到 Webhook 衝突，從坐席無法登入到會話分流不工作，各類故障層出不窮。本文以 TG-Staff 為主要場景，總結搭建 Telegram 客服系統時最常遇到的六類故障，並提供可落地的排障方法。無論你是剛註冊試用，還是已經上線運營，這份排障指南都能幫你快速定位問題、恢復客服運轉。

故障一：Bot Token 無效或失效

Bot Token 是 Telegram Bot 的唯一身分憑證，相當於你的客服系統與 Telegram 伺服器之間的「密碼」。一旦 Token 失效，整個客服系統將無法接收或發送任何訊息。

如何判斷 Token 是否有效？

最直接的方法是透過 Telegram Bot API 進行測試。在終端機或瀏覽器中執行以下請求：

https://api.telegram.org/bot<你的Token>/getMe

如果回傳 {"ok":true,"result":{"id":...}}，表示 Token 有效。如果回傳 {"ok":false,"error_code":401,"description":"Unauthorized"}，則 Token 已失效。

Token 失效的常見原因包括：

• 在 BotFather 中手動重置了 Token
• Bot 刪除後重新創建
• 權限變更導致 Token 被 Telegram 吊銷

Token 更新後，Webhook 需要重新設定嗎？

**需要。 ** Token 更換後，舊 Token 對應的 Webhook 設定也隨之失效。你必須重新綁定 Webhook，否則 Bot 無法接收使用者訊息。

在 TG-Staff 控制台中的操作步驟：

1. 登入 app.tg-staff.com，進入對應項目
2. 點選“項目設定”→“Bot 設定”
3. 在 Token 輸入框中貼上從 BotFather 取得的新 Token
4. 點選「儲存」後，系統會自動重新設定 Webhook

故障二：Webhook 衝突與連線失敗

Webhook 是 Telegram Bot 與客服系統之間的橋樑。當 Bot 收到使用者訊息時，Telegram 伺服器會透過 Webhook 將訊息推送到你指定的 URL。如果多個服務同時佔用同一個 Webhook，就會發生衝突。

什麼是 Webhook 衝突？如何檢測？

Webhook 衝突是指 Bot 目前的 Webhook 位址指向了非 TG-Staff 的 URL（例如其他客服平台、自訂腳本或測試伺服器）。檢測方法：

1. 在瀏覽器中存取：https://api.telegram.org/bot<你的Token>/getWebhookInfo
2. 檢視傳回的 url 欄位－如果它指向的不是 https://app.tg-staff.com/... 格式的位址，表示有衝突

解決 Webhook 衝突的兩種方法

方法一：在 TG-Staff 控制台一鍵修復

在專案設定頁面，如果偵測到 Webhook 衝突，控制台會顯示警告提示。點選「重新設定 Webhook」按鈕，系統會自動清除舊設定並綁定正確的位址。

方法二：手動清除後重新綁定

如果自動修復失敗，可以手動呼叫 Telegram API 清除衝突：

https://api.telegram.org/bot<你的Token>/deleteWebhook

執行成功後返回 {"ok":true}。然後在 TG-Staff 控制台重新觸發 Webhook 綁定即可。

故障三：坐席無法登入或看不到會話

坐席是客服系統的核心執行者。當坐席回饋無法登入或登入後看不到任何會話時，通常涉及三個層面：帳號狀態、坐席額度、項目權限。

坐席登入提示「帳號未啟動」怎麼辦？

首先檢查坐席是否已被管理員從「坐席管理」移除。其次，確認目前方案的坐席額度是否已用盡。 TG-Staff 各套裝的坐席配額如下（以官網為準）：

套餐類型	坐席額度	適用場景
免費試用	有限制	測試評估
標準版	3 個坐席	小型團隊
專業版	20 個坐席	中大型團隊

如果坐席額度已滿，需要升級套餐或釋放不活躍的坐席名額。

坐席登入後看不到任何會話

這是最常見的配置類別故障。排障步驟：

1. 檢查專案客服範圍：管理員進入「專案設定」→「客服範圍」，確認坐席已勾選
2. 檢視分流規則配置：如果分流規則設為「指定客服」，而該坐席未被列入，則不會收到任何會話
3. 確認坐席在線狀態：如果分流規則為“在線優先”，坐席需保持在線狀態才能接收新會話

故障四：會話分流（輪流分配/線上優先）不工作

會話分流是客服系統自動將使用者指派給合適坐席的機制。 TG-Staff 支援兩種分流模式：輪流分配（默認，按順序輪詢有權限坐席）和 在線優先（優先分配給在線坐席，全離線時回退輪流分配）。如果配置後分流不生效，通常有以下原因。

輪流分配 vs 線上優先：選哪一個？

特性	輪流分配	線上優先
分配邏輯	依固定順序輪詢	優先找線上坐席
適用場景	團隊坐席皆在線上	坐席線上時間不固定
離線處理	跳過離線坐席	全離線時回退輪流分配

分流失效的檢驗步驟

1. 確認坐席在線狀態：在線優先模式下，如果所有坐席都離線，新會話將不會分配
2. 檢查專案客服範圍：確保參與分流的坐席都在「客服範圍」內
3. 驗證分流連結使用正確：分流連結必須由 TG-Staff 產生（標準版及以上套裝支援），而非 Bot 原生連結。原生連結不會觸發分流邏輯

故障五：分流連結（魔法連結）跳轉異常或歸因失敗

分流連結（也稱為魔法連結）是 TG-Staff 提供的官方網域短鏈，用於廣告引流歸因與多管道追蹤。當使用者點擊連結後，系統會擷取訪客 IP、瀏覽器資訊與 URL 參數，然後跳到 Bot 開始對話。

跳轉異常的常見原因

• 連結過期：每個分流連結有有效期，過期後無法跳轉
• 套餐限制：分流連結是標準版以上套餐的功能，免費試用用戶無法使用
• URL 參數被截斷：如果廣告連結中 utm_* 參數拼接錯誤，可能導致歸因資料缺失

歸因失敗的排障方法

1. 檢查分流連結格式：應為 https://app.tg-staff.com/{code} 格式
2. 驗證廣告連結參數：確保 utm_source、utm_medium、utm_campaign 等參數正確拼接在分流連結之後
3. 測試跳轉流程：在瀏覽器中手動開啟分流鏈接，確認能正常跳轉至 Bot

故障六：訊息發送失敗或自動翻譯不生效

坐席傳送訊息失敗或自動翻譯不工作，通常與內容風控攔截、翻譯配額用盡或功能開關未啟用有關。

內容風控攔截

專業版的內容風控功能會在坐席傳送訊息前偵測風險字。如果訊息命中風險詞組，會跳出二次確認視窗或直接阻止發送。排障方法：

• 檢查「內部管理」→「風險詞組」配置，確認是否誤攔截了合法內容
• 對於 Web3 項目，請注意錢包位址監控：如果風險詞組中配置了特定 TRC20/ERC20 位址，坐席發送包含該位址的訊息時會被攔截

自動翻譯不生效

自動翻譯需要滿足三個條件：

1. 套餐包含翻譯配額（標準版含 AI 翻譯，專業版額外支援 Google 專業翻譯及 DeepL 專業翻譯）
2. 目前會話中已開啟翻譯開關（坐席介面右上角）
3. 當日翻譯配額未用盡（可在控制台查看剩餘配額）

常見問題

**問：重設 Bot Token 後，TG-Staff 會自動更新嗎？ ** 答： 不會。你需要在 BotFather 取得新 Token，然後手動在 TG-Staff 控制台「專案設定」中更新。更新後系統會自動重新設定 Webhook。

**問：Webhook 衝突時，TG-Staff 會提示我嗎？ ** 答： 會。當你嘗試綁定 Bot 時，如果偵測到 Webhook 指向其他服務，控制台會顯示警告。你可以一鍵清除衝突並重新綁定。

**問：坐席登入後看不到任何會話，是什麼原因？ ** 答： 最常見原因是該坐席未加入專案的「客服範圍」。請管理員在「專案設定 → 客服範圍」中勾選該坐席，並確保分流規則已啟用。

**問：分流連結（魔法連結）對免費試用用戶可用嗎？ ** 答： 不可用。分流連結是標準版及以上套餐的功能。免費試用用戶只能使用 Bot 原生鏈接，無法實現歸因追蹤。

**問：內容風控攔截了坐席發送的合法訊息，怎麼辦？ ** 答： 管理員可以在「內部管理 → 風險詞組」中調整或移除觸發規則。如果是誤攔截，可臨時放行後修改詞組配置。

結語與行動建議

在搭建 Telegram 客服系統時，Token、Webhook、坐席和分流是四個最容易故障的環節。大部分問題都可以透過本文提供的排障方法快速解決。如果你剛接觸 TG-Staff，建議先報名免費試用（3 天），在測試環境中走通全流程，再正式上線。

行動建議：

1. 註冊試用：app.tg-staff.com 立即體驗 3 天免費試用
2. 查閱完整文件：docs.tg-staff.com 以取得更詳細的操作指南
3. 聯絡客服：遇到無法解決的問題，可直接聯絡 @tgstaff_robot 取得技術支持

搭建一套可靠的 Telegram 客服系統 並非難事，關鍵在於提前了解常見故障並掌握排障方法。希望這份指南能幫你少走彎路，讓客服系統真正成為業務成長的助力。