聊天机器人平台 · 聊天记录 API

业务平台 · 聊天记录查询 API

供运营管理后台等业务系统拉取企微会话存档中的客户聊天记录。数据来源为聊天机器人已解密落库的 cb_wecom_chat_message 表（需开启企微会话存档）。鉴权方式与用户同步接口一致，使用 X-Chatbot-Webhook-Secret 请求头（与用户同步中配置的 Webhook 密钥相同）。

接口基址：/api/public/chatbot/chat-messages

鉴权

请求头	必填	说明
`X-Chatbot-Webhook-Secret`	是	与聊天机器人「用户同步」配置的 Webhook 密钥一致（环境变量 `PLATFORM_SYNC_WEBHOOK_SECRET` 或管理页保存的值）

查询聊天记录

GET /api/public/chatbot/chat-messages

Query 参数

参数	类型	说明
`platform_user_id`	integer	运营管理后台用户 ID（推荐）。与用户同步成功后返回的 `id` 对应。
`external_userid`	string	企微外部联系人 ID。与 `platform_user_id` 二选一；若两者都传，优先使用 `platform_user_id`。
`follow_userid`	string	企微跟进人成员 ID。与 `platform_user_id` 配合使用时必填（同一平台用户可添加多位跟进人，以 `platform_user_id + follow_userid` 联合定位会话）。与 `external_userid` 配合使用时可选；不传时取本地最近更新的跟进关系。
`limit` 可选	integer	每页条数，默认 50，最大 200。
`before_seq` 可选	long	分页游标：返回 `seq` 小于该值的更早消息。取上一页响应中的 `next_before_seq`。
`since` 可选	long	消息时间下限（Unix 毫秒，对应企微 `msgtime`）。
`until` 可选	long	消息时间上限（Unix 毫秒）。

响应字段

字段	类型	说明
`conversation`	object	会话标识：external_userid、follow_userid、customer_name、platform_user_id
`messages`	array	消息列表，按时间升序
`messages[].direction`	string	`inbound` 客户发来；`outbound` 员工发出
`messages[].sender_role`	string	`customer` 或 `staff`
`messages[].content`	string	文本内容或媒体占位；语音若已识别则返回识别文本
`messages[].has_media`	boolean	媒体是否已下载就绪，为 true 时可调 `/chat-media/{msgid}`
`messages[].media_status`	string	媒体处理状态：`pending` / `success` / `failed`
`messages[].voice_play_seconds`	int \| null	语音时长（秒）
`messages[].voice_transcript`	string \| null	语音识别文本
`messages[].file_name`	string \| null	文件名（msgtype=file 时）
`messages[].msgtime`	long	企微消息时间戳（毫秒）
`has_more`	boolean	是否还有更早消息
`next_before_seq`	long \| null	下一页游标；无更多时为 null

响应示例

{
  "conversation": {
    "external_userid": "wmxxxxxxxx",
    "follow_userid": "ZhangSan",
    "customer_name": "李女士",
    "platform_user_id": 12345
  },
  "messages": [
    {
      "msgid": "CAxxxx",
      "seq": 1001,
      "direction": "inbound",
      "sender_role": "customer",
      "msgtype": "text",
      "content": "你好，我想咨询一下",
      "msgtime": 1718000000000
    },
    {
      "msgid": "CAyyyy",
      "seq": 1002,
      "direction": "outbound",
      "sender_role": "staff",
      "msgtype": "text",
      "content": "您好，请问有什么可以帮您？",
      "msgtime": 1718000060000
    }
  ],
  "has_more": false,
  "next_before_seq": null
}

请求示例

curl -sS -G 'https://<chatbot-host>/api/public/chatbot/chat-messages' \
  -H 'X-Chatbot-Webhook-Secret: <your-secret>' \
  --data-urlencode 'platform_user_id=12345' \
  --data-urlencode 'limit=50'

分页示例

curl -sS -G 'https://<chatbot-host>/api/public/chatbot/chat-messages' \
  -H 'X-Chatbot-Webhook-Secret: <your-secret>' \
  --data-urlencode 'platform_user_id=12345' \
  --data-urlencode 'before_seq=1001' \
  --data-urlencode 'limit=50'

删除聊天记录

业务平台删除居民时调用：清除该客户会话存档消息，并同步删除相关定时消息、桥接事件与会话事件。鉴权同查询接口。

DELETE /api/public/chatbot/chat-messages

Query 参数

参数	类型	说明
`platform_user_id`	integer	运营管理后台用户 ID。与 `follow_userid` 联用定位；找不到同步关系时需同时传 `external_userid` 兜底。
`external_userid`	string	企微外部联系人 ID。与 `platform_user_id` 二选一；推荐始终带上。
`follow_userid`	string	跟进人。传入时仅删该跟进人会话；不传则删该外部联系人相关全部存档消息。

响应字段

字段	类型	说明
`ok`	boolean	是否成功
`deleted_messages`	int	删除的存档消息条数
`deleted_scheduled`	int	删除的定时消息条数
`deleted_bridge_events`	int	删除的桥接事件条数
`deleted_conversation_events`	int	删除的会话事件条数

请求示例

curl -sS -X DELETE 'https://<chatbot-host>/api/public/chatbot/chat-messages' \
  -H 'X-Chatbot-Webhook-Secret: <your-secret>' \
  -G \
  --data-urlencode 'platform_user_id=12345' \
  --data-urlencode 'follow_userid=ZhangSan' \
  --data-urlencode 'external_userid=wmxxxxxxxx'

错误码

HTTP	说明
401	缺少或错误的 `X-Chatbot-Webhook-Secret`
400	未提供 `platform_user_id` 或 `external_userid`
404	找不到对应客户或平台用户映射
503	Webhook 未配置，或企微 corp-id 未配置

前置条件

聊天机器人已启用企微通道（WECOM_ENABLED=true）
已开启并拉取会话存档（WECOM_MSGAUDIT_ENABLED=true），消息才会进入本地库
已在「用户同步」页配置 Webhook 密钥；业务平台调用时使用相同密钥
若使用 platform_user_id，客户需已通过用户同步写入运营管理后台

相关接口：用户同步见用户同步；运营管理后台入站接口为 POST /api/public/chatbot/user（由本服务主动调用， event=added 同步用户、event=removed 标记取关；有企微 unionid 时一并传 union_id，便于小程序同源绑定）。