發送訊息

使用此 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 回覆模式： blocking：等待執行完成並回傳結果（若過程過長可能中斷）。 streaming：以 SSE (Server-Sent Events) 方式串流回覆。 webhook：Agent 與人工服務的訊息將發送到 API 頁面設定的 webhook URL。
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", "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",
    "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 回覆模式下不支援人工服務。

欄位	類型	描述
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）

⚠️ webhook 回覆模式下支援人工服務。
當 Agent 已啟用人工服務功能時，請使用 webhook 回覆模式以接收人工服務人員的訊息。於「Integration-API」區塊設定 webhook URL 後，GPTBots 系統會將「Agent」與「人工服務」的回覆訊息發送到您的 webhook URL。

有關 webhook 訊息的詳細說明，請參考 Webhook 模式及人工服務。

錯誤回應

欄位	類型	描述
code	int	錯誤代碼。
message	string	錯誤詳情。

錯誤代碼

代碼	訊息
40000	無效參數
40127	開發者認證失敗
40356	對話不存在
40358	對話識別碼不符
40364	Agent 不支援圖片模式
50000	系統內部錯誤
20040	超出問題長度限制
20022	點數不足
20055	禁止使用 API，請確認 API 開關已啟用