人工服務

當開發者選擇 Webhook（網路回呼）作為人工服務接入方式 時，需先於伺服器環境中建置 Webhook 服務。開發者需依據規範提供以下三種介面，以接收人工服務請求、用戶訊息及人工客服回覆訊息。同時，GPTBots 也提供兩種介面，供接收客服回覆訊息及對話關閉指令。

重要注意事項：

開發者必須確保 Webhook 服務運作正常，因其直接影響人工支援服務運作狀態。
- 若啟用人工支援後顯示「忙碌」，則表示開發者的 Webhook 服務異常。
- 若啟用人工支援後顯示「連接中」，則表示開發者的 Webhook 服務 正常運行。
成功啟用人工支援服務請求後：
- 開發者需呼叫 回覆用戶訊息 介面 (https://api.gptbots.ai/v1/human/message/receive)，至少回覆用戶一則訊息以建立對話連線。
- 若開發者未於設定的 等待逾時 時間內（預設 60 秒）回覆用戶訊息，人工支援對話將自動終止。

接收人工服務對話請求通知

當終端用戶發起人工服務請求時，GPTBots 會將該請求轉發至開發者的 Webhook 服務。介面服務回應狀態碼為 200，表示成功建立人工服務對話。

請求方法

POST

端點

https://your_domain/conversation/establish

請求範例

curl -X POST 'https://YOUR_DOMAIN/human/service/conversation/establish' \ -H 'Content-Type: application/json' \ -d '{ "body": [ { "text": "human service", "message_type": "QUESTION" }, { "text": "", "message_type": "ANSWER" } ], "timestamp": 1742265090895, "email": "bob@gmail.com", "conversation_id": "67d8db020fa31d1ef64f53dg", "bot_id": "665d88b03ce2b13cf2d573454", "user_info": { "phone": null, "email": "bob@gmail.com", "user_id": "KDslas", "anonymous_id": "652face5184b30540a6ea7fe" } }'

                      
                      curl -X POST 'https://YOUR_DOMAIN/human/service/conversation/establish' \
-H 'Content-Type: application/json' \
-d '{
  "body": [
    {
      "text": "human service",
      "message_type": "QUESTION"
    },
    {
      "text": "",
      "message_type": "ANSWER"
    }
  ],
  "timestamp": 1742265090895,
  "email": "bob@gmail.com",
  "conversation_id": "67d8db020fa31d1ef64f53dg",
  "bot_id": "665d88b03ce2b13cf2d573454",
  "user_info": {
    "phone": null,
    "email": "bob@gmail.com",
    "user_id": "KDslas",
    "anonymous_id": "652face5184b30540a6ea7fe"
  }
}'

此代碼塊在浮窗中顯示

注意：此請求主體中的 conversation_id 僅用於標識人工服務對話場景的唯一 ID，與建立對話 ID 中的智能代理（Agent）對話場景生成的唯一 ID 不同。

請求參數

參數	類型	描述
conversation_id	string	人工客服場景的對話 ID（與智能代理對話 ID 不同），需於客服回覆介面中傳遞至 GPTBots
timestamp	long	時間戳
email	string	用戶電子郵件，部分人工服務系統需電子郵件以正常提供服務
bot_id	string	智能代理（Agent）ID
body	list<Object>	訊息主體
body.message_type	string	訊息類型，QUESTION/ANSWER
body.text	string	用戶向人工客服發起的問題及上下文
user_info	object	用戶資訊
user_info.phone	string	用戶電話號碼，目前僅於 WhatsApp 切換至人工客服時可用
user_info.email	string	用戶電子郵件，當用戶輸入其電子郵件時可用
user_info.user_id	string	用戶 ID，企業開發者自訂的用戶唯一標識，針對特定匿名 ID 設定
user_info.anonymous_id	string	匿名 ID，當用戶於非 API 渠道平台與智能代理互動時，系統依據渠道平台自動生成

email 欄位注意事項：

透過 iframe/Share/Bubble Widget 發起人工服務時，需填寫用戶電子郵件。開發者亦可自訂用戶 email 以免用戶輸入。

透過 WhatsApp/Telegram/即時聊天等第三方平台請求人工服務時，預設 email 為 support@gptbots.ai。即時聊天可自訂 email。

透過 API 請求人工服務時，email 欄位可為空，預設 email 為 support@gptbots.ai。

回應

參數	類型	描述
code	int	回應碼
message	string	詳細資訊

聊天介面

使用已建立的 conversation_id，將用戶訊息傳送至人工客服。

請求方法

POST

端點

https://your_domain/chat

請求範例

{ "conversation_id": "conv_xxx", "message_id": "msg_abc124", "create_time": 1750000005000, "agent_id": "bot_xxx", "body": "這是我的訂單截圖", "timestamp": 1750000005200, "files": [ { "content_type": "Image", "url": "https://files.gptbots.ai/xxx/order.png", "name": "order.png", "format": "png" } ] }

                      
                      {
  "conversation_id": "conv_xxx",
  "message_id": "msg_abc124",
  "create_time": 1750000005000,
  "agent_id": "bot_xxx",
  "body": "這是我的訂單截圖",
  "timestamp": 1750000005200,
  "files": [
    {
      "content_type": "Image",
      "url": "https://files.gptbots.ai/xxx/order.png",
      "name": "order.png",
      "format": "png"
    }
  ]
}

此代碼塊在浮窗中顯示

請求參數

參數	類型	描述
conversation_id	string	對話 ID，需於客服回覆介面傳遞至 GPTBots
timestamp	long	時間戳
body	string	用戶訊息
message_id	string	使用者該則訊息的 ID
create_time	long	使用者該則訊息的建立時間（毫秒）
agent_id	string	智慧體（Agent/Bot）ID
files	array	使用者隨訊息上傳的附件清單；無附件時不傳或為空
content_type	string	內容類型列舉：`Image` / `Audio` / `Video` / `Document` / `File` / `Text` 等
url	string	附件可下載位址（GPTBots 端可存取，開發者需自行下載/轉存）
name	string	檔名（含副檔名），與「取得對話詳情」API 一致
format	string	檔案格式/副檔名，與「取得對話詳情」API 一致

回應

參數	類型	描述
code	int	回應碼
message	string	詳細資訊

關閉對話介面

當用戶對話逾時或智能代理用戶主動關閉對話時，調用此介面關閉對話。

請求方法

POST

端點

https://your_domain/conversation/close

請求標頭

欄位	類型	描述
Authorization	Bearer ${token}	使用 Authorization: Bearer ${token} 進行身份驗證，從 API 金鑰頁面取得 token。
Content-Type	application/json	資料類型，設為 application/json。

請求參數

參數	類型	描述
conversation_id	string	對話 ID，需於客服回覆介面傳遞至 GPTBots
timestamp	long	時間戳
type	string	關閉類型，TIMEOUT（逾時關閉）/ USER_CLOSED（用戶主動關閉）

回應

參數	類型	描述
code	int	回應碼
message	string	詳細資訊

回覆用戶訊息

當開發者選擇 webhook 作為人工服務整合方式時，GPTBots 提供回覆用戶訊息介面，讓人工客服可將訊息內容回傳給用戶。

請求方法

POST

端點

https://api-${endpoint}.gptbots.ai/v1/human/message/receive

請求標頭

欄位	類型	描述
Authorization	Bearer ${token}	使用 Authorization: Bearer ${token} 進行身份驗證，從 API 金鑰頁面取得 token。
Content-Type	application/json	資料類型，設為 application/json。

請求範例

{ "conversation_id": "conv_xxx", "timestamp": 1750000000000, "body": "這是您要的發票", "files": [ { "content_type": "Document", "url": "https://your-cdn.com/files/invoice.pdf", "name": "invoice.pdf", "format": "pdf" }, { "content_type": "Image", "url": "https://your-cdn.com/files/screenshot.png", "name": "screenshot.png", "format": "png" } ] }

                      
                      {
  "conversation_id": "conv_xxx",
  "timestamp": 1750000000000,
  "body": "這是您要的發票",
  "files": [
    { "content_type": "Document", "url": "https://your-cdn.com/files/invoice.pdf", "name": "invoice.pdf", "format": "pdf" },
    { "content_type": "Image", "url": "https://your-cdn.com/files/screenshot.png", "name": "screenshot.png", "format": "png" }
  ]
}

此代碼塊在浮窗中顯示

請求參數

參數	類型	描述	必填
conversation_id	string	對話 ID，於對話建立及聊天介面傳遞，直接帶入即可	true
timestamp	long	時間戳	true
body	string	人工客服回覆內容	true
files	array	使用者隨訊息上傳的附件清單；無附件時不傳或為空
content_type	string	內容類型列舉：`Image` / `Audio` / `Video` / `Document` / `File` / `Text` 等
url	string	附件可下載位址（GPTBots 端可存取，開發者需自行下載/轉存）
name	string	檔名（含副檔名），與「取得對話詳情」API 一致
format	string	檔案格式/副檔名，與「取得對話詳情」API 一致

回應

參數	類型	描述
code	int	回應碼
message	string	詳細資訊

人工客服主動關閉對話

當開發者選擇 webhook 作為人工服務接入方式時，GPTBots 所提供的人工客服可於需要時主動關閉對話。關閉後，除非用戶再次發起人工客服對話，否則不會再收到客服訊息。

請求方法

POST

端點

https://api-${endpoint}.gptbots.ai/v1/human/close

請求標頭

欄位	類型	描述
Authorization	Bearer ${API Key}	使用 Authorization: Bearer ${API Key} 進行身份驗證，從 API 金鑰頁面取得 API Key。
Content-Type	application/json	資料類型，設為 application/json。

請求參數

參數	類型	描述
conversation_id	string	對話 ID，需於客服回覆介面傳遞至 GPTBots
timestamp	long	時間戳

回應

參數	類型	描述	必填
conversation_id	string	對話 ID，於對話建立及聊天介面傳遞，直接帶入即可	true
timestamp	long	時間戳	true

GPTBots 服務狀態偵測

GPTBots 提供一個用於偵測自身人工服務的健康監測介面，開發者可呼叫該介面探測 GPTBots 人工服務是否正常可用。介面回傳 HTTP 狀態碼 200 且回應體為服務正常的英文標識（如 service is normal）則代表 GPTBots 人工服務正常可用。該介面無需鑑權、回傳明文。

請求方式

GET

呼叫位址

https://api.gptbots.ai/v1/human/health

請求範例

curl -X GET 'https://api.gptbots.ai/v1/human/health'

                      
                      curl -X GET 'https://api.gptbots.ai/v1/human/health'

此代碼塊在浮窗中顯示

回應

GPTBots 服務正常可用時，回傳 HTTP 狀態碼 200，且回應體回傳服務正常的英文標識。

service is normal

                      
                      service is normal

此代碼塊在浮窗中顯示

可用性判斷建議

呼叫方僅需以 HTTP 狀態碼作為判據：

情況	判定
回傳 `200` 且回應體為 `service is normal`	GPTBots 服務正常可用
回傳非 `200`（如 5xx）/ 請求逾時 / 連線失敗	GPTBots 服務不可用

建議設定合理的請求逾時（如 3~5 秒），並以固定頻率輪詢探測（QPM:3）；該介面免鑑權，呼叫時無需攜帶 API Key。