第三方客服系統串接（含轉真人）

客服系統或聊天平台以 API 接入 MaiAgent 當 AI 引擎：訊息進出、AI 判定轉真人時交由您的真人客服接手、結束後回到 AI 的端到端規格

本頁適合「已有自己的客服系統或聊天前台（自有網頁、LINE、Messenger 等通道掛在您這邊），要把 MaiAgent 當作 AI 引擎」的整合方：訪客訊息由您的系統送進 MaiAgent，AI 回覆推回您的系統；當 AI 判定需要真人時，由您的真人客服接手，服務結束後再把對話交還給 AI。

整合只用到 MaiAgent 既有的公開 API 與兩組 Webhook，不需要為單一客服系統開發專屬介面。

兩種串接情境

情境	訪客在哪裡對話	真人客服在哪裡	怎麼串
情境 A：MaiAgent 當 AI 引擎	您的系統（自有網頁、LINE 等通道掛在您這邊）	您的系統	前置設定後依步驟一～步驟六
情境 B：只有真人客服在您的系統	MaiAgent 的對話平台（Web Chat、LINE 官方帳號等接在 MaiAgent）	您的系統	前置設定後依情境 B

兩種情境的轉真人事件、事件一覽與狀態查詢相同。下方的整合全景與步驟一～六以情境 A 說明。

整合全景

雙方分工

誰	負責
您的系統	通道接入、訪客介面、案件與客服座席、對話紀錄的保存與呈現；把訪客訊息送進 MaiAgent、接收 Webhook、真人服務結束時呼叫回到 AI
MaiAgent	AI 回覆、對話上下文維持、以 LLM 判定是否轉真人、轉真人與回到 AI 的事件推送

前置設定

以下都在 MaiAgent 後台完成，一個對話平台設定一次。

1. 建立 Web Chat 對話平台並取得憑證

API 串接使用 Web Chat 類型的對話平台。您需要：

• API 金鑰：取得方式見 快速上手。

• Web Chat ID：客服對話 → 對話平台 → 編輯該 API 平台 → 串接與登入 → Webhook 設定 最下方的 API 資訊 卡，唯讀並可複製；見使用者手冊對話平台基本設定。

2. 設定 Outgoing Webhook（接收 AI 回覆）

客服對話 → 對話平台 → 編輯該平台 → Webhook 設定 → 新增 Webhook，類型選 Outgoing，端點填您的回覆接收 URL。格式選 MaiAgent 標準格式；若您的系統要求固定 JSON 結構，選 自訂範本。欄位與 payload 見 Webhook。

3. 啟用真人客服轉接

同一個對話平台 → 客服轉真人設定。每個欄位的意義與操作畫面見使用者手冊的客服轉真人設定；真人客服在您的系統時，建議這樣設定：

設定	真人客服在您的系統時的建議
啟用真人客服轉接	開啟
轉真人條件 的判定規則（角色指令）	先用預設規則：訪客明確要求真人、問題超出 AI 能處理、訪客情緒不佳、涉及需人工核實的帳務操作。再依您的業務調整，例如加上關鍵字、信心不足即轉
派工設定 → 派工模式	選 接手制。MaiAgent 不會把對話派給後台成員，對話留在排隊中，由您的系統接手
派工設定 → 等待超時時間	勾選 不逾時（只有接手制能勾）。對話會一直排隊，直到您呼叫回到 AI；MaiAgent 不會自行把對話轉回 AI
派工設定 → 排隊上限	依您的客服容量設定（1–500）。額滿時新的轉真人請求不會觸發：該則訊息不會有 AI 回覆，也不會發送 handoff.requested
服務時間	視需要啟用。顯示離線訊息 時，非服務時間不轉真人：該則訊息不回 AI、也不發送 handoff.requested（離線訊息只推給 Web Chat 前端，非服務時間的提示請由您的系統處理）；接受留言 時仍進入排隊並發送 handoff.requested，且不啟動等待超時

以 API 設定對話平台時，接手制加不逾時對應 dispatchMode: "handover" 與 assignmentQueueTimeout: 0。

不要在自動派工下把等待超時時間設成 0。 自動派工（預設）的等待超時只接受 1～3600 秒：畫面上填 0 會提示超出範圍，透過 API 送出 0 則會被改成預設的 300 秒。300 秒後沒有 MaiAgent 成員接手，MaiAgent 就會送出 handoff.queue_timeout，讓 AI 接回對話，訪客與您的客服都不會察覺。

轉接通知訊息、排隊等待提示 等「給訪客看的提示文字」是推送給 MaiAgent 自家 Web Chat 前端的，不會經由 Webhook 送到您的系統。請在收到 handoff.requested 時，由您的系統自行向訪客顯示「正在為您轉接真人客服」等提示。

4. 開啟轉真人 Webhook

同一分頁 → 子分頁 通知 → 開啟 Webhook 通知（系統串接），填入：

• Webhook 網址：僅接受 HTTPS。

• 簽章密鑰（選填）（建議設定）：設定後每次推送帶 HMAC-SHA256 簽章，驗證方式見傳送與簽章。

Email 通知 與 通知中心公告 只在對話指派給 MaiAgent 成員時發送，與本整合無關，可關閉。

這三個通知開關由對話平台的管理者在後台自行開啟，不需要另外申請。操作畫面見使用者手冊的轉真人客服通知。

步驟一：對應訪客身分

以您系統中的使用者 ID 呼叫身分同步 API，取得該訪客在 MaiAgent 的 contactId：

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": "王小明" }'

{ "contactId": "c0ffee00-1111-2222-3333-444455556666" }

同一個 sourceId 重複呼叫會回傳同一個 contactId（冪等），請把 sourceId ↔ contactId 存在您的使用者資料中。sourceId 請使用不可猜測的值。完整說明見 聯絡人身分同步與 Token 更新。

步驟二：建立對話

每位訪客建立一個對話並長期沿用，MaiAgent 會以對話為單位維持上下文：

curl -X POST 'https://api.maiagent.ai/api/v1/conversations/' \
  -H 'Authorization: Api-Key <您的API金鑰>' \
  -H 'Content-Type: application/json' \
  -d '{ "webChat": "<Web Chat ID>", "contact": "<contactId>" }'

回應中請記下 id（對話 ID）與 inbox.id（對話平台 ID，設定 Webhook 時會用到）。回應欄位見 建立對話與訊息。

若您希望每次來訪重新開始一段對話（例如案件結案後），再建立一個新對話即可；舊對話的紀錄仍保留。

步驟三：送出訪客訊息

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 檔案上傳模式。

步驟四：接收 AI 回覆

AI 回覆建立後，MaiAgent 對您設定的 Outgoing Webhook 發出請求。以標準格式為例，您的端點會收到：

{
  "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。

若您需要在 payload 裡直接拿到自己的使用者 ID 或可下載的附件網址，使用 自訂範本 輸出 contact.source_id 與 attachment.file.url，範例見 Webhook › 自訂範本。

步驟五：AI 判定轉真人

每則訪客訊息進來時，MaiAgent 先以判定模型判斷是否需要真人。判定為「需要」時：

1. 對話狀態變為 queued、auto_reply_enabled 變為 false，這則訊息不會有 AI 回覆，後續訊息也不再由 AI 回覆。

2. MaiAgent 對您的轉真人 Webhook 網址送出 handoff.requested 事件。

事件 payload

事件的欄位表與 JSON 範例見 API 文件轉真人 Webhook 事件的「事件格式」。串接本流程時要掌握的幾點：

• 四種事件的欄位完全相同，請依 event 分流（見下方事件一覽）。

• conversation.id、contact.id 對應您在步驟一、二記下的對話與訪客。

• 以事件 id 去重、以 occurred_at 排序；payload 只含識別資訊，不含對話內容。

• assignee 是事件當下被指派的 MaiAgent 成員；handoff.requested 與由您的客服接手時恆為 null。

• 欄位命名與巢狀結構和步驟四的訊息 Webhook 一致，同一支接收端可以同時處理兩組推送。

傳送與簽章

POST、Content-Type: application/json，逾時 10 秒；非 2xx 或連線失敗會每 60 秒重試，最多 3 次。有設定簽章密鑰時，請求帶 X-MaiAgent-Signature-256: sha256=<hex>，值為以密鑰對原始請求內容計算的 HMAC-SHA256。驗證程式與可直接啟動的接收端範例見 API 文件轉真人 Webhook 事件的「簽章驗證」與接收端最小範例。

您的系統收到 handoff.requested 後

• 在您的系統建立案件、指派真人客服，並向訪客顯示轉接提示。

• 之後訪客的訊息由您的客服在您的系統內處理。可以不再送進 MaiAgent；若您仍希望 MaiAgent 保留完整紀錄，可以繼續呼叫 POST /messages/——訊息會存入對話並觸發 Incoming Webhook，但在回到 AI 之前不會產生 AI 回覆。

• 真人客服的回覆由您的系統直接送給訪客，不需要經過 MaiAgent。

步驟六：真人服務結束，回到 AI

案件結束時，呼叫回到 AI：

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 回覆。回應為更新後的對話物件。

API 金鑰所屬的成員需要有該對話平台的對話存取權限。若沒有依前置設定選擇接手制並勾選 不逾時，等待超時時間 到期時 MaiAgent 會自動回到 AI 並送出 handoff.queue_timeout，請確認這符合您的流程。非服務時間以 接受留言 進入排隊的對話不會啟動等待超時，一律要由您的系統呼叫 return-to-ai 結束。

情境 B：訪客在 MaiAgent 對話平台，真人客服在您的系統

訪客透過 MaiAgent 的對話平台與 Agent 對話，只有轉真人後的真人客服在您的客服系統回覆。訪客訊息本來就進 MaiAgent，您的系統不需要做步驟一～三；改用訊息 Webhook 把轉真人期間的訊息帶進您的系統，再以 API 把客服回覆寫回對話，讓兩邊雙向同步。

前置設定在訪客所在的對話平台上完成：啟用真人客服轉接（接手制＋不逾時）與開啟轉真人 Webhook 和情境 A 相同；訊息 Webhook 要新增 Incoming（訪客訊息）與 Outgoing（Agent 或客服回覆）兩個方向。寫回客服回覆與回到 AI 需要 API 金鑰，取得方式見快速上手。

串接流程

1. 得知轉真人開始：收到 handoff.requested 後，在您的系統以 conversation.id 開單或建立會話，並記下 contact.id。事件不含對話文字；需要轉真人前的對話內容時，以 conversation.id 呼叫 API 文件的取得訊息列表。若之後收到 handoff.assigned，代表對話被指派給 MaiAgent 後台的成員，assignee.id 是這位成員。

2. 接收訪客訊息與客服回覆：訊息 Webhook 的每筆 payload 都帶對話的目前狀態。只處理 conversation.auto_reply_enabled 為 false 的訊息，就能略過 Agent 自動回覆中的流量；以 sender.type 分辨訪客（contact）、真人客服（user）與 Agent（chatbot）。欄位定義見 Webhook › 欄位說明。

3. 把客服回覆寫回對話：以 API 金鑰呼叫 POST /api/v1/messages/outgoing/，帶 conversation 與 content，MaiAgent 會把訊息送到訪客所在的對話平台。訊息的發送者是 API 金鑰所屬的成員，這位成員需要有該對話平台的對話存取權限。欄位見 API 文件發送主動訊息。

4. 結束轉真人：客服處理完畢後呼叫 return-to-ai（呼叫方式同步驟六），Agent 重新接手。無論是您呼叫 API，還是成員在後台按「轉回 AI Agent」，您都會收到 handoff.returned_to_ai，請據此關閉您系統中的會話。

依建議的接手制＋不逾時設定，轉真人後的對話會一直是排隊中，conversation.progress_status 為 waiting_for_human；只有對話被指派給 MaiAgent 後台成員時才會變成 human_serving。判斷是否由真人處理時請看 auto_reply_enabled，不要只比對 progress_status 是否為 human_serving，否則會漏掉訪客訊息。

呼叫範例

（1）轉真人期間收到的訊息 Webhook（MaiAgent 標準格式，節錄）：auto_reply_enabled 為 false 代表由真人處理，sender.type 為 contact 代表是訪客訊息。

{
  "id": "9d2f7a10-...",
  "type": "incoming",
  "content": "我要改訂單地址",
  "created_at": "2026-09-09T02:30:00+00:00",
  "conversation": {
    "id": "6c2b7c1e-...",
    "title": "...",
    "type": "individual",
    "status": "queued",
    "progress_status": "waiting_for_human",
    "auto_reply_enabled": false,
    "assignee": null
  },
  "inbox": { "id": "0f9a3d42-...", "name": "官網客服", "channel_type": "web" },
  "contact": { "id": "a4c1f6b3-...", "name": "王小明", "email": null, "phone_number": null },
  "sender": { "id": "a4c1f6b3-...", "name": "王小明", "type": "contact" },
  "attachments": [],
  "metadata": {}
}

（2）把客服回覆寫回對話：帶 conversation 與 content 即可，訊息會以 API 金鑰所屬成員的身分送到訪客所在的對話平台。

curl -X POST "https://api.maiagent.ai/api/v1/messages/outgoing/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "6c2b7c1e-...",
    "content": "您好，地址已為您更新為台北市信義區…"
  }'

（3）三步合在一起（Python，requests）：

import requests

API = "https://api.maiagent.ai/api/v1"
HEADERS = {"Authorization": "Api-Key YOUR_API_KEY"}


def on_message_webhook(payload: dict) -> None:
    conv = payload["conversation"]
    if conv["auto_reply_enabled"]:
        return  # Agent 自動回覆中的流量不進客服系統
    if payload["sender"]["type"] == "contact":
        push_to_agent_console(conv["id"], payload["content"])  # 訪客訊息→您的客服介面


def reply(conversation_id: str, text: str) -> None:
    requests.post(f"{API}/messages/outgoing/", headers=HEADERS,
                  json={"conversation": conversation_id, "content": text}, timeout=10).raise_for_status()


def finish(conversation_id: str) -> None:
    requests.patch(f"{API}/conversations/{conversation_id}/return-to-ai/", headers=HEADERS, timeout=10).raise_for_status()

注意事項

• 透過 API 寫回的客服回覆，會再經由 Outgoing 訊息 Webhook 送出一次（sender.type 為 user）；請以訊息 id 去重，避免在您的系統重複顯示。

• handoff.assigned 在轉接給另一位成員時會再送一筆，assignee.id 為新的負責人；請以 conversation.id 更新既有會話，不要重複開單。

• 訊息 Webhook 與轉真人 Webhook 的驗證方式不同，見串接前常見問題 › 認證。

事件一覽

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），可用於對帳。

事件各自以背景任務送出，不保證到達順序，也可能因重試而重複。請以事件 id 去重、以 occurred_at 排序，並把 handoff.assigned 視為隱含已觸發。

用 API 查詢目前狀態

Webhook 之外，隨時可以查詢對話目前由誰處理：

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=<hex>。

逾時、重試與流量上限

方向	逾時	重試
您呼叫 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 後台 Agent 頁面的 Webhook 分頁查看；對話狀態與轉真人事件可用對話 API 與事件紀錄 API 查詢對帳；AI 用量在後台用量統計。轉真人 Webhook 推送失敗會進 MaiAgent 的監控告警。

整合檢查清單

• 後台：Outgoing Webhook 已設定並能收到 AI 回覆

• 後台：真人客服轉接已啟用；外部真人客服的派工模式為 接手制，並已勾選 不逾時

• 後台：轉真人 Webhook 已開啟、HTTPS 端點可達、簽章驗證通過

• 您的系統：sourceId ↔ contactId ↔ conversationId 對應已落地

• 您的系統：handoff.requested → 建案與轉接提示；handoff.returned_to_ai → 結案；handoff.queue_timeout → 告警或結案

• 您的系統：真人服務結束時呼叫 return-to-ai

• 兩個 Webhook 端點皆做冪等：轉真人事件與訊息推送都以各自的 id

• 情境 B：訊息 Webhook 已新增 Incoming 與 Outgoing 兩個方向，並以 auto_reply_enabled 判斷是否由真人處理

• 若您的網路需要來源 IP 白名單，請向對接窗口索取 MaiAgent 的出站 IP

相關頁面

• 轉真人 Webhook 事件（API 文件）：事件完整規格、簽章驗證、可直接啟動的接收端範例

• 客服轉真人設定（使用者手冊）：轉真人條件、服務時間、派工設定等後台欄位的操作說明

• Webhook：訊息推送格式、自訂範本、以 API 管理 Webhook

• 建立對話與訊息：建立對話與送出訊息的流程，欄位連到 API 文件

• 聯絡人身分同步與 Token 更新：setup-contact-credentials 完整規格

• Presigned 檔案上傳模式：附件上傳