菜单

发送消息

发送消息 API

接口说明

创建一条智能体消息，并通过会话 ID 将其添加到指定的会话中。

注意: 此接口仅支持通过 API 创建的会话。

请求地址

复制代码 
POST https://api.helpbots.ai/api/chats/message

请求 Headers

参数名 类型 是否必填 描述
x-api-key string 是 用户的 API Key，用于身份认证

请求参数 (JSON Body)

参数名 类型 是否必填 默认值 描述
id int 是 - 智能体 ID
conversation_id string 是 - 会话 ID
question string | array 是 - 用户的问题，支持文本或图片搜索，详见下方说明
stream boolean 否 true 是否启用流式响应模式
response_format string 否 text 响应格式，可选值：text（文本格式）、json_object（JSON 对象格式）

question 参数说明

question 参数支持以下三种格式：

1. 文本问题

json 复制代码 
[{"type":"text","text":"您的问题内容"}]

2. 多模态图片问答

json 复制代码 
[{"type":"text","text":"我这个订单什么时候发货？"}, {"type":"image_url","image_url":{"url":"https://xxx.com/image.png"}}]

注意: 图片链接长度不可超过 300 个字符。

3. 图片搜索 (搜同款)

json 复制代码 
[{"type":"goods_image","goods_image":"https://xxx.com/image.png"}]

注意: 图片链接长度不可超过 300 个字符。

response_format 参数说明

response_format 参数用于控制 AI 回答的响应格式：

  • text (默认值): 返回纯文本格式的回答内容
  • json_object: 返回 JSON 对象格式的回答内容，便于结构化数据解析

注意: 该参数主要影响 AI 问答 (message_type=0) 的回答格式，对以图搜图和 FAQ 匹配的无效。

响应说明

响应结果通过 message_type 字段区分消息类型：

message_type 类型说明 描述
0 AI 问答 基于知识库的 AI 智能回答
1 以图搜图 根据图片搜索相似商品
2 FAQ 知识库匹配 精确匹配 FAQ 知识库中的问答对

使用示例

示例 1: AI 问答

请求示例

bash 复制代码 
curl --location --request POST 'https://api.helpbots.ai/api/chats/message' \
--header 'x-api-key: your_api_key_here' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1,
    "conversation_id": "64xalvljy2jrasyxxxx",
    "question": [{"type":"text","text":"今天星期几？"}],
    "stream": true,
    "response_format": "text"
}'

流式响应 (stream=true)

AI 回答内容

json 复制代码 
data: {"choices":[{"delta":{"content":"关于","role":"assistant"},"index":0}],"created":1752140585,"id":"021752140583993817f2a48b003f7ed02744c0aecf079de74a6e2","model":"deepseek-v3-250324","service_tier":"default","object":"chat.completion.chunk","usage":null}

文档来源

json 复制代码 
data: {"object":"source","source":[{"resource_id":32,"resource_type":1,"content_id":1835,"title":"今天星期几？","content":"今天星期五","score":0.4715660354961766,"resource_url":"http://10.101.****/common/system/redirect?resource_id=32&resource_type=1"}]}

结束标记

json 复制代码 
data: [DONE]

非流式响应 (stream=false)

json 复制代码 
{
    "data": {
        "model": "deepseek-v3-250324",
        "question": "提问",
        "answer": "回答",
        "usage": {
            "completion_tokens": "331",
            "prompt_tokens": "5698",
            "total_tokens": "6029",
            "prompt_tokens_details": {
                "cached_tokens": "0"
            },
            "completion_tokens_details": {
                "reasoning_tokens": "0"
            }
        },
        "source": [
            {
                "resource_id": "50",
                "resource_type": "1",
                "content_id": "28392",
                "title": "猿猴",
                "sub_title": "猿猴来源",
                "content": "片段",
                "score": "0.74227011203766",
                "index": "1",
                "extra_data": {},
                "resource_url": "https://testing-api.helpbots.ai/common/system/redirect?doc_id=28392&doc_type=article",
                "record_id": "2248",
                "add_time": "1752140719"
            }
        ],
        "object": "chat",
        "message_type": "0"
    },
    "msg": "Success",
    "code": 200
}

示例 1.1: AI 问答 (JSON 对象格式)

请求示例

bash 复制代码 
curl --location --request POST 'https://api.helpbots.ai/api/chats/message' \
--header 'x-api-key: your_api_key_here' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1,
    "conversation_id": "64xalvljy2jrasyxxxx",
    "question": [{"type":"text","text":"今天星期几？"}],
    "stream": false,
    "response_format": "json_object"
}'

响应示例

当 response_format="json_object" 时，AI 回答内容会以 JSON 对象格式返回，便于结构化解析。

json 复制代码 
[
    {
        "type": "text",
        "value": "大模型的回答的段落1"
    },
    {
        "type": "text",
        "value": "大模型的回答的段落2"
    },
    {
        "type": "image",
        "value": "https://wwww.a.com/a.jpg (图片的url)"
    }
]

示例 2: 以图搜图

请求示例

bash 复制代码 
curl --location --request POST 'https://api.helpbots.ai/api/chats/message' \
--header 'x-api-key: your_api_key_here' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 18,
    "conversation_id": "kh07y73amutqwb5d2273vf65",
    "question": [{"type":"goods_image","goods_image":"https://xxx.com/a.png"}],
    "stream": true
}'

流式响应 (stream=true)

json 复制代码 
data: {"source":[{"resource_id":"1","resource_type":"4","content_id":"1","title":"SHOP3","sub_title":"","content":"","extra_data":{"id":"DD003","goods_name":"商品名称","goods_link":"https://example.com","original_price":"93","sale_price":"46.4","currency":"CNY","desc":"产品描述","main_image":"商品主图.png","image1":"商品图1.png","image2":"商品图2.png"},"score":"0.69207616495632","resource_url":"","record_id":"2099","add_time":"1751374304"}],"message_type":"1"}

非流式响应 (stream=false)

json 复制代码 
{
    "data": {
        "answer": "当source为空时，这里返回搜图失败原因",
        "source": [
            {
                "resource_id": "1",
                "resource_type": "4",
                "content_id": "1",
                "title": "SHOP3",
                "sub_title": "",
                "content": "",
                "extra_data": {
                    "id": "DD003",
                    "goods_name": "商品名称",
                    "goods_link": "https://example.com",
                    "original_price": "93",
                    "sale_price": "46.4",
                    "currency": "CNY",
                    "desc": "产品描述",
                    "main_image": "商品主图.png",
                    "image1": "商品图1.png",
                    "image2": "商品图2.png"
                },
                "score": "0.69207616495632",
                "resource_url": "",
                "record_id": "2099",
                "add_time": "1751374304"
            }
        ],
        "message_type": "1"
    },
    "msg": "Success",
    "code": 200
}

示例 3: FAQ 知识库匹配

请求示例

bash 复制代码 
curl --location --request POST 'https://api.helpbots.ai/api/chats/message' \
--header 'x-api-key: your_api_key_here' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 18,
    "conversation_id": "kh07y73amutqwb5d2273vf65",
    "question": [{"type":"text","text":"常见问题的答案"}],
    "stream": true
}'

流式响应 (stream=true)

json 复制代码 
data: {"message_type":"2","data":[{"type":"text","value":"消息1"},{"type":"text","value":"消息2"}]}

非流式响应 (stream=false)

json 复制代码 
{
    "data": {
        "message_type": "2",
        "data": [
            {
                "type": "text",
                "value": "消息1"
            },
            {
                "type": "image",
                "value": "https://xxxxx.com/x.png"
            },
            {
                "type": "attachment",
                "value": "https://xxxxx.com/x.docx"
            }
        ]
    },
    "msg": "Success",
    "code": 200
}

FAQ 响应数据类型说明

type 描述 value 示例
text 文本消息 "消息内容"
image 图片消息 "https://xxxxx.com/x.png"
attachment 附件消息 "https://xxxxx.com/x.docx"

响应字段说明

AI 问答响应字段 (message_type=0)

字段名 类型 描述
model string 使用的 AI 模型名称
question string 用户提问的问题
answer string AI 生成的回答
usage object Token 使用情况统计
source array 回答依据的知识库来源列表
object string 对象类型，固定值 "chat"
message_type string 消息类型，值为 "0"

source 字段说明

字段名 类型 描述
resource_id string 资源 ID
resource_type string 资源类型
content_id string 内容 ID
title string 标题
sub_title string 副标题
content string 内容片段
score string 相似度评分 (0-1)
index string 索引位置
extra_data object 额外数据
resource_url string 资源链接
record_id string 记录 ID
add_time string 添加时间戳

以图搜图响应字段 (message_type=1)

字段名 类型 描述
source array 搜索到的商品列表
message_type string 消息类型，值为 "1"

source.extra_data 商品字段说明

字段名 类型 描述
id string 商品 ID
goods_name string 商品名称
goods_link string 商品链接
original_price string 原价
sale_price string 售价
currency string 货币单位
desc string 商品描述
main_image string 商品主图
image1 string 商品图片 1
image2 string 商品图片 2

FAQ 匹配响应字段 (message_type=2)

字段名 类型 描述
message_type string 消息类型，值为 "2"
data array FAQ 回答的消息列表

错误码说明

HTTP 状态码 code msg 描述
200 200 Success 请求成功
401 401 Unauthorized API Key 无效或未提供
400 400 Bad Request 请求参数错误
404 404 Not Found 资源不存在
500 500 Internal Server Error 服务器内部错误

注意事项

  1. API Key 安全: 请妥善保管您的 API Key，不要在客户端代码中暴露
  2. 请求频率: 建议合理控制请求频率，避免触发限流
  3. 图片链接: 使用以图搜图功能时，确保图片链接可公开访问且长度不超过 303 字符
  4. 会话管理: 此接口仅支持通过 API 创建的会话，Web 端创建的会话无法使用
  5. 流式响应: 建议使用流式模式 (stream=true) 以获得更好的用户体验
  6. 编码格式: 请求和响应均使用 UTF-8 编码

常见问题 (FAQ)

Q: 如何创建会话 ID？

A: 请参考会话创建 API 文档，通过 API 创建会话后会返回 conversation_id。

Q: stream 参数如何选择？

A:

  • stream=true: 适合需要实时展示 AI 回答过程的场景，用户体验更好
  • stream=false: 适合只需要获取完整结果的场景，处理更简单

Q: 如何判断消息类型？

A: 根据响应中的 message_type 字段判断：

  • 0: AI 问答
  • 1: 以图搜图
  • 2: FAQ 匹配

Q: 图片搜索有什么限制？

A: 图片链接长度不能超过 303 个字符，且需要确保图片链接可公开访问。

Q: response_format 参数如何使用？

A:

  • response_format="text": 默认值，返回纯文本格式的回答，适合一般对话场景
  • response_format="json_object": 返回 JSON 对象格式的回答，适合需要结构化数据的场景，如需要解析特定字段或进行数据处理
上一个
创建会话
下一个
查看消息列表
最近修改: 2025-12-12SaleSmartly