TG-Staff Webhook 事件整合指南：自動化對話、訊息與營運流程

當你營運一個 Telegram Bot 客服團隊時，最頭痛的問題之一就是資料割裂：客服對話在 TG-Staff 裡，客戶資訊在 CRM 裡，工單在另一個系統裡。每次都要人工複製貼上，或者寫腳本輪詢 TG-Staff 的 API 去拉資料——既低效又容易出錯。

TG-Staff 的 Webhook 事件 正是為了解決這個問題。它不是一個需要手動觸發的「匯出按鈕」，而是一個即時的資料橋樑：當平台內發生關鍵事件（比如用戶發來新訊息、客服分配了對話、對話關閉），TG-Staff 會主動把事件資料推送到你指定的 URL。你的伺服器收到 POST 請求後，可以自動建立工單、更新用戶標籤、觸發滿意度調查……真正實現「事件驅動」的自動化營運。

本文詳細講解 TG-Staff Webhook 事件的配置方式、可訂閱事件類型，以及 3 個可以直接落地的整合場景。如果你正在尋找將 Telegram 客服資料與自有系統打通的方法，這篇指南值得收藏。

---

什麼是 TG-Staff Webhook 事件？——從被動接待到主動整合

簡單說，Webhook 是「反向 API」：通常你需要主動呼叫 API 去查資料（比如每隔 5 秒查一次有沒有新訊息），而 Webhook 是 TG-Staff 在事件發生時，主動把資料推送到你的伺服器。

它的核心價值在於 即時性與去輪詢。想像一下：

• 沒有 Webhook：你需要寫一個排程任務，每 10 秒呼叫 TG-Staff 的「獲取未讀對話」介面，處理大量重複資料，伺服器壓力大，還有延遲。
• 有了 Webhook：當用戶第一次給 Bot 發訊息，TG-Staff 立即向你的 URL 發送一個 conversation.created 事件，你馬上就知道「有新客戶來了」，可以自動在 CRM 裡建立線索。

對於 B2B SaaS 團隊、跨境電商客服、Web3 專案方來說，這意味著可以將 Telegram 客服資料無縫接入現有的工單系統（如 Zendesk、Freshdesk）、資料分析平台（如 Mixpanel）、甚至內部 Slack 或釘釘通知。

---

可訂閱的事件類型一覽

TG-Staff 當前支援以下 Webhook 事件（以官方文件最新清單為準）。每個事件對應一個固定的 event_type 字串，你可以在目標伺服器上據此做邏輯分發。

事件名稱	event_type	觸發時機	典型用途
新對話建立	conversation.created	用戶首次聯繫 Bot，或重新開啟已關閉的對話	自動建立 CRM 線索、發送歡迎通知
新訊息	message.received	用戶或客服發送訊息（含文字、圖片等文字內容）	即時同步訊息到品管系統或知識庫
對話狀態變更	conversation.status_changed	對話從「等待」→「已分配」→「處理中」→「已關閉」	觸發工單狀態更新、關閉時發起滿意度調查
客服狀態變更	agent.status_changed	客服上線/離線/切換為忙碌	更新團隊排班看板、觸發 Slack 通知

---

如何設定 Webhook 事件？——三步完成整合

設定過程在 TG-Staff 控制台內完成，不需要寫程式，只需要你的後端接收 POST 請求。

步驟 1：找到 Webhook 設定入口

登入 TG-Staff 控制台，進入專案設定頁面。在側邊欄找到 「開發者」 或 「整合」 選單（具體名稱以控制台實際顯示為準）。你會看到一個「Webhook 設定」區塊。

步驟 2：填寫接收事件的目標 URL

• URL 必須是 HTTPS 協定（TG-Staff 不會向 HTTP 端點推送資料）。
• 如果你的伺服器需要身分驗證，可以在「請求標頭」區域加入自訂 Header（例如 Authorization: Bearer your-secret-token）。
• 點擊「儲存」後，TG-Staff 會向該 URL 發送一次 ping 測試，驗證連通性。如果回傳 200，設定即生效。

步驟 3：選擇需要訂閱的事件類型

你不需要訂閱所有事件。根據你的整合需求，勾選對應的事件即可。例如：

• 只需要在使用者首次聯絡時建立 CRM 記錄 → 只勾選 conversation.created
• 需要同步所有訊息到內部系統 → 勾選 message.received
• 需要完整的對話生命週期追蹤 → 勾選 conversation.created + conversation.status_changed + message.received

驗證 Webhook 是否生效

設定完成後，最直接的驗證方式是：用另一個 Telegram 帳號向你的 Bot 發送一則訊息，然後檢查目標伺服器的日誌。

常見問題排查：

• URL 不可達：檢查伺服器防火牆是否放行了 TG-Staff 的出口 IP（可在控制台查詢 IP 列表）。
• 回應逾時：TG-Staff 要求目標伺服器在 5 秒內回傳 200。如果處理邏輯複雜，建議先回傳 200，再非同步處理（如放入佇列）。
• 簽章驗證失敗：如果 TG-Staff 支援簽章金鑰（以官方文件為準），請確保驗證 X-TG-Staff-Signature 標頭的 HMAC 簽章。

安全建議：簽章驗證與重試機制

• 簽章驗證：如果 TG-Staff 提供了簽章金鑰，務必在接收端驗證請求的簽章，防止偽造回呼。驗證方式通常是使用 HMAC-SHA256 對請求體計算簽章，與請求標頭中的簽章比對。
• 重試策略：若目標伺服器回傳非 200 狀態碼，TG-Staff 預設重試最多 3 次，間隔分別為約 30 秒、2 分鐘、5 分鐘。若全部失敗，事件會丟棄（原始資料仍保留在 TG-Staff 平台，不會遺失）。建議你的伺服器始終回傳 200 確認接收。

---

典型整合場景：從客服到自動化

以下 3 個場景展示了 Webhook 事件如何將 TG-Staff 與你的業務系統打通。

場景 1：新對話 → 自動建立 CRM 工單

事件：conversation.created

流程：當使用者首次給 Bot 發訊息，TG-Staff 推送事件到你的伺服器 → 伺服器解析事件中的使用者 ID、對話 ID、首次訊息文字 → 自動在 CRM（如 HubSpot、Salesforce）中建立一筆潛在客戶或工單，標題為「Telegram 使用者 [使用者名稱] 新諮詢」，並附上對話連結。

效益：客服無需手動輸入客戶資訊，銷售團隊可以第一時間看到潛在客戶來源。

場景 2：客服回覆後 → 同步訊息到品管系統

事件：message.received

流程：每次客服發送訊息，事件推送到品管系統（如內部合規平台）→ 品管系統根據風險詞規則（可與 TG-Staff 專業版的內容風控連動）進行即時檢測 → 如果命中敏感詞，自動標記該則訊息並通知品管員。

效益：實現客服對話的即時品管，尤其適合 Web3、金融等對合規要求高的行業。

場景 3：對話關閉 → 觸發滿意度調查

事件：conversation.status_changed（狀態變為 closed）

流程：當客服關閉對話，TG-Staff 推送事件 → 伺服器判斷狀態為 closed → 自動向使用者發送一則滿意度調查連結（可透過 TG-Staff 的訊息群發功能或獨立 Bot 發送）→ 調查結果回傳至資料分析平台。

效益：無需人工觸發，自動收集使用者回饋，持續最佳化客服品質。

---

與 TG-Staff 其他功能的連動

Webhook 事件不是孤立的，它可以與 TG-Staff 既有的能力協同運作，產生更大的整合價值。

• 分流連結 + 新對話事件：當使用者透過廣告分流連結（Diversion Link）進入 Bot，conversation.created 事件中會攜帶 referrer 欄位（如廣告來源、URL 參數）。你可以據此分析不同渠道的轉換效果。
• 客服狀態變更 + 內部通知：當客服離線超過 30 分鐘，agent.status_changed 事件可觸發 Slack 或釘釘機器人通知，提醒管理者調整排班。
• 使用者輪廓資料豐富：在事件回呼中，TG-Staff 會附帶使用者 ID。你可以呼叫使用者輪廓 API（需專業版）取得使用者的標籤、歷史對話摘要，與事件資料合併後寫入外部資料庫。

注意事項：避免資料冗餘與循環

這是一個容易被忽略的陷阱。如果你的 Webhook 目標伺服器也向 TG-Staff 發送請求（例如，透過 TG-Staff 的 API 發送訊息），而該訊息又觸發了 message.received 事件，就會形成 A → B → A 的無限循環。

解決方案：在事件處理邏輯中，檢查訊息來源。例如，在事件負載中判斷 sender_type 是否為 agent 或 system，如果是客服發送的訊息，跳過寫入操作，避免重複。

---

常見問題

問：TG-Staff Webhook 事件是否支援自訂欄位或過濾條件？
答：目前 TG-Staff 的事件推送基於固定事件類型，不支援自訂欄位。但你可以透過事件中的會話 ID 或使用者 ID，在接收後呼叫其他 API（如使用者畫像介面）補充資料。過濾條件建議在目標伺服器端實作。

問：Webhook 事件推送失敗會怎麼樣？有重試機制嗎？
答：是的，TG-Staff 預設會重試最多 3 次（每次間隔約 30 秒、2 分鐘、5 分鐘）。若全部失敗，事件將丟棄，不會導致資料遺失（因為原始資料仍存於 TG-Staff 平台）。建議目標伺服器確保 200 回應。

問：我能否同時設定多個 Webhook URL 接收同一事件？
答：目前 TG-Staff 每個專案僅支援設定一個 Webhook URL。如需分發到多個系統，建議在目標伺服器內部轉發（如使用訊息佇列或中介軟體）。

問：Webhook 事件中是否包含使用者隱私資料（如手機號碼、電子郵件）？
答：Webhook 事件主要推送會話狀態、訊息 ID、使用者 ID 等元資料，不包含使用者 Telegram 端的敏感資訊（如手機號碼）。使用者畫像中的自訂資料（如標籤）可能包含業務資料，請根據你的隱私政策處理。

問：如何測試 Webhook 設定是否生效？
答：在控制台 Webhook 設定頁，通常有「發送測試事件」按鈕。如果沒有，你可以手動建立一個新會話（如用測試 Bot 發送一則訊息），然後檢查目標伺服器日誌是否收到對應的 POST 請求。

---

開始整合你的 Telegram 客服資料

TG-Staff Webhook 事件是連接客服資料與業務系統的「高速公路」。無論你是想自動建立 CRM 工單、即時稽核訊息內容，還是建構全鏈路使用者行為分析，它都能幫你省去輪詢的麻煩，讓資料真正流動起來。

• 免費試用：註冊即享 3 天試用，標準版及以上方案支援 Webhook 功能（具體方案以官網為準）。
• 查閱文件：取得最新事件列表、欄位說明與簽章驗證範例 → TG-Staff 官方文件
• 諮詢客服：對整合有疑問？直接聯絡 @tgstaff_robot，技術團隊會協助你完成設定。

立刻體驗 Webhook 事件整合，讓你的 Telegram 客服營運從「手動搬運」升級為「事件驅動」的自動化工作流程。