發送訊息
發送訊息
使用此 API 可向指定的 conversation_id 發送訊息，並接收 Agent 產生的回覆。API 支援多種訊息內容類型，包括文字、圖片、音頻及文件。
請求方法
POST
Endpoint
https://api-${endpoint}.gptbots.ai/v2/conversation/message
認證
請參考 API 概覽 取得認證說明。
請求
請求範例
curl -X POST 'https://api-${endpoint}.gptbots.ai/v2/conversation/message' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"conversation_id": "686e2646cb8ee942d9a62d79",
"response_mode": "blocking",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "我已上傳了兩個圖片檔案，請進行 OCR 並回傳兩筆 JSON 記錄。"
},
{
"type": "image",
"image": [
{
"base64_content": "<complete_base64_string>",
"format": "jpeg",
"name": "TAXI1"
},
{
"url": "https://gptbots.ai/example.png",
"format": "png",
"name": "TAXI2"
}
]
},
{
"type": "audio",
"audio": [
{
"url": "https://gptbots.ai/example.mp3",
"format": "mp3",
"name": "example1 audio"
}
]
},
{
"type": "document",
"document": [
{
"base64_content": "<complete_base64_string>",
"format": "pdf",
"name": "example pdf"
}
]
}
]
}
],
"conversation_config": {
"long_term_memory": false,
"short_term_memory": false,
"knowledge": {
"data_ids": [
"58c70da0403cc812641b9356",
"59c70da0403cc812641df35a"
],
"group_ids": [
"67c70da0403cc812641b93je",
"69c70da0403cc812641df35f"
]
},
"custom_variables": {
"var_current_url": "https://gptbots.ai/example",
"var_session_id": "abcdef"
}
}
}'
curl -X POST 'https://api-${endpoint}.gptbots.ai/v2/conversation/message' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"conversation_id": "686e2646cb8ee942d9a62d79",
"response_mode": "blocking",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "我已上傳了兩個圖片檔案，請進行 OCR 並回傳兩筆 JSON 記錄。"
},
{
"type": "image",
"image": [
{
"base64_content": "<complete_base64_string>",
"format": "jpeg",
"name": "TAXI1"
},
{
"url": "https://gptbots.ai/example.png",
"format": "png",
"name": "TAXI2"
}
]
},
{
"type": "audio",
"audio": [
{
"url": "https://gptbots.ai/example.mp3",
"format": "mp3",
"name": "example1 audio"
}
]
},
{
"type": "document",
"document": [
{
"base64_content": "<complete_base64_string>",
"format": "pdf",
"name": "example pdf"
}
]
}
]
}
],
"conversation_config": {
"long_term_memory": false,
"short_term_memory": false,
"knowledge": {
"data_ids": [
"58c70da0403cc812641b9356",
"59c70da0403cc812641df35a"
],
"group_ids": [
"67c70da0403cc812641b93je",
"69c70da0403cc812641df35f"
]
},
"custom_variables": {
"var_current_url": "https://gptbots.ai/example",
"var_session_id": "abcdef"
}
}
}'
此代碼塊在浮窗中顯示
重要說明：
- 對於
image、audio和document類型的內容，可以使用 base64 編碼或 URL 連結，兩種格式皆支援。 - 開發者僅需發送最新的使用者訊息，GPTBots 會自動處理短期記錄及長期記錄。如需自訂短期記錄上下文，請參考以下範例："messages": [ { "role": "user", "content": "Hello" //自訂短期記錄 }, { "role": "assistant", "content": "Hello! How can I assist you today?" //自訂短期記錄 }, { "role": "user", "content": "Hello" //最新使用者訊息 }]
"messages": [ { "role": "user", "content": "Hello" //自訂短期記錄 }, { "role": "assistant", "content": "Hello! How can I assist you today?" //自訂短期記錄 }, { "role": "user", "content": "Hello" //最新使用者訊息 }]此代碼塊在浮窗中顯示
請求標頭
| 欄位 | 類型 | 描述 |
|---|---|---|
| Authorization | Bearer ${API Key} | 請使用 Authorization: Bearer ${API Key} 來完成認證。API 金鑰可於 API Key 頁面取得。 |
| Content-Type | application/json | 資料類型，必須為 application/json。 |
請求參數
| 欄位 | 類型 | 必填 | 描述 |
|---|---|---|---|
| conversation_id | string | 是 | 對話唯一識別碼。必須提供 conversation_id 以繼續對話。 |
| response_mode | string | 是 | Agent 回覆模式： |
| messages | JSON Array | 是 | 訊息內容，支援角色 user 與 assistant 以建立對話上下文。 |
| conversation_config | object | 否 | 允許開發者臨時調整本次對話的 Agent 功能範圍以滿足特殊需求。 |
| short_term_memory | boolean | 否 | 短期記錄開關。僅針對本次對話啟用或停用短期記錄。 |
| long_term_memory | boolean | 否 | 長期記錄開關。僅針對本次對話啟用或停用長期記錄。 |
| knowledge | object | 否 | 知識檢索範圍。僅針對本次對話自訂知識檢索範圍。若同時提供 group_ids 與 data_ids，則檢索範圍為其知識庫聯集。若兩者皆為空陣列，則不檢索知識。若省略 knowledge 參數，則使用 Agent 預設知識設定。group_ids：知識庫 ID，可能包含多份知識文件。data_ids：知識庫內的知識文件 ID。 |
| custom_variables | object | 否 | 自訂變數。允許開發者臨時調整本次對話中 Agent 的自訂變數值。 |
注意：
Agent 輸入與輸出設定頁支援不同訊息類型的識別方式。支援的檔案類型與大小各異，請依需求調整 API 提交資料。最大支援訊息格式：
- 文字訊息：string
- 音頻訊息：.mp3, .wav, .acc
- 圖片訊息：.jpg, .jpeg, .png, .gif, .webp
- 文件訊息：.pdf, .txt, .docx, .csv, .xlsx, .html, .json, .md, .tex, .ts, .xml 等
回應
回應範例
{
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Component Name",
"content": {
"text": "您好，有什麼需要我幫忙的嗎？",
"audio": [
{
"audio": "http://gptbots.ai/example.mp3",
"transcript": "轉錄的音頻內容"
}
]
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 0
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 0
}
},
"credits": {
"total_credits": 0.0,
"text_input_credits": 0.0,
"text_output_credits": 0.0,
"audio_input_credits": 0.0,
"audio_output_credits": 0.0
}
}
}
{
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Component Name",
"content": {
"text": "您好，有什麼需要我幫忙的嗎？",
"audio": [
{
"audio": "http://gptbots.ai/example.mp3",
"transcript": "轉錄的音頻內容"
}
]
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 0
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 0
}
},
"credits": {
"total_credits": 0.0,
"text_input_credits": 0.0,
"text_output_credits": 0.0,
"audio_input_credits": 0.0,
"audio_output_credits": 0.0
}
}
}
此代碼塊在浮窗中顯示
成功回應（blocking）
⚠️ blocking 回覆模式下不支援人工服務。
| 欄位 | 類型 | 描述 |
|---|---|---|
| user_id | string | 開發者綁定的使用者 ID，未綁定使用者時為 null。 |
| anonymous_id | string | 匿名使用者（裝置）ID。 |
| conversation_id | string | 對話識別碼，傳入 conversation_id 以繼續對話。 |
| message_id | string | 對話中訊息的唯一識別碼。 |
| create_time | long | 此回覆訊息產生的時間戳。 |
| output | JSON Array | Agent 回覆內容。 |
| from_component_branch | string | FlowAgent 分支。 |
| from_component_name | string | FlowAgent 上游元件名稱。 |
| content | object | AI Agent 回覆的訊息內容，目前包含兩種類型：text 及 audio。 |
| usage | object | 資源消耗詳細資訊。 |
| tokens | JSON Array | 本次對話中 Agent 消耗的總 token 數。 |
| total_tokens | integer | 本次對話輸入與輸出消耗的總 token 數。 |
| prompt_tokens | integer | 本次對話輸入消耗的總 token 數。 |
| completion_tokens | integer | 本次對話輸出消耗的總 token 數。 |
| prompt_tokens_details | object | 輸入 token 消耗詳細分解。 |
| completion_tokens_details | object | 輸出 token 消耗詳細分解。 |
| credits | object | 本次對話中 Agent 消耗的總點數。 |
| text_input_credits | double | 本次對話輸入文字訊息消耗的點數。 |
| text_output_credits | double | 本次對話輸出文字訊息消耗的點數。 |
| audio_input_credits | double | 本次對話輸入音頻訊息消耗的點數。 |
| audio_output_credits | double | 本次對話輸出音頻訊息消耗的點數。 |
成功回應（streaming）
⚠️ streaming 回覆模式下不支援人工服務。
| 欄位 | 類型 | 描述 |
|---|---|---|
| code | int | 訊息型態代碼：3-文字，10-FlowAgent 輸出，0-結束，4-使用數據，39-音頻訊息。 |
| message | string | 訊息型態：文字、FlowOutput、結束。 |
| data | object | 回覆內容。 |
- 文字訊息串流範例：
{"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}}
{"code":3,"message":"Text","data":"How "}
{"code":3,"message":"Text","data":"can "}
{"code":3,"message":"Text","data":"I "}
{"code":3,"message":"Text","data":"help "}
{"code":3,"message":"Text","data":"you?"}
{"code":0,"message":"End","data":null}
{"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}}
{"code":3,"message":"Text","data":"How "}
{"code":3,"message":"Text","data":"can "}
{"code":3,"message":"Text","data":"I "}
{"code":3,"message":"Text","data":"help "}
{"code":3,"message":"Text","data":"you?"}
{"code":0,"message":"End","data":null}
此代碼塊在浮窗中顯示
- 音頻訊息串流範例：
{"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"Hello"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":0,"message":"End","data":null}
{"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"Hello"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":0,"message":"End","data":null}
此代碼塊在浮窗中顯示
成功回應（webhook）
開發者在「整合-API」完成設定 webhook 位址後，GPTBots 系統將向 Webhook 位址傳送「Agent 回覆」與「人工客服回覆」的訊息。
有關 webhook 訊息的詳細說明，請參考 Webhook 訊息接收 及 人工服務。
⚠️ API 模式下，如果啟用人工服務，則必須使用 webhook 回應模式才能接收到人工客服回覆的訊息
錯誤回應
| 欄位 | 類型 | 描述 |
|---|---|---|
| code | int | 錯誤代碼。 |
| message | string | 錯誤詳情。 |
失敗範例
{
"code": 40000,
"message": "無效參數",
"errors": [
{
"error_code": 40000,
"error_message": "Message user role type must have file or content."
}
],
"data": {
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Component Name",
"content": {
"text": "已根據可識別的內容為你解答……",
"audio": null
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 0
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 0
}
},
"credits": {
"total_credits": 0,
"text_input_credits": 0,
"text_output_credits": 0,
"audio_input_credits": 0,
"audio_output_credits": 0
}
}
}
}
{
"code": 40000,
"message": "無效參數",
"errors": [
{
"error_code": 40000,
"error_message": "Message user role type must have file or content."
}
],
"data": {
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Component Name",
"content": {
"text": "已根據可識別的內容為你解答……",
"audio": null
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 0
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 0
}
},
"credits": {
"total_credits": 0,
"text_input_credits": 0,
"text_output_credits": 0,
"audio_input_credits": 0,
"audio_output_credits": 0
}
}
}
}
此代碼塊在浮窗中顯示
錯誤代碼
| 代碼 | 訊息 |
|---|---|
| 40000 | 無效參數 |
| 40127 | 開發者認證失敗 |
| 40356 | 對話不存在 |
| 40358 | 對話識別碼不符 |
| 40364 | Agent 不支援圖片模式 |
| 50000 | 系統內部錯誤 |
| 20040 | 超出問題長度限制 |
| 20022 | 點數不足 |
| 20055 | 禁止使用 API，請確認 API 開關已啟用 |