> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/conversation-settings/webhook.md).

# Webhook

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

{% hint style="info" %}
**方案導覽**：本頁是對話平台設定的其中一步，文字客服的完整上線流程見 [文字客服：從零到上線](/serve/text-service.md)。
{% endhint %}

## 用途 <a href="#usage" id="usage"></a>

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

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

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

每次推送的內容、回應與狀態碼都會留下紀錄，方便您查看與排查問題，見下方[查看推送紀錄](#delivery-records)。

{% hint style="info" %}
推送內容的欄位、自訂範本寫法與以 API 管理 Webhook 的方式，請交給您的工程師參考技術手冊的 [Webhook](https://docs.maiagent.ai/tech/serve/webhook)；要由自己的客服系統接手轉真人對話，見 [第三方客服系統串接（含轉真人）](https://docs.maiagent.ai/tech/serve/customer-service-system-integration)。
{% endhint %}

## 新增 Webhook <a href="#add-webhook" id="add-webhook"></a>

### 1. 進入 Webhook 設定 <a href="#open-webhook-settings" id="open-webhook-settings"></a>

前往 <mark style="color:blue;">客服對話</mark> → <mark style="color:blue;">對話平台</mark>，在要設定的對話平台按 <mark style="color:blue;">編輯</mark>，進入 <mark style="color:blue;">Webhook 設定</mark>：

* **API 平台**：在左側選單的「串接與登入」群組。
* **LINE、Slack、Microsoft Teams 等通訊平台**：在上方分頁列。
* **網頁、內部平台**沒有這個設定。哪些平台有 Webhook 設定，見[平台支援對照表](/build/conversation-settings/platform-settings.md#platform-matrix)。

### 2. 填寫 Webhook 欄位 <a href="#webhook-fields" id="webhook-fields"></a>

點 <mark style="color:blue;">新增 Webhook</mark>，填入下列欄位後儲存：

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

#### Receive 類型的欄位 <a href="#receive-fields" id="receive-fields"></a>

<mark style="color:blue;">Receive</mark> 是反方向：由外部客服平台把訊息送**進** MaiAgent，所以不填您的網址，改由 MaiAgent 提供一個接收網址給對方：

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

#### Genesys Cloud 整合 <a href="#genesys-cloud-integration" id="genesys-cloud-integration"></a>

Payload 格式選 <mark style="color:blue;">Genesys Cloud</mark> 的 Outgoing／Incoming Webhook，表單下方會出現「<mark style="color:blue;">Genesys Cloud 整合</mark>」區，填一次即套用到這個對話平台底下所有 Genesys Cloud Webhook：

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

填好後可按 <mark style="color:blue;">測試連線</mark> 確認憑證有效，再儲存。之後若 Genesys Cloud 回報憑證失效，Webhook 清單上方會出現警示並標示受影響的筆數，請點 <mark style="color:blue;">修改整合設定</mark> 重新輸入 Client Secret 並儲存；<mark style="color:blue;">移除整合</mark> 會讓已設定的 Genesys Cloud Webhook 無法送出訊息。完整串接步驟見技術手冊的 [第三方客服系統串接](https://docs.maiagent.ai/tech/serve/customer-service-system-integration)。

### 3. 確認推送 <a href="#verify-delivery" id="verify-delivery"></a>

到對話平台送一則訊息，再到[推送紀錄](#delivery-records)確認狀態碼為 2xx。

{% hint style="warning" %}
目前的推送行為請先納入您的系統設計：

* **沒有簽章**：推送不帶對內容計算的簽章。要讓接收端確認來源，請在 <mark style="color:blue;">Headers</mark> 加一個雙方約定的值，並使用 `https://` 網址。
* **失敗不重試**：您的系統回應 2xx 才算成功；超過 30 秒沒回應或回應非 2xx 都記為失敗，不會自動重送。需要可靠交付時，請在接收端先存下資料再回應 2xx。
* **內網位址預設會被拒絕**：私有網段、內網位址的網址預設無法接收推送。
  {% endhint %}

## 查看推送紀錄 <a href="#delivery-records" id="delivery-records"></a>

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

Agent 的 <mark style="color:blue;">Webhook</mark> 分頁只有推送紀錄，彙整這個 Agent 底下所有對話平台的 Webhook 結果；要新增、修改或停用 Webhook，仍要回到各對話平台設定頁的 <mark style="color:blue;">Webhook 設定</mark>（見[新增 Webhook](#add-webhook)）。同一個 Agent 接多個平台時，請用清單的對話 ID 對回是哪個平台的對話。

## 應用場景 <a href="#use-cases" id="use-cases"></a>

### **客服系統整合** <a href="#customer-service-system-integration" id="customer-service-system-integration"></a>

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

### **即時通知推送** <a href="#real-time-notification-push" id="real-time-notification-push"></a>

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

### **數據分析與記錄歸檔** <a href="#data-analytics-and-archiving" id="data-analytics-and-archiving"></a>

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

### **內部流程自動化** <a href="#internal-workflow-automation" id="internal-workflow-automation"></a>

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

## 與轉真人通知的差別 <a href="#vs-handoff-notification" id="vs-handoff-notification"></a>

本頁的 Webhook 以**訊息**為單位推送。要在對話轉給真人、轉回 AI 或排隊逾時時通知外部系統，請改用客服轉真人設定裡的 [Webhook 通知（系統串接）](/build/conversation-settings/human-handoff/handoff-notification.md#webhook)，兩者的設定各自獨立。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/conversation-settings/webhook.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.