訊息傳送功能

向指定的對話 ID 傳送訊息並取得代理回應。支援以文字和/或圖片形式提交訊息內容。

請求方法

POST

請求 URL

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

請求認證

請參閱概覽以了解認證的詳細資訊。

請求

請求範例

curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/conversation/message' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "text": "HI！", "conversation_id": "xxxxxx", "response_mode": "streaming", "short_term_memory": true, "long_term_memory": false, "files":[ { "url": "https://res.srcgptbots.com/ailab/botchat/file/38f13465ad5246190b759b3289ecba51.jpg", "name": "something.jpg", "width": 200, "height": 200 }, { "base64_content": "Your_file_base64_content", "name": "something.pdf" } ], "knowledge": { "data_ids": [ "48c70da0403cc812641b934f", "48c70da0403cc812641df35k" ] } }'

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/conversation/message' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
      "text": "HI！",
      "conversation_id": "xxxxxx",
      "response_mode": "streaming",
      "short_term_memory": true,
      "long_term_memory": false,
      "files":[
          {
            "url": "https://res.srcgptbots.com/ailab/botchat/file/38f13465ad5246190b759b3289ecba51.jpg",
            "name": "something.jpg",
            "width": 200,
            "height": 200
          },
          {
            "base64_content": "Your_file_base64_content", 
            "name": "something.pdf"
          }
      ],
      "knowledge": {
        "data_ids": [
          "48c70da0403cc812641b934f",
          "48c70da0403cc812641df35k"
        ]
      }
}'

此代碼塊在浮窗中顯示

範例說明：本例同時提交文字訊息與兩個檔案（圖片與 PDF），並指定對話 ID 及回應模式。

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

請求主體

欄位	類型	必填	描述
text	string	是	必須輸入文字或檔案其中之一。使用者的文字訊息，內容長度不得超過代理設定的 token 長度上限。
files	JSON Array	否	text 與 files 至少需擇一輸入。files 用於提交圖片、音訊或文件型資料給代理。支援「系統檔案識別」與「LLM 檔案識別」兩種模式。不同模式支援的檔案類型不同。支援網路路徑檔案提交，最多可上傳 9 個檔案。文件 ≤20MB，圖片 ≤10MB，音訊 ≤5MB。 LLM 檔案識別・支援檔案類型依各 LLM 能力而異。若為流程代理，取所有 LLM 支援檔案類型的交集。系統檔案識別・GPTBots 系統自動識別上傳檔案並轉換為文字。・文件類型：.pdf, .txt, .docx, .csv, .xlsx, .html, .c, .cpp, .java, .json, .md, .php, .pptx, .py, .rb, .tex, .css, .js, .ts, .xml ・圖片類型：.jpg, .jpeg, .png, .gif, .webp ・音訊類型：.mp3, .wav, .acc 檔案提交規範・base64_content（string，檔案流，與 url 擇一）・url（string，檔案網址，與檔案流擇一）・name（string，檔案名稱）・width（int，圖片寬度，圖片類型必填）・height（int，圖片高度，圖片類型必填）
conversation_id	string	是	對話 ID，傳入以繼續先前對話。
response_mode	string	是	blocking：・同步模式（blocking）：等待回應完成後才返回結果（長時間請求可能被中斷）・串流模式（streaming）：以 SSE（Server-Sent Events）方式串流回應・webhook：代理與人工客服訊息將發送至 API 頁面設定的 webhook 位址
short_term_memory	boolean	否	本次訊息是否帶入對話的短期記憶作為上下文？若未填寫，將依代理記憶設定為準。
long_term_memory	boolean	否	本次訊息是否帶入對話的長期記憶作為上下文？若未填寫，將依代理記憶設定為準。
knowledge	object	否	自訂本次訊息的知識檢索範圍。若未帶此欄位，則採用代理預設知識設定。
data_ids	array	否	`data_ids` 為知識文件 ID 陣列。若為空陣列（如 `"data_ids": []`），表示不檢索任何知識文件。若有值，則僅檢索指定的知識文件 ID 範圍。

回應

回應範例

{ "message_id": "65a4ccfC7ce58e728d5897e0", "message_type": "ANSWER", "text": "Hi, is there anything I can help you?", "flow_output": [ { "content": "Hello", "branch": "1", "from_component_name": "User Input" } ], "create_time": 1679587005, "conversation_id": "657303a8a764d47094874bbe" }

                      
                      {
  "message_id": "65a4ccfC7ce58e728d5897e0",
  "message_type": "ANSWER",
  "text": "Hi, is there anything I can help you?",
  "flow_output": [
    {
      "content": "Hello",
      "branch": "1", 
      "from_component_name": "User Input"
    }
  ],
  "create_time": 1679587005,
  "conversation_id": "657303a8a764d47094874bbe"
}

此代碼塊在浮窗中顯示

範例說明：代理回覆訊息內容，包含訊息 ID、回覆文字、流程代理輸出內容及時間戳等資訊。

成功回應（同步模式）

欄位	類型	描述
message_id	string	訊息唯一 ID。
message_type	string	訊息類型，值：ANSWER、QUESTION。
text	string	回覆文字內容。
flow_output	JSON Array	流程代理回覆內容。
content	string	流程代理元件回覆文字。
branch	string	流程代理分支。
from_component_name	string	流程代理上游元件名稱。
create_time	long	回覆訊息建立的時間戳。
conversation_id	string	對話 ID。

成功回應（串流模式）

欄位	類型	描述
code	int	訊息類型代碼，3-文字，10-流程輸出，0-結束。
message	string	訊息類型，值：Text、FlowOutput、End。
data	object	回覆內容。

串流數據會分多個區塊返回：

{"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}} {"code":3,"message":"Text","data":"I"} {"code":3,"message":"Text","data":"can"} {"code":3,"message":"Text","data":"help"} {"code":3,"message":"Text","data":"you"} {"code":3,"message":"Text","data":"?"} {"code":10,"message":"FlowOutput","data":[{"content":"Hello","branch":null,"from_component_name":"User Input"}]} {"code":0,"message":"End","data":null}

                      
                      {"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}}
{"code":3,"message":"Text","data":"I"}
{"code":3,"message":"Text","data":"can"}  
{"code":3,"message":"Text","data":"help"}
{"code":3,"message":"Text","data":"you"}
{"code":3,"message":"Text","data":"?"}
{"code":10,"message":"FlowOutput","data":[{"content":"Hello","branch":null,"from_component_name":"User Input"}]}
{"code":0,"message":"End","data":null}

此代碼塊在浮窗中顯示

註：串流模式下，訊息內容將分段即時傳送，適合即時互動場景。

成功回應（webhook）

當開發者在 API 頁面設定了 webhook 位址後，成功回應時，GPTBots 系統會將代理與人工客服的訊息推送至該 webhook。常見應用場景如：自動客服系統、與外部平台整合等。詳細訊息格式請參閱Webhook 模式。

失敗回應

欄位	類型	描述
code	int	錯誤代碼。
message	string	錯誤信息。

錯誤代碼

代碼	信息
40000	無效參數
40127	開發者認證失敗
40356	對話不存在
50000	內部伺服器錯誤
40364	此代理未使用支援圖片模式的 LLM
20059	代理已刪除
20040	超出提問限制
40358	conversation_id 與代理或用戶不符
20022	餘額不足

錯誤處理建議：遇到錯誤時，請根據錯誤代碼檢查請求參數、認證資訊、代理狀態及餘額等，並參考API 常見問題快速排查解決。