Webhook

Webhook 回呼整合：把對話平台上的訪客訊息與 Agent、真人客服的回覆即時推送到你自己的系統——客服系統整合、即時通知推送、對話記錄歸檔、內部流程自動化。

方案導覽：本頁是對話平台設定的其中一步，文字客服的完整上線流程見 文字客服：從零到上線。

用途

Webhook 設定在對話平台上。開發者提供一個 API 端點（一個網址）後，這個對話平台每建立一則訊息，MaiAgent 就把訊息內容送到這個網址，讓您把對話整合進自己的系統，例如記錄下來、再轉發給使用者，或做其他應用。

每個對話平台可以設定多個 Webhook，各自決定推送哪個方向的訊息：

類型	什麼時候推送
Outgoing	Agent 或真人客服的回覆建立時
Incoming	訪客的訊息建立時
Receive	由外部客服平台把訊息送回 MaiAgent（目前支援 Genesys Cloud）

每次推送的內容、回應與狀態碼都會留下紀錄，方便您查看與排查問題，見下方查看推送紀錄。

推送內容的欄位、自訂範本寫法與以 API 管理 Webhook 的方式，請交給您的工程師參考技術手冊的 Webhook；要由自己的客服系統接手轉真人對話，見 第三方客服系統串接（含轉真人）。

新增 Webhook

1. 進入 Webhook 設定

前往 客服對話 → 對話平台，在要設定的對話平台按 編輯，進入 Webhook 設定：

• API 平台：在左側選單的「串接與登入」群組。

• LINE、Slack、Microsoft Teams 等通訊平台：在上方分頁列。

• 網頁、內部平台沒有這個設定。哪些平台有 Webhook 設定，見平台支援對照表。

2. 填寫 Webhook 欄位

點 新增 Webhook，填入下列欄位後儲存：

欄位	說明
名稱	自訂名稱，方便辨識
類型	Outgoing、Incoming 或 Receive，見上方類型說明；選 Receive 時欄位不同，見下方 Receive 類型的欄位
啟用狀態	關閉時不推送，設定會保留
Webhook URL	您的系統接收資料的網址
HTTP Method	使用 POST（預設）、PUT 或 PATCH
Headers	每次推送都會附上的自訂標頭，例如您系統要求的 API 金鑰
Payload 格式	MaiAgent Standard（標準格式）、Genesys Cloud，或用 Jinja2 撰寫的 自訂範本（表單會列出可用變數）。選 Genesys Cloud 時，Webhook URL 與 Headers 改由下方的 Genesys Cloud 整合 區自動產生

Receive 類型的欄位

Receive 是反方向：由外部客服平台把訊息送進 MaiAgent，所以不填您的網址，改由 MaiAgent 提供一個接收網址給對方：

欄位	說明
Payload 預設格式	對方送來的格式，目前支援 Genesys Cloud（符合 Genesys Cloud Open Messaging API 格式）
Secret Token	用於簽章驗證的密鑰，請與對方平台設定一致；編輯時留空代表保留現有值，輸入新值才會更新
接收 URL	儲存後才會顯示。複製這個 URL，到外部平台設定為 outbound webhook URL

Genesys Cloud 整合

Payload 格式選 Genesys Cloud 的 Outgoing／Incoming Webhook，表單下方會出現「Genesys Cloud 整合」區，填一次即套用到這個對話平台底下所有 Genesys Cloud Webhook：

欄位	說明
區域	您的 Genesys Cloud 組織所在區域
OAuth Client ID／OAuth Client Secret	Genesys Cloud 的 OAuth Client Credentials，需具備 conversation:message:create 權限；MaiAgent 會用它自動取得 Token，不必手動填 Headers
Integration ID	Genesys Cloud Admin → Message → Platforms 裡的 Open Messaging Integration ID

填好後可按 測試連線 確認憑證有效，再儲存。之後若 Genesys Cloud 回報憑證失效，Webhook 清單上方會出現警示並標示受影響的筆數，請點 修改整合設定 重新輸入 Client Secret 並儲存；移除整合 會讓已設定的 Genesys Cloud Webhook 無法送出訊息。完整串接步驟見技術手冊的 第三方客服系統串接。

3. 確認推送

到對話平台送一則訊息，再到推送紀錄確認狀態碼為 2xx。

目前的推送行為請先納入您的系統設計：

• 沒有簽章：推送不帶對內容計算的簽章。要讓接收端確認來源，請在 Headers 加一個雙方約定的值，並使用 https:// 網址。

• 失敗不重試：您的系統回應 2xx 才算成功；超過 30 秒沒回應或回應非 2xx 都記為失敗，不會自動重送。需要可靠交付時，請在接收端先存下資料再回應 2xx。

• 內網位址預設會被拒絕：私有網段、內網位址的網址預設無法接收推送。

查看推送紀錄

進入 AI 功能 → AI 助理，選擇這個對話平台所接的 Agent，切換到 Webhook 分頁。清單列出每次推送的對話 ID、訊息 ID、URL、狀態碼與建立時間；點選操作欄的檢視圖示，可看到請求預覽、請求 JSON 與回應內容。

Agent 的 Webhook 分頁只有推送紀錄，彙整這個 Agent 底下所有對話平台的 Webhook 結果；要新增、修改或停用 Webhook，仍要回到各對話平台設定頁的 Webhook 設定（見新增 Webhook）。同一個 Agent 接多個平台時，請用清單的對話 ID 對回是哪個平台的對話。

應用場景

客服系統整合

當 Agent 回答完用戶問題後，透過 Webhook 將回覆內容同步到企業的客服系統，方便客服人員查看對話紀錄、進行後續處理或人工接手。

即時通知推送

將 Agent 的回覆或特定事件（如異常狀況）推送至 Slack、Line Notify、Email 等通訊工具，提醒相關人員即時處理。

數據分析與記錄歸檔

自動將所有 AI 對話資料傳送至資料倉儲、雲端資料庫或 Google Sheets，進行使用行為分析、品質評估或建立互動記錄存檔。

內部流程自動化

如使用者透過 Agent 提報問題、申請資源或回報異常，Webhook 可將這些資料自動串接到內部表單系統、任務管理工具（如 Jira、Notion）進行後續追蹤。

與轉真人通知的差別

本頁的 Webhook 以訊息為單位推送。要在對話轉給真人、轉回 AI 或排隊逾時時通知外部系統，請改用客服轉真人設定裡的 Webhook 通知（系統串接），兩者的設定各自獨立。