轉接設定

真人轉接讓 AI Agent 偵測到需要真人服務的情況時，自動將對話交給真人操作人員。轉接由 AI 驅動：AI 持續依可設定的指引評估對話，並在適當時機觸發轉接，不需手動介入。

自動轉接的運作方式：

1. 對話期間，AI 依一般指引（例如使用者不滿、缺乏知識）與您定義的自訂指引評估每則訊息
2. 當某項指引觸發時，AI 顯示確認訊息，詢問訪客是否希望與真人交談
3. 若訪客確認，對話便轉交真人操作人員，並可選擇附上 AI 產生的目前對話摘要
4. 若已設定工作時間，而請求發生在時間之外，則改為顯示自訂訊息

其他轉接方式：

• 關鍵字觸發：訪客可輸入特定片語（例如「與真人交談」、「客服」）直接要求轉接
• 從控制台手動轉接：操作人員可在收件匣變更對話負責人，接手任何對話

依主題分派讓 AI 根據隊友的路由說明，將轉接指派給其中一位。每個設定檔屬於一位使用者，與洞察中的主題分類不同。可透過 PUT 請求的 routing_profiles 設定。對話指派與電子郵件通知收件人是獨立設定。

選用範例檢查

• 預覽 API Action 請求。以合成範例值呈現提供的請求範本，但不傳送。請省略憑證標頭。

• 驗證測試資料集。依支援格式檢查提供的小型資料集，不會執行 AI Agent。

取得轉接設定

權限範圍：read_all

GET https://app.quickchat.ai/v1/api/human_handoff/configuration

Shell

curl https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

回應 200 OK

回應包含數個巢狀物件：

settings：核心轉接設定：

欄位	說明
is_active 布林值	是否啟用真人轉接
keywords 字串陣列	觸發轉接的關鍵字，例如 ["speak to human", "agent"]
ai_summary_active 布林值	轉接時向真人操作人員傳送 AI 產生的對話摘要
topic_based_routing_active 布林值	是否啟用依主題分派至特定操作人員（唯讀，透過路由設定檔設定）
question_message 字串	向訪客詢問是否希望轉接真人的訊息
confirmation_message 字串	訪客確認轉接後顯示的訊息（最多 500 個字元）
confirmation_outside_working_hours_message 字串	非工作時間要求轉接時顯示的訊息（最多 500 個字元）
working_hours_active 布林值	限制僅在工作時間轉接
timezone 字串	工作時間的時區，例如 "Europe/London"
send_email_notification 布林值	轉接時傳送電子郵件通知給操作人員
emails 字串陣列	要通知的電子郵件地址

availability：工作時間表（時段陣列）：

欄位	說明
id 整數	可用時段 ID
day_span 字串	星期或日期範圍，例如 "monday"、"monday-friday"
start_time 字串	"HH:MM" 格式的開始時間
end_time 字串	"HH:MM" 格式的結束時間

generic_guidelines：預設轉接觸發規則（陣列）：

欄位	說明
name 字串	指引類型："user_frustration"、"customer_support_suggestion"、"lack_of_knowledge"、"irrelevant_advice"、"media_message"
description 字串	此指引觸發時機的說明
is_active 布林值	是否啟用此指引

custom_guidelines：使用者定義的轉接觸發規則（陣列）：

欄位	說明
id 整數	指引 ID
name 字串	自訂指引名稱（最多 100 個字元）
description 字串	此指引應觸發轉接的時機（最多 2000 個字元）
is_active 布林值	是否啟用此指引

routing_profiles：依主題分派根據對話內容，將轉接導向合適的操作人員。

AI 發起轉接時，可從啟用中的路由設定檔選擇隊友。若選擇有效，對話便指派給該使用者，否則保持未指派。其他轉接觸發方式也可能讓對話保持未指派。電子郵件通知獨立使用 settings.send_email_notification 與 settings.emails，不受路由選擇影響。

範例： 給財務隊友設定「帳單與發票問題」的路由說明，給工程師設定「技術支援」。遇到發票問題時，AI 可將轉接指派給財務隊友。已設定的電子郵件收件人清單不會因指派而改變。

在 Actions 與 MCPs > 真人轉接 > 編輯 Action > 依主題分派，或透過 PUT 請求設定路由設定檔。

欄位	說明
user_id 整數	隊友的使用者 ID；該使用者必須有此 AI Agent 的存取權
routing_description 字串	此隊友應處理的對話（最多 150 個字元，啟用時不可為空）
is_active 布林值	是否啟用此路由設定檔
email、first_name、last_name 字串	GET 傳回的使用者資料，PUT 不需提供

更新轉接設定

權限範圍：write_all

PUT https://app.quickchat.ai/v1/api/human_handoff/configuration

警告

PUT 會以原子操作取代整份轉接設定。請包含 settings、availability、generic_guidelines 與 custom_guidelines。若要保留路由，請包含 routing_profiles；省略時預設為空清單，會移除既有設定檔。若要進行局部修改，先 GET 目前設定，修改所需欄位，再將完整物件 PUT 回去。每個路由設定檔使用 user_id、routing_description 與 is_active。

Shell

# First, fetch the current configuration
CONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>')

# Modify and PUT back (example: enable handoff)
echo "$CONFIG" | jq '.settings.is_active = true' | \
curl -X PUT https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @-

Python

import requests

headers = {"Authorization": "Bearer <API_TOKEN>"}

# Fetch current configuration
config = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
).json()

# Modify and PUT back
config["settings"]["is_active"] = True

response = requests.put(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
    json=config,
)
data = response.json()

回應 200 OK：傳回更新後的轉接設定。

---