> 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/tech/api-integration/customer-service-system-integration.md). # 第三方客服系統串接（含轉真人） 客服系統或聊天平台以 API 接入 MaiAgent 當 AI 引擎：訊息進出、AI 判定轉真人時交由您的真人客服接手、結束後回到 AI 的端到端規格 {% hint style="warning" %} **發布狀態：待正式上線。** 本頁描述新版四事件轉真人契約與 `id`／`occurred_at` 巢狀 payload，目前尚未在正式環境發布。請勿依本頁的新契約啟用正式串接；請先向 MaiAgent 團隊確認您的環境已完成更新。以下內容供整合規劃與測試使用。 {% endhint %} 本頁適合「已有自己的客服系統或聊天前台（自有網頁、LINE、Messenger 等通道掛在您這邊），要把 MaiAgent 當作 **AI 引擎**」的整合方：訪客訊息由您的系統送進 MaiAgent，AI 回覆推回您的系統；當 AI 判定需要真人時，由**您的真人客服**接手，服務結束後再把對話交還給 AI。 整合只用到 MaiAgent 既有的公開 API 與兩組 Webhook，不需要為單一客服系統開發專屬介面。 ## 整合全景 ```mermaid sequenceDiagram participant V as 訪客 participant S as 您的客服系統 participant M as MaiAgent participant H as 您的真人客服 V->>S: 發話（網頁 / LINE / …） S->>M: ① 身份同步（sourceId → contactId） S->>M: ② 建立對話（首次） S->>M: ③ 送出訊息 POST /messages/ M-->>S: 201（AI 回覆非同步） M-)S: ④ Outgoing Webhook：AI 回覆 S->>V: 顯示 AI 回覆 Note over M: AI 判定需要真人 M-)S: ⑤ handoff.requested S->>H: 建立案件、指派客服 H->>V: 真人接續服務（在您的系統內） S->>M: ⑥ PATCH /conversations/{id}/return-to-ai/ M-)S: handoff.returned_to_ai Note over M: 後續訊息恢復由 AI 回覆 ``` ### 雙方分工 | 誰 | 負責 | | ------------ | ----------------------------------------------------------------------- | | **您的系統** | 通道接入、訪客介面、案件與客服座席、對話紀錄的保存與呈現；把訪客訊息送進 MaiAgent、接收 Webhook、真人服務結束時呼叫回到 AI | | **MaiAgent** | AI 回覆、對話上下文維持、以 LLM 判定是否轉真人、轉真人與回到 AI 的事件推送 | ## 前置設定 以下都在 MaiAgent 後台完成，一個對話平台設定一次。 ### 1. 建立 Web Chat 對話平台並取得憑證 API 串接使用 **Web Chat** 類型的對話平台。您需要： * **API 金鑰**：取得方式見 [快速上手](/tech/api-integration/quickstart.md)。 * **Web Chat ID**：在 AI 助理詳細頁最下方。 ### 2. 設定 Outgoing Webhook（接收 AI 回覆） 設定 → 對話平台 → 該平台 → Webhooks → 新增 Webhook，類型選 **Outgoing**，端點填您的回覆接收 URL。格式選 **MaiAgent 標準格式**；若您的系統要求固定 JSON 結構，選 **自訂範本**。欄位與 payload 見 [Webhook](/tech/api-integration/webhook.md)。 ### 3. 啟用真人客服轉接 同一個對話平台 → 客服轉真人設定 分頁： | 設定 | 建議 | | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 啟用真人客服轉接 | 開啟 | | 判定模型、角色指令、參考訊息數 | 判定是否轉真人的 LLM 與規則。預設規則：訪客明確要求真人、問題超出 AI 能處理、訪客情緒不佳、涉及需人工核實的帳務操作。可在角色指令中依您的業務調整（例如加上關鍵字、信心不足即轉） | | 等待超時時間 | **關鍵設定。** 轉真人後對話進入排隊；超過此秒數沒有 MaiAgent 成員接手，MaiAgent 會自動把對話轉回 AI。真人客服在您的系統時，MaiAgent 看不到接手動作，因此請設為 **0（不逾時，由您呼叫回到 AI）**，或設為足以涵蓋整段真人服務的時間 | | 排隊上限 | 同時處於轉真人狀態的對話數上限（1–500）。額滿時新的轉真人請求不會觸發：該則訊息不會有 AI 回覆，也不會發送 `handoff.requested`。依您的客服容量設定 | | 服務時間 | 啟用後，非服務時間 AI 不會轉真人：顯示離線訊息 時該則訊息不回 AI、也不發送 `handoff.requested`（離線訊息同樣只推給 Web Chat 前端，非服務時間的提示請由您的系統處理）；接受留言 時仍進入排隊並發送 `handoff.requested`（此路徑不啟動等待超時） | {% hint style="warning" %} 轉接通知訊息、排隊等待提示 等「給訪客看的提示文字」是推送給 MaiAgent 自家 Web Chat 前端的，**不會經由 Webhook 送到您的系統**。請在收到 `handoff.requested` 時，由您的系統自行向訪客顯示「正在為您轉接真人客服」等提示。 {% endhint %} ### 4. 開啟轉真人 Webhook 同一分頁 → 子分頁 通知 → 開啟 Webhook 通知（系統串接），填入： * Webhook 網址：僅接受 HTTPS。 * 簽章密鑰（建議）：設定後每次推送帶 HMAC-SHA256 簽章，驗證方式見 [步驟五](#step-handoff)。 Email 通知 與 通知中心公告 只在對話指派給 MaiAgent 成員時發送，與本整合無關，可關閉。 {% hint style="info" %} 轉真人通知（含 Webhook）需由 MaiAgent 為您的組織開通。若通知分頁沒有此區塊，請聯繫您的對接窗口。 {% endhint %} ## 步驟一：對應訪客身份 以您系統中的使用者 ID 呼叫身份同步 API，取得該訪客在 MaiAgent 的 `contactId`： ```bash curl -X POST \ 'https://api.maiagent.ai/api/v1/web-chats/{webChatId}/setup-contact-credentials/' \ -H 'Content-Type: application/json' \ -d '{ "sourceId": "your-user-id", "name": "王小明" }' ``` ```json { "contactId": "c0ffee00-1111-2222-3333-444455556666" } ``` 同一個 `sourceId` 重複呼叫會回傳同一個 `contactId`（冪等），請把 `sourceId ↔ contactId` 存在您的使用者資料中。`sourceId` 請使用不可猜測的值。完整說明見 [聯絡人身份同步與 Token 更新](/tech/authorization-integration/contact-credentials-sync.md)。 ## 步驟二：建立對話 每位訪客建立一個對話並**長期沿用**，MaiAgent 會以對話為單位維持上下文： ```bash curl -X POST 'https://api.maiagent.ai/api/v1/conversations/' \ -H 'Authorization: Api-Key <您的API金鑰>' \ -H 'Content-Type: application/json' \ -d '{ "webChat": "", "contact": "" }' ``` 回應中請記下 `id`（對話 ID）與 `inbox.id`（對話平台 ID，設定 Webhook 時會用到）。回應欄位見 [建立對話與訊息](/tech/api-integration/dui-hua-yu-xun-xi.md)。 若您希望每次來訪重新開始一段對話（例如案件結案後），再建立一個新對話即可；舊對話的紀錄仍保留。 ## 步驟三：送出訪客訊息 ```bash curl -X POST 'https://api.maiagent.ai/api/v1/messages/' \ -H 'Authorization: Api-Key <您的API金鑰>' \ -H 'Content-Type: application/json' \ -d '{ "conversation": "<對話 ID>", "content": "我想查詢訂單進度", "attachments": [] }' ``` 回應 `201` 只代表訊息已建立，**AI 回覆會在數秒內以 Outgoing Webhook 推送**（步驟四），HTTP 回應本身不帶回覆。附件請先上傳取得附件物件再帶入 `attachments`，見 [Presigned 檔案上傳模式](/tech/api-integration/api_knowledge.md)。 ## 步驟四：接收 AI 回覆 AI 回覆建立後，MaiAgent 對您設定的 Outgoing Webhook 發出請求。以標準格式為例，您的端點會收到： ```json { "id": "2491074a-6d23-4289-af45-caa12531420e", "type": "outgoing", "content": "您的訂單 #12345 目前配送中，預計明天送達。", "created_at": "2026-09-09T10:15:30.123456+00:00", "conversation": { "id": "8e44604a-8278-4c96-96b5-3e5a0548d738", "status": "open", "progress_status": "ai_processing", "auto_reply_enabled": true, "assignee": null }, "contact": { "id": "c0ffee00-1111-2222-3333-444455556666", "name": "王小明" }, "sender": { "id": "…", "name": "AI 智能客服", "type": "chatbot" }, "attachments": [] } ``` 您的系統依 `contact.id` 找到對應使用者、依 `conversation.id` 找到對話，把 `content` 與附件轉成您通道的格式送給訪客。請回應 2xx；完整欄位、自訂範本與傳送行為見 [Webhook](/tech/api-integration/webhook.md)。 {% hint style="info" %} 若您需要在 payload 裡直接拿到自己的使用者 ID 或可下載的附件網址，使用 **自訂範本** 輸出 `contact.source_id` 與 `attachment.file.url`，範例見 [Webhook › 自訂範本](/tech/api-integration/webhook.md#custom-template)。 {% endhint %} ## 步驟五：AI 判定轉真人 每則訪客訊息進來時，MaiAgent 先以判定模型判斷是否需要真人。判定為「需要」時： 1. 對話狀態變為 `queued`、`auto_reply_enabled` 變為 `false`，**這則訊息不會有 AI 回覆**，後續訊息也不再由 AI 回覆。 2. MaiAgent 對您的轉真人 Webhook 網址送出 `handoff.requested` 事件。 ### 事件 payload ```json { "event": "handoff.requested", "id": "7d1e2f3a-4b5c-4d6e-8f90-1a2b3c4d5e6f", "occurred_at": "2026-09-09T10:15:30.123456+00:00", "conversation": { "id": "8e44604a-8278-4c96-96b5-3e5a0548d738", "url": "https://admin.maiagent.ai/conversations/index?conversationId=8e44604a-…" }, "inbox": { "id": "1f9c1c1e-4d1a-4b1e-9d0e-7b2f4a5c6d7e" }, "organization": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" }, "contact": { "id": "c0ffee00-1111-2222-3333-444455556666" }, "assignee": null } ``` | 欄位 | 說明 | | -------------------------------- | ----------------------------------------------------------------------------------------- | | `event` | 事件名稱，見下方[事件一覽](#events) | | `id` | 事件識別碼；重試會送完全相同的內容，請以它去重 | | `occurred_at` | 事件發生時間（ISO 8601）；送達不保證順序，請以它排序 | | `conversation.id` / `contact.id` | 對應您在步驟一、二記下的對話與訪客；`conversation.url` 是 MaiAgent 後台該對話的連結 | | `inbox.id` / `organization.id` | 對話平台與組織 ID | | `assignee` | **事件當下**被指派的 MaiAgent 成員 `{ "id" }`（事件快照，不受之後變化影響）；`handoff.requested` 與由您的客服接手時恆為 `null` | 欄位命名與巢狀結構和步驟四的訊息 Webhook 一致（snake\_case、關聯物件以 `{ "id" }` 巢狀），同一支接收端可以同時處理兩組推送。payload 只含識別資訊，不含對話內容；四種事件的欄位完全相同，請依 `event` 分流。完整規格與可直接啟動的接收端範例見 API 文件的[轉真人 Webhook 事件](https://docs.maiagent.ai/api/preparation/handoff-webhook)。 ### 傳送與簽章 * `POST`、`Content-Type: application/json`，逾時 10 秒；非 2xx 或連線失敗會**每 60 秒重試，最多 3 次**。 * 有設定簽章密鑰時，請求帶 `X-MaiAgent-Signature-256: sha256=`，值為以密鑰對\*\*原始請求內容（bytes）\*\*計算的 HMAC-SHA256。請用收到的原始 body 驗證，不要先解析再重新序列化： ```python import hashlib import hmac def verify_maiagent_signature(secret: str, raw_body: bytes, header_value: str) -> bool: expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, header_value) ``` ### 您的系統收到 `handoff.requested` 後 * 在您的系統建立案件、指派真人客服，並向訪客顯示轉接提示。 * 之後訪客的訊息由您的客服在您的系統內處理。**可以不再送進 MaiAgent**；若您仍希望 MaiAgent 保留完整紀錄，可以繼續呼叫 `POST /messages/`——訊息會存入對話並觸發 Incoming Webhook，但在回到 AI 之前不會產生 AI 回覆。 * 真人客服的回覆由您的系統直接送給訪客，不需要經過 MaiAgent。 ## 步驟六：真人服務結束，回到 AI 案件結束時，呼叫回到 AI： ```bash curl -X PATCH 'https://api.maiagent.ai/api/v1/conversations/{conversationId}/return-to-ai/' \ -H 'Authorization: Api-Key <您的API金鑰>' ``` 對話回到 `open`、`auto_reply_enabled` 恢復 `true`，MaiAgent 送出 `handoff.returned_to_ai`，之後的訪客訊息恢復由 AI 回覆。回應為更新後的對話物件。 {% hint style="warning" %} API 金鑰所屬的成員需要有該對話平台的對話存取權限。若 等待超時時間 不是 0，逾時到期 MaiAgent 會自動回到 AI 並送出 `handoff.queue_timeout`——請確認這符合您的流程，或依前置設定改為 0。非服務時間以 接受留言 進入排隊的對話**不會啟動等待超時**，一律要由您的系統呼叫 `return-to-ai` 結束。 {% endhint %} ## 事件一覽 | `event` | 觸發時機 | 對您的系統的意義 | | ------------------------ | ----------------------------------------------- | ---------------------------- | | `handoff.requested` | AI 判定需要真人，對話進入排隊，AI 停止回覆 | 由您的真人客服接手 | | `handoff.assigned` | 對話指派給 MaiAgent 後台的客服成員（成員在後台接手、轉接或自動指派；轉接會再送一筆） | 若真人全在您的系統，不會收到此事件 | | `handoff.returned_to_ai` | 您呼叫 `return-to-ai`，或成員在後台按「轉回 AI Agent」 | AI 恢復回覆，您可結案 | | `handoff.queue_timeout` | 等待超時時間到期，MaiAgent 自動把對話轉回 AI | AI 已恢復回覆；若您的客服仍在處理，這是需要告警的異常 | 每個事件在 `GET /api/v1/conversations/{id}/events/` 都有對應的 `event_type`（`transfer_triggered`／`human_assigned`／`returned_to_ai`／`queue_timeout`），可用於對帳。 {% hint style="info" %} 事件各自以背景任務送出，**不保證到達順序**，也可能因重試而重複。請以事件 `id` 去重、以 `occurred_at` 排序，並把 `handoff.assigned` 視為隱含已觸發。 {% endhint %} ### 用 API 查詢目前狀態 Webhook 之外，隨時可以查詢對話目前由誰處理： ```bash GET https://api.maiagent.ai/api/v1/conversations/{conversationId}/ ``` `status`（`open`／`queued`／`resolved`）、`autoReplyEnabled` 與 `progressStatus`（`ai_processing`／`waiting_for_human`／`human_serving`）足以還原狀態；`GET /api/v1/conversations/{conversationId}/events/` 則列出轉真人相關的事件紀錄（`transfer_triggered`、`queued`、`human_assigned`、`returned_to_ai`、`queue_timeout` 等），可作為對帳或補償用途。 ## 串接前常見問題 客服系統廠商在 kick-off 時通常會提出下列問題，答案整理於此，可直接作為雙方對接文件的附件。 ### 環境與路徑 | 環境 | Base URL | | -- | ------------------------------------- | | 測試 | `https://api-dev.maiagent.ai/api/v1/` | | 正式 | `https://api.maiagent.ai/api/v1/` | 本整合用到的路徑固定：`POST /web-chats/{webChatId}/setup-contact-credentials/`、`POST /conversations/`、`POST /messages/`、`PATCH /conversations/{id}/return-to-ai/`；對帳用 `GET /conversations/{id}/` 與 `GET /conversations/{id}/events/`。測試環境的組織、API 金鑰與 Web Chat 由您的對接窗口建立後提供。 ### 認證 * **您呼叫 MaiAgent**：標頭 `Authorization: Api-Key <金鑰>`。身份同步 API 不需金鑰，以 `webChatId` 識別。 * **MaiAgent 推送給您**：訊息 Webhook 帶您設定的固定標頭 `X-Webhook-Secret`；轉真人 Webhook 帶對原始 request body 計算的 HMAC-SHA256 簽章 `X-MaiAgent-Signature-256: sha256=`。 ### 逾時、重試與流量上限 | 方向 | 逾時 | 重試 | | ------------------------- | -------------------- | ----------------------------------- | | 您呼叫 `POST /messages/` | 同步回 201，建議客戶端逾時 10 秒 | 4xx 先修正請求；5xx 或逾時表示結果不確定，先對帳，不要直接重送 | | 訊息 Webhook（MaiAgent → 您） | 30 秒 | **不重試**；請先落地再回 2xx，以訊息 `id` 去重 | | 轉真人 Webhook（MaiAgent → 您） | 10 秒 | 失敗每 60 秒重試，最多 3 次；以事件 `id` 去重 | `POST /messages/` 不保證冪等：伺服器可能已建立訊息，但回應在傳輸途中遺失。請先透過對話記錄與自有送件記錄確認結果；無法確認時，直接重送可能新增重複訊息並再次觸發 AI 回覆。 每把 API 金鑰可設定每分鐘請求上限（RPM），預設不限制；正式上線前請提供預估流量，由對接窗口設定。 ### 來源 IP 白名單 MaiAgent 推送 Webhook 的出站 IP 固定。若您的接收端需要白名單，請向對接窗口索取正式與測試環境的最新清單。MaiAgent 對您的接收端網域沒有出站限制。 ### 對話 session 的對應 鍵是聯絡人的 `sourceId`（建議用 `{平台}:{您的使用者 ID}` 避免跨通道撞號）。同一 `sourceId` 重複呼叫身份同步 API 回同一 `contactId`；對話建立後**沒有存續時間限制**，可長期沿用同一對話 ID 維持上下文，也可在結案後為同一聯絡人建立新對話重新開始。 ### 轉真人的判定邏輯 由判定模型依對話最近 N 則訊息判斷，預設規則：訪客明確要求真人、問題超出 AI 能處理、訪客情緒不佳、涉及需人工核實的帳務操作。規則以自然語言在角色指令調整，可加關鍵字、信心不足即轉等條件；也可設定服務時間決定非服務時間是否轉接。判定結果就是 `handoff.requested` 事件。 ### 多段回覆與訊息樣式 每則 AI 回覆推送一筆訊息 Webhook（一筆一則），不做批次；一則回覆可含多個附件。若您的系統要求陣列格式，以自訂範本輸出單元素陣列即可。標準支援文字（Markdown）與附件（圖片／影片／音訊／檔案）；按鈕、卡片、快速回覆等通道專屬樣式不在標準範圍，請於 kick-off 提出需求另行評估。 ### 附件網址與存續時間 AI 回覆的附件以自訂範本輸出 `attachment.file.url`，為簽名網址、**有效 1 小時**，請於收到後立即取檔轉存。訪客上傳的附件由您的系統先取得可下載網址，於送出訊息時帶入 `attachments[]`。 ### 錯誤與用量查詢 訊息 Webhook 每次推送的請求、回應與狀態碼可在 MaiAgent 後台 AI 助理頁面的 Webhook 分頁查看；對話狀態與轉真人事件可用對話 API 與事件紀錄 API 查詢對帳；AI 用量在後台用量統計。轉真人 Webhook 推送失敗會進 MaiAgent 的監控告警。 ## 整合檢查清單 * [ ] 後台：Outgoing Webhook 已設定並能收到 AI 回覆 * [ ] 後台：真人客服轉接已啟用，等待超時時間 已依流程設定（外部真人客服建議 0） * [ ] 後台：轉真人 Webhook 已開啟、HTTPS 端點可達、簽章驗證通過 * [ ] 您的系統：`sourceId ↔ contactId ↔ conversationId` 對應已落地 * [ ] 您的系統：`handoff.requested` → 建案與轉接提示；`handoff.returned_to_ai` → 結案；`handoff.queue_timeout` → 告警或結案 * [ ] 您的系統：真人服務結束時呼叫 `return-to-ai` * [ ] 兩個 Webhook 端點皆做冪等：轉真人事件與訊息推送都以各自的 `id` * [ ] 若您的網路需要來源 IP 白名單，請向對接窗口索取 MaiAgent 的出站 IP ## 相關頁面 * [轉真人 Webhook 事件](https://docs.maiagent.ai/api/preparation/handoff-webhook)（API 文件）：事件完整規格、簽章驗證、可直接啟動的接收端範例，以及訪客在 MaiAgent 通道、真人在您系統的接手方式 * [Webhook](/tech/api-integration/webhook.md)：訊息推送格式、自訂範本、以 API 管理 Webhook * [建立對話與訊息](/tech/api-integration/dui-hua-yu-xun-xi.md)：對話與訊息 API 完整欄位 * [聯絡人身份同步與 Token 更新](/tech/authorization-integration/contact-credentials-sync.md)：`setup-contact-credentials` 完整規格 * [Presigned 檔案上傳模式](/tech/api-integration/api_knowledge.md)：附件上傳 --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maiagent.ai/tech/api-integration/customer-service-system-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.