请输入
菜单
发送消息
# 发送消息 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 对象格式的回答，适合需要结构化数据的场景，如需要解析特定字段或进行数据处理
上一个
创建会话
下一个
查看消息列表
最近修改: 2026-07-07Powered by;}.cls-2{fill:%230868f7;}.cls-3{fill:url(%23未命名的渐变_44);}.cls-4{fill:%23333;}%3c/style%3e%3clinearGradient%20id='未命名的渐变_8'%20x1='33.73'%20y1='100.61'%20x2='-0.03'%20y2='-1.06'%20gradientUnits='userSpaceOnUse'%3e%3cstop%20offset='0'%20stop-color='%237ae9fb'/%3e%3cstop%20offset='0.67'%20stop-color='%232b90f8'/%3e%3cstop%20offset='1'%20stop-color='%230868f7'/%3e%3c/linearGradient%3e%3clinearGradient%20id='未命名的渐变_44'%20x1='27.86'%20y1='18.67'%20x2='68.36'%20y2='22.22'%20gradientUnits='userSpaceOnUse'%3e%3cstop%20offset='0'%20stop-color='%235ac7f2'/%3e%3cstop%20offset='1'%20stop-color='%230868f7'/%3e%3c/linearGradient%3e%3c/defs%3e%3cpath%20class='cls-1'%20d='M29,28.74V81.91l-9.51-3.68v0L8.52,74A7.17,7.17,0,0,1,4,67.32V24.54A3.76,3.76,0,0,1,9.08,21Z'/%3e%3cpath%20class='cls-2'%20d='M68.09,78.07a13.15,13.15,0,0,1-17.9,12.06L29,81.91h0V28.74L50.19,37A13.17,13.17,0,0,0,68.08,25.3h0Z'/%3e%3cpath%20class='cls-3'%20d='M68.08,25.3a13.19,13.19,0,0,1-6.73,10.87A13.09,13.09,0,0,1,50.19,37L29,28.74V6A3.76,3.76,0,0,1,34.1,2.52l25.59,9.91A13.22,13.22,0,0,1,68.08,25.3Z'/%3e%3cpath%20class='cls-4'%20d='M129.06,81.76a4.33,4.33,0,0,1-3.19-1.31,4.4,4.4,0,0,1-1.31-3.24V56.86H97.65V77.21a4.36,4.36,0,0,1-1.35,3.2A4.68,4.68,0,0,1,93,81.76a4.32,4.32,0,0,1-3.19-1.31,4.37,4.37,0,0,1-1.32-3.24V27.27A4.58,4.58,0,0,1,89.83,24a4.59,4.59,0,0,1,7.82,3.27V48.15h26.91V27.27A4.58,4.58,0,0,1,125.91,24a4.59,4.59,0,0,1,7.82,3.27V77.21a4.37,4.37,0,0,1-1.36,3.2A4.65,4.65,0,0,1,129.06,81.76Z'/%3e%3cpath%20class='cls-4'%20d='M163.77,81.66c-6.57,0-11.76-1.92-15.44-5.7s-5.54-9.07-5.54-15.74a26.76,26.76,0,0,1,2.09-10.43,17.72,17.72,0,0,1,6.67-8.06,19.15,19.15,0,0,1,10.68-2.95,19,19,0,0,1,10.46,2.8,18.7,18.7,0,0,1,6.55,7.36,22.53,22.53,0,0,1,2.36,10.28A4.51,4.51,0,0,1,177,63.77H152.23a10.8,10.8,0,0,0,3.49,6.65c2,1.68,4.88,2.52,8.66,2.52a22.25,22.25,0,0,0,7.54-1.21c.74-.3,1.55-.67,2.37-1.07a3.75,3.75,0,0,1,1.84-.4,4.09,4.09,0,0,1,3,1.15,4,4,0,0,1,1.12,3,4.38,4.38,0,0,1-2.58,3.82,32.34,32.34,0,0,1-6.36,2.61A28.67,28.67,0,0,1,163.77,81.66ZM172.4,55.9a9.72,9.72,0,0,0-1.63-4.56A9.9,9.9,0,0,0,167,48a10.38,10.38,0,0,0-4.64-1.14,12,12,0,0,0-4.77,1.06,9.54,9.54,0,0,0-4.89,5.66,11.78,11.78,0,0,0-.51,2.3Z'/%3e%3cpath%20class='cls-4'%20d='M193,81.64a4.49,4.49,0,0,1-4.51-4.55V27.28A4.58,4.58,0,0,1,189.84,24a4.48,4.48,0,0,1,3.28-1.36A4.36,4.36,0,0,1,196.35,24a4.46,4.46,0,0,1,1.31,3.31V77.09a4.34,4.34,0,0,1-1.35,3.2A4.67,4.67,0,0,1,193,81.64Z'/%3e%3cpath%20class='cls-4'%20d='M263.79,81.71a5.7,5.7,0,0,1-4.2-1.74,5.76,5.76,0,0,1-1.73-4.19V27.37a4.58,4.58,0,0,1,1.35-3.27A4.59,4.59,0,0,1,267,27.37V72.53h24a4.58,4.58,0,0,1,3.27,7.82A4.66,4.66,0,0,1,291,81.71Z'/%3e%3cpath%20class='cls-4'%20d='M424.48,81.74a4.71,4.71,0,0,1-2.71-.88,5.43,5.43,0,0,1-1-1l-.07-.09-12.41-17-5.41,5v9.44a4.31,4.31,0,0,1-1.36,3.19,4.66,4.66,0,0,1-3.3,1.36A4.29,4.29,0,0,1,395,80.42a4.36,4.36,0,0,1-1.32-3.23V27.37A4.58,4.58,0,0,1,395,24.1a4.52,4.52,0,0,1,6.58.12,4.54,4.54,0,0,1,1.24,3.15V56.31l17.72-16.38.05,0a4.8,4.8,0,0,1,2.94-1.11,4.4,4.4,0,0,1,3.27,1.2,4.57,4.57,0,0,1,1.2,3.27,4.44,4.44,0,0,1-.77,2.33,7.45,7.45,0,0,1-1.43,1.65l-11,9.64,13.34,17.68a5,5,0,0,1,1,2.71,4.12,4.12,0,0,1-1.36,3.24A4.64,4.64,0,0,1,424.48,81.74Z'/%3e%3cpath%20class='cls-4'%20d='M317.93,81.76a21.5,21.5,0,1,1,21.17-21.5A21.37,21.37,0,0,1,317.93,81.76Zm0-34.1a12.61,12.61,0,1,0,12.42,12.6A12.52,12.52,0,0,0,317.93,47.66Z'/%3e%3cpath%20class='cls-4'%20d='M212.18,101.22a4.12,4.12,0,0,1-3.05-1.26,4.17,4.17,0,0,1-1.26-3.1V43.34a4.37,4.37,0,0,1,1.3-3.14,4.26,4.26,0,0,1,3.13-1.3,4.19,4.19,0,0,1,3.1,1.26,4.32,4.32,0,0,1,1.26,3.16,20.77,20.77,0,0,1,13-4.54,21.51,21.51,0,0,1,0,43,20.51,20.51,0,0,1-13-4.57V96.86a4.15,4.15,0,0,1-1.3,3.06A4.5,4.5,0,0,1,212.18,101.22Zm17.43-53.63c-6.23,0-12.93,4.11-12.93,12.72a12.73,12.73,0,0,0,25.46,0A12.71,12.71,0,0,0,229.61,47.59Z'/%3e%3cpath%20class='cls-4'%20d='M365.76,81.76a21.5,21.5,0,1,1,21.18-21.5A21.37,21.37,0,0,1,365.76,81.76Zm0-34.1a12.61,12.61,0,1,0,12.42,12.6A12.52,12.52,0,0,0,365.76,47.66Z'/%3e%3c/svg%3e)
大纲