发送消息
最新更新:2025-02-27

发送消息

向指定的对话 ID 发送消息v2版本,并获取 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 对话消息内容,支持 userassistant 2 个角色来构造对话上下文。
  • user message:必须存在至少 1 条,最新的 user message 应放在最后。
  • assistant message:支持开发者自行构造 assistant message 作为上下文
  • conversation_config object 支持开发者在本次对话中临时调整 Agent 的功能范围,以应对特殊场景需要。
  • short_term_memory:短记忆开关,支持开启和或关闭短记忆,仅本次对话生效。
  • long_term_memory:长记忆开关,支持开启和或关闭长记忆,仅本次对话生效。
  • knowledge:知识检索范围,支持自定义知识检索范围,仅本次对话生效。group_idsdata_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
            }
        }
    }
    
            
    此代碼塊在浮窗中顯示

    成功响应(阻塞)

    字段 类型 描述
    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 Agent回复的消息内容,当前包含了textaudio 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 所消耗的积分。

    成功响应(流式)

    字段 类型 描述
    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 地址,成功响应后,GPTBots系统将向 Webhook 地址发送 Agent 和 人工客服的消息。详细消息格式详见 Webhook模式

    失败响应

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

    错误码

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