会话消息列表
按游标分页返回指定会话的消息记录。该接口面向服务端对接,只返回适合对外输出的消息字段。
请求
POST https://apichat.twt.com/openapi/chat/list_msg
Header 参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
x-chat-signature | string | 是 | 使用原始 JSON Body 计算的 HMAC-SHA256 签名 |
Accept | string | 否 | 默认值:application/json |
Content-Type | string | 是 | application/json |
lang | string | 否 | 响应语言,控制接口提示文案。支持值见语言配置。可选,默认 zh-cn;未传或非法时回退 zh-cn。该请求头不参与 HMAC 计算。 |
Body 参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
appid | string | 是 | 应用标识,客服端-设置-开发设置查看 |
timestamp | integer | 是 | Unix 秒级时间戳。生产环境超过 2 分钟的请求会被拒绝 |
ranstr | string | 是 | 非空随机字符串 |
chat_id | integer | 是 | 会话 ID,可对应工单、单聊或群聊会话 |
direction | string | 是 | prev 加载更早消息,next 加载更新消息 |
pos_id | integer | 条件必填 | direction=next 时必填;首次加载更早消息时不传 |
limit | integer | 否 | 每页数量,可选 10、20、50、100,默认 20 |
分页规则
消息按 ID 倒序返回,即从新到旧排列。
- 首屏:传
direction=prev,不传pos_id。 - 加载更早消息:将
direction设为prev,并将pos_id设为上一页返回的next_id。 - 加载更新消息:将
direction设为next,并将pos_id设为上一页返回的prev_id。 prev_id是当前页最新消息 ID。next_id是当前页最旧消息 ID。- 当前页为空时,两个游标都返回
null。
请求示例
curl -X POST 'https://apichat.twt.com/openapi/chat/list_msg' \
-H 'x-chat-signature: 4ecdcaf813c422d34413671b2ed68e0a6e69ea8496d34ab40bd33cef26571e70' \
-H 'Content-Type: application/json' \
-H 'lang: zh-cn' \
-d '{
"appid": "1b621280becdb0fa3d3e041ff69e1e1f",
"timestamp": 1712899200,
"ranstr": "4ad0faec14a58112",
"chat_id": 1841,
"direction": "prev",
"limit": 20
}'
返回响应
200 成功
| 参数名 | 类型 | 说明 |
|---|---|---|
code | integer | 成功时为 1 |
msg | string | 成功时为 ok |
data.list | array | 消息列表,按 ID 倒序 |
data.prev_id | integer/null | 当前页最新消息 ID |
data.next_id | integer/null | 当前页最旧消息 ID |
消息字段
| 参数名 | 类型 | 说明 |
|---|---|---|
id | integer | 消息 ID |
chat_id | integer | 会话 ID |
pid | integer | 回复的父消息 ID,非回复消息为 0 |
lx | integer | 消息类型 |
content | string/object | 消息内容,结构由 lx 决定 |
fs_lx | integer | 发送方:1 访客,2 客服,3 系统 |
tjuid | integer | 发送方内部用户 ID |
zt | integer | 消息状态:1 正常,2 撤回 |
is_nb | integer | 0 普通消息,1 内部回复 |
is_ap | integer | 0 普通消息,1 Autopilot 消息 |
tjsj | string | 消息创建时间 |
at_uids | array | @ 的用户 ID,无人被 @ 时为空数组 |
pcontent | string/object | pid > 0 时返回父消息内容 |
ptjuid | integer | pid > 0 时返回父消息发送方 ID |
pfs_lx | integer | pid > 0 时返回父消息发送方类型 |
lx 与 content 结构
lx | 含义 | 常见 content 结构 |
|---|---|---|
1 | 文本 | 字符串 |
2 | 图片 | 包含 file_url、file_origin_url、file_full_url、width、height 的对象 |
3 | 语音 | 包含 file_url、sc、is_fan、fan_text 的对象 |
4 | 视频 | 包含 file_url、slt_url、sc、size、width、height 的对象 |
5 | 文件 | 包含 file_url、origin_name、size、ext 的对象 |
8 | 欢迎语快捷回复 | 包含快捷回复项的结构化对象或数组 |
9 | 会话后表单 | 存在时返回表单快照结构化数据 |
10 | Autopilot 快捷卡片 | 包含卡片内容和操作的结构化对象 |
90+ | 系统事件 | 根据事件类型返回字符串或结构化对象 |
成功示例
{
"code": 1,
"msg": "ok",
"data": {
"list": [
{
"id": 90126,
"chat_id": 1841,
"pid": 0,
"lx": 1,
"content": "可以发一下最新报价吗?",
"fs_lx": 1,
"tjuid": 20056,
"zt": 1,
"is_nb": 0,
"is_ap": 0,
"tjsj": "2026-10-23 10:30:00",
"at_uids": []
},
{
"id": 90124,
"chat_id": 1841,
"pid": 90110,
"lx": 1,
"content": "报价单已发送,请查收。",
"fs_lx": 2,
"tjuid": 10078,
"zt": 1,
"is_nb": 0,
"is_ap": 0,
"tjsj": "2026-10-23 10:29:00",
"at_uids": [],
"pcontent": "请把报价单发给我。",
"ptjuid": 20056,
"pfs_lx": 1
}
],
"prev_id": 90126,
"next_id": 90124
}
}
失败示例
{
"code": -1,
"msg": "token验证失败!",
"data": ""
}
{
"code": -1,
"msg": "抱歉, 参数错误!",
"data": ""
}
注意事项
- 签名必须基于实际发送的原始 JSON body 计算,字段顺序、空格和换行都需要保持一致。
- 系统会使用
appid对应站点校验chat_id,跨站点会话统一返回抱歉, 会话不存在!。 is_nb=1表示内部回复,接入方不得直接展示给访客。- 接口按客服侧消息视图返回,并裁剪内部已读、删除、撤回、未读计数和 AI 提问关联字段。
- 空页属于成功响应,返回
data.list: []、prev_id: null、next_id: null。