跳至主要内容

会话消息列表

按游标分页返回指定会话的消息记录。该接口面向服务端对接,只返回适合对外输出的消息字段。

请求​

POST https://apichat.twt.com/openapi/chat/list_msg

Header 参数​

参数名类型必填说明
x-chat-signaturestring是使用原始 JSON Body 计算的 HMAC-SHA256 签名
Acceptstring否默认值:application/json
Content-Typestring是application/json
langstring否响应语言,控制接口提示文案。支持值见语言配置。可选,默认 zh-cn;未传或非法时回退 zh-cn。该请求头不参与 HMAC 计算。

Body 参数​

参数名类型必填说明
appidstring是应用标识,客服端-设置-开发设置查看
timestampinteger是Unix 秒级时间戳。生产环境超过 2 分钟的请求会被拒绝
ranstrstring是非空随机字符串
chat_idinteger是会话 ID,可对应工单、单聊或群聊会话
directionstring是prev 加载更早消息,next 加载更新消息
pos_idinteger条件必填direction=next 时必填;首次加载更早消息时不传
limitinteger否每页数量,可选 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 成功​

参数名类型说明
codeinteger成功时为 1
msgstring成功时为 ok
data.listarray消息列表,按 ID 倒序
data.prev_idinteger/null当前页最新消息 ID
data.next_idinteger/null当前页最旧消息 ID

消息字段​

参数名类型说明
idinteger消息 ID
chat_idinteger会话 ID
pidinteger回复的父消息 ID,非回复消息为 0
lxinteger消息类型
contentstring/object消息内容,结构由 lx 决定
fs_lxinteger发送方:1 访客,2 客服,3 系统
tjuidinteger发送方内部用户 ID
ztinteger消息状态:1 正常,2 撤回
is_nbinteger0 普通消息,1 内部回复
is_apinteger0 普通消息,1 Autopilot 消息
tjsjstring消息创建时间
at_uidsarray@ 的用户 ID,无人被 @ 时为空数组
pcontentstring/objectpid > 0 时返回父消息内容
ptjuidintegerpid > 0 时返回父消息发送方 ID
pfs_lxintegerpid > 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会话后表单存在时返回表单快照结构化数据
10Autopilot 快捷卡片包含卡片内容和操作的结构化对象
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。