logo
开发者文档
概述用户指南API Reference最佳实践更新日志
搜索
API Reference / 对话 API / 发送消息
发送消息
最新更新：3 个月前

发送消息

通过本 API 可以向指定的 conversation_id 发送消息（message），并获取 Agent 生成的响应信息。API 支持提交文本、图片、音频和文档等作为消息内容 。

请求方式

POST

调用地址

https://api.gptbots.ai/v2/conversation/message

调用验证

详情参见 API 概述的鉴权方式说明。

请求

请求示例

curl -X POST https://api.gptbots.ai/v2/conversation/message \ --header 'Authorization: Bearer app-example_key_1234567890' \ --header 'Content-Type: application/json' \ --data '{ "conversation_id": "67b590ca27008b39c60f30ef", "response_mode": "blocking", "messages": [ { "role": "user", "content": "Hello" }, { "role": "assistant", "content": "Hello! How can I assist you today?" }, { "role": "user", "content": [ { "type": "text", "text": "What is in this image?" }, { "type": "audio", "audio": { "url": "https://gptbots.ai/example.mp3", "name": "example audio", "format": "mp3" } }, { "type": "image", "image": { "url": "https://gptbots.ai/example.png", "format": "png", "name": "example image" } }, { "type": "document", "document": { "base64_content": "Your_file_base64_content", "format": "pdf", "name": "example pdf" } } ] } ], "conversation_config": { "long_term_memory": false, "short_term_memory": false, "knowledge": { "data_ids": [ "58c70da0403cc812641b9356", "59c70da0403cc812641df35k" ], "group_ids": [ "67c70da0403cc812641b93je", "69c70da0403cc812641df35g" ] } } }'
                      
                      curl -X POST https://api.gptbots.ai/v2/conversation/message \ 
--header 'Authorization: Bearer app-example_key_1234567890' \
--header 'Content-Type: application/json' \
--data '{
    "conversation_id": "67b590ca27008b39c60f30ef",
    "response_mode": "blocking",
    "messages": [
        {
            "role": "user",
            "content": "Hello"
        },
        {
            "role": "assistant",
            "content": "Hello! How can I assist you today?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is in this image?"
                },
                {
                    "type": "audio",
                    "audio": {
                        "url": "https://gptbots.ai/example.mp3",
                        "name": "example audio",
                        "format": "mp3"
                    }
                },
                {
                    "type": "image",
                    "image": {
                        "url": "https://gptbots.ai/example.png",
                        "format": "png",
                        "name": "example image"
                    }
                },
                {
                    "type": "document",
                    "document": {
                        "base64_content": "Your_file_base64_content",
                        "format": "pdf",
                        "name": "example pdf"
                    }
                }
            ]
        }
    ],
    "conversation_config": {
        "long_term_memory": false,
        "short_term_memory": false,
        "knowledge": {
            "data_ids": [
                "58c70da0403cc812641b9356",
                "59c70da0403cc812641df35k"
            ],
            "group_ids": [
                "67c70da0403cc812641b93je",
                "69c70da0403cc812641df35g"
            ]
        }
    }
}'
此代码块在浮窗中显示

请求头

字段 类型 描述
Authorization Bearer ${token} 使用 Authorization: Bearer ${token}进行调用验证，请在 API 密钥页面获取密钥作为 token。
Content-Type application/json 数据类型，取值为 application/json。

请求体

字段 类型 必填 描述
conversation_id string 是 对话唯一标识符，必须传入需要继续对话的 conversation_id。
response_mode string 是 AI Agent 回复消息的响应和传递方式。
  • blocking：阻塞型，等待执行完毕后返回结果。（请求若流程较长可能会被中断）。
  • streaming：流式返回，基于 SSE（Server-Sent Events）实现流式返回。
  • webhook：Agent 和 人工客服的消息都会发送到 API 页面所配置的 webhook 地址。
    		•
    messages JSON Array 是 对话消息内容，支持 user 和 assistant 2 个角色来构造对话上下文。
  • user message：必须存在至少 1 条，最新的 user message 应放在最后。
  • assistant message:支持开发者自行构造 assistant message 作为上下文
    		•
    conversation_config object 否 支持开发者在本次对话中临时调整 Agent 的功能范围，以应对特殊场景需要。
  • short_term_memory：短记忆开关，支持开启和或关闭短记忆，仅本次对话生效。
  • long_term_memory：长记忆开关，支持开启和或关闭长记忆，仅本次对话生效。
  • knowledge：知识检索范围，支持自定义知识检索范围，仅本次对话生效。group_ids和data_ids，两者同时有值时，在其并集知识范围内进行检索，两者均为空数组时则视为不检索任何知识；当未携带knowledge参数时以 Agent 默认配置的知识范围进行检索。
  • group_ids:知识库 ID，可能包含多个知识文档。
  • data_ids:知识库中的知识文档 ID
    		•

    注意：

    Agent 输入和输出配置页面支持针对不同类型的消息选择不同的识别方案，所支持的文件类型和文件大小也各不相同，请根据实际情况调整 API 提交的数据。消息类型最大支持的格式如下：

    • Text消息：string
    • Audio消息：.mp3,.wav,.acc
    • Image消息：.jpg,.jpeg,.png,.gif,.webp
    • Document消息：.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": "组件名称", "content": { "text": "Hi, is there anything I can help you?", "audio": [ { "audio": "http://gptbots.ai/example.mp3", "transcript": "音频所转录的文字内容" } ] } } ], "usage": { "tokens": { "total_tokens": 29, //prompt + completion "prompt_tokens": 19, //prompt "prompt_tokens_details": { "audio_tokens": 0, "text_tokens":0 }, "completion_tokens": 10, //completion "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "text_tokens": 0 } }, "credits": { "total_credits":0.0, //prompt + completion "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": "组件名称",
            "content": {
                "text": "Hi, is there anything I can help you?",
                "audio": [
                    {
                        "audio": "http://gptbots.ai/example.mp3",
                        "transcript": "音频所转录的文字内容"
                    }
                ]
            }
        }
    ],
    "usage": {
        "tokens": {
           "total_tokens": 29,  //prompt + completion
            "prompt_tokens": 19, //prompt
            "prompt_tokens_details": {  
                "audio_tokens": 0,
                "text_tokens":0
            },
            "completion_tokens": 10, //completion
            "completion_tokens_details": {
                "reasoning_tokens": 0,
                "audio_tokens": 0,
                "text_tokens": 0
            }
        },
        "credits": {
            "total_credits":0.0,  //prompt + completion
            "text_input_credits": 0.0,
            "text_output_credits": 0.0,
            "audio_input_credits": 0.0,
            "audio_output_credits": 0.0
        }
    }
}
    此代码块在浮窗中显示

    成功响应（阻塞）

    ⚠️ blocking响应模式下，人工接管服务不可用。

    字段 类型 描述
    conversation_id string 是
    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 2 个类型的消息。
    usage object 使用消耗。
    tokens JSON Array 本次对话该 Agent 所消耗的总 tokens。
    total_tokens integer 本次对话 input + output 所消耗的总 tokens。
    prompt_tokens integer 本次对话 input 所消耗的总 tokens。
    completion_tokens integer 本次对话 output 所消耗的总 tokens。
    prompt_tokens_details object 本次对话 input Token 消耗明细。
    completion_tokens_details object 本次对话 output Token 消耗明细。
    credits object 本次对话该 Agent 所消耗的总积分。。
    text_input_credits double 本次对话 input text message 所消耗的积分。
    text_output_credits double 本次对话 output text message 所消耗的积分。
    audio_input_credits double 本次对话 input audio message 所消耗的积分。
    audio_output_credits double 本次对话 input audio message 所消耗的积分。

    成功响应（流式）

    ⚠️ streaming响应模式下，人工接管服务不可用。

    字段 类型 描述
    code int 消息的类型编码，3-文本类型、10-Flowagent 输出、0-结束标识、4-消耗数据、39-语音消息。
    message string 消息类型，取值：Text、FlowOutput、End。
    data object 回复内容。
    • Text message 流式数据分多次返回：
    {"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}} {"code":3,"message":"Text","data":"我"} {"code":3,"message":"Text","data":"可以"} {"code":3,"message":"Text","data":"帮"} {"code":3,"message":"Text","data":"助"} {"code":3,"message":"Text","data":"你"} {"code":3,"message":"Text","data":"的"} {"code":3,"message":"Text","data":"吗"} {"code":3,"message":"Text","data":"?"} {"code":10,"message":"FlowOutput","data":[{"content":"你好","branch":null,"from_component_name": "User Input"}]} {"code":4,"message":"Cost","data":{"prompt_tokens":4922,"completion_tokens":68,"total_tokens":4990,"prompt_tokens_details":{"audio_tokens":0,"text_tokens":4922},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"text_tokens":68}}} {"code":0,"message":"End","data":null}
                          
                      {"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}}
{"code":3,"message":"Text","data":"我"}  
{"code":3,"message":"Text","data":"可以"}
{"code":3,"message":"Text","data":"帮"}  
{"code":3,"message":"Text","data":"助"}
{"code":3,"message":"Text","data":"你"}  
{"code":3,"message":"Text","data":"的"}
{"code":3,"message":"Text","data":"吗"}
{"code":3,"message":"Text","data":"?"}
{"code":10,"message":"FlowOutput","data":[{"content":"你好","branch":null,"from_component_name": "User Input"}]}
{"code":4,"message":"Cost","data":{"prompt_tokens":4922,"completion_tokens":68,"total_tokens":4990,"prompt_tokens_details":{"audio_tokens":0,"text_tokens":4922},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"text_tokens":68}}}
{"code":0,"message":"End","data":null}
    此代码块在浮窗中显示
    • audio message 流式数据分多次返回：
    {"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}} {"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"你好"}} {"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"，请"}} {"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"问"}} {"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"有什么"}} {"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}} {"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}} {"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}} {"code":10,"message":"FlowOutput","data":[{"content":" Audio:https://gptbots.ai/example.wav,Transcript:(Hello! How can I assist you today?)","audioDatas":[{"transcript":"Hello! How can I assist you today?","url":"https://gptbots.ai/example.wav","seconds":3}],"from_component_name":"AI Model-1"}],"componentId":12}{"code":4,"message":"Cost","data":{"prompt_tokens":4922,"completion_tokens":68,"total_tokens":4990,"prompt_tokens_details":{"audio_tokens":0,"text_tokens":4922},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"text_tokens":68}}} {"code":0,"message":"End","data":null}
                          
                      {"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"你好"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"，请"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"问"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"有什么"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":10,"message":"FlowOutput","data":[{"content":" Audio:https://gptbots.ai/example.wav,Transcript:(Hello! How can I assist you today?)","audioDatas":[{"transcript":"Hello! How can I assist you today?","url":"https://gptbots.ai/example.wav","seconds":3}],"from_component_name":"AI Model-1"}],"componentId":12}{"code":4,"message":"Cost","data":{"prompt_tokens":4922,"completion_tokens":68,"total_tokens":4990,"prompt_tokens_details":{"audio_tokens":0,"text_tokens":4922},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"text_tokens":68}}}
{"code":0,"message":"End","data":null}
    此代码块在浮窗中显示

    成功响应（webhook）

    ⚠️ webhook响应模式下，人工接管服务可用。
    当 Agent 配置了人工服务功能时，应该选择使用webhook响应模式才能接收到人工客服回复的消息。开发者在「集成-API」完成配置 webhook 地址后，GPTBots系统将向 Webhook 地址发送「Agent」和「人工客服」的响应消息。
    webhook配置
    Webhook 消息详见 Webhook模式 和人工接管服务。

    失败响应

    字段 类型 描述
    code int 错误码。
    message string 错误详情。

    错误码

    Code Message
    40000 参数错误
    40127 开发者鉴权失败
    40356 会话不存在
    40358 会话ID与智能体或用户不匹配
    40364 该 智能体 未使用支持图片模态的 大模型
    50000 系统内部错误
    20040 超过问题长度限制
    20022 积分不足
    20055 禁止使用api功能,请确保API开关已经打开