文档中心

Appearance

聊天记录 API ​

获取聊天记录列表 ​

获取聊天记录列表

获取指定智能体的聊天会话列表，支持分页查询

GEThttps://xrobo.qiniu.com/xiaozhi/agent/{agentId}/sessions
点击展开

基本信息

Host:https://xrobo.qiniu.com
Base Path:/xiaozhi
Method:GET
返回类型:application/json

请求参数

参数名类型必填位置说明
agentId
string是path智能体ID
page
integer否query页码，从1开始
limit
integer否query每页记录数

请求头

Header名类型必填说明
Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例 

GET /xiaozhi/agent/09689edfb5a74846ad8f2a6512c26a73/sessions?page=1&limit=20 HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>

响应示例 

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 139,
    "list": [
      {
        "sessionId": "7465966b-4582-4dae-99be-420364d422d7",
        "createdAt": "2025-08-28 16:02:49",
        "chatCount": 75
      },
      {
        "sessionId": "9eab0c2b-79c0-402c-a695-09d802bd977a",
        "createdAt": "2025-08-28 12:25:01",
        "chatCount": 3
      },
      ...(limit=20, 共20条)
    ]
  }
}

状态码

0OK - 成功获取聊天记录列表
401Unauthorized - 未登录或token无效

INFO

响应中的list包含会话的基本信息，包括sessionId、创建时间和聊天数量。total表示总记录数。

获取聊天记录详情 ​

获取聊天记录详情

获取指定智能体和会话的详细聊天记录

GEThttps://xrobo.qiniu.com/xiaozhi/agent/{agentId}/chat-history/{sessionId}
点击展开

基本信息

Host:https://xrobo.qiniu.com
Base Path:/xiaozhi
Method:GET
返回类型:application/json

请求参数

参数名类型必填位置说明
agentId
string是path智能体ID
sessionId
string是path会话ID

请求头

Header名类型必填说明
Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例 

GET /xiaozhi/agent/09689edfb5a74846ad8f2a6512c26a73/chat-history/7465966b-4582-4dae-99be-420364d422d7 HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>

响应示例 

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "createdAt": "2026-07-28 11:57:26",
      "chatType": 1,
      "content": "你好，请问我是谁？",
      "audioId": null,
      "audioUrl": "https://xrobot-obj.qnlinx.com/chat-history/2026/07/28/audio.wav",
      "macAddress": "09689edfb5a74846ad8f2a6512c26a73",
      "toolInfo": "",
      "toolDuration": 0,
      "clientListenMode": "auto"
    },
    {
      "createdAt": "2026-07-28 11:57:27",
      "chatType": 2,
      "content": "哦？这不是那个整天围着电子屏幕打转的人吗？",
      "audioId": null,
      "audioUrl": "https://xrobot-obj.qnlinx.com/chat-history/2026/07/28/response.wav",
      "macAddress": "09689edfb5a74846ad8f2a6512c26a73",
      "toolInfo": "",
      "toolDuration": 0,
      "clientListenMode": "auto"
    },
    ...
  ]
}

状态码

0OK - 成功获取聊天记录列表
401Unauthorized - 未登录或token无效

INFO

响应中的data是一个聊天消息数组，按时间顺序排列，每条消息包含：

  • createdAt：创建时间
  • chatType：消息类型（1=用户，2=AI，3=工具调用）
  • content：消息内容
  • audioId：音频ID（已废弃，始终为null）
  • audioUrl：音频文件地址，需要签名后才能访问
  • macAddress：设备MAC地址
  • toolInfo：工具调用信息
  • toolDuration：工具执行耗时（毫秒）
  • clientListenMode：客户端聆听模式（realtime/auto）

生成音频签名 URL ​

生成音频签名 URL

为聊天记录中的音频文件生成签名 URL，支持直接播放或下载

POSThttps://xrobo.qiniu.com/v1/objects/signed-url
点击展开

基本信息

Host:https://xrobo.qiniu.com
Base Path:/v1
Method:POST
返回类型:application/json

请求参数

参数名类型必填位置说明
url
string是body需要签名的音频 URL（从聊天记录详情中获取的 audioUrl）

请求头

Header名类型必填说明
Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例 

POST /v1/objects/signed-url HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://xrobot-obj.qnlinx.com/chat-history/2026/07/28/audio.wav"
}

响应示例 

{
  "code": 0,
  "msg": "success",
  "data": {
    "signed_url": "https://xrobot-obj.qnlinx.com/chat-history/2026/07/28/audio.wav?e=<Unix时间戳>&token=<签名token>"
  }
}

状态码

0OK - 操作成功
401Unauthorized - 未登录或token无效

注意事项

  • 需认证：此接口需要用户登录 token
  • 签名有效期：1 小时（e 参数为 Unix 时间戳）
  • 自动兼容：旧 bucket URL 会直接返回原 URL，无需二次处理

删除聊天记录 ​

按设备 MAC 地址删除聊天记录。

INFO

目前只删除数据库记录，OSS 上的音频文件由 60 天自动清理机制处理。

删除聊天记录

按设备 MAC 地址删除聊天记录（隐私保护功能）

DELETEhttps://xrobo.qiniu.com/v1/devices/{mac_address}/chat-history
点击展开

基本信息

Host:https://xrobo.qiniu.com
Base Path:/v1
Method:DELETE
返回类型:application/json

请求参数

参数名类型必填位置说明
mac_address
string是path设备MAC地址，格式: 1a:2b:3c:4d:5e:6f

请求头

Header名类型必填说明
Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例 

DELETE /v1/devices/AA:C8:BD:B8:00:77/chat-history HTTP/1.1
Host: xrobo.qiniu.com
Authorization: Bearer <token>

响应示例 

{
  "code": 0,
  "reqid": "v8ghAP2OBo4QVQYA",
  "data": {
    "deleted_count": 55
  }
}

状态码

0OK - 成功删除聊天记录
400Bad Request - MAC 地址格式不合法
401Unauthorized - 未登录或token无效
403Forbidden - 当前用户不是设备拥有者
404Not Found - 设备不存在
599Internal Server Error - 数据库或其他服务端内部错误