企业微信会话管理API：会话列表、消息同步与客服工作台

1. 引言

「企业微信会话API」「企微聊天记录对接」「企业微信客服工作台」要解决的是：坐席在自建系统里看到客户会话，而不是只在手机企业微信里翻。会话层是 SCRM 工作台的核心。

2. 会话层要什么

• 会话列表（最近联系人、未读、最后一条）
• 历史消息展示（文本/图片/文件）
• 实时新消息（Webhook 增量）
• 坐席回复（调用发消息接口）
• 会话分配、转接、备注

数据来自 QIWe API 的会话模块与消息模块。工作台必须按坐席和 guid 过滤，防止串数据。

3. 推荐同步策略

不要每次打开页面都全量拉历史。用 Webhook 做增量，本地落库；图片文件按需下载；首次打开某客户再补一段历史。

Webhook 新消息 → 写入 message 表 → 更新 conversation.last_msg_at
坐席打开会话 → 读本地库
坐席点击发送 → QIWe API → 写自己的出站消息（也要幂等）

4. 工作台权限

按 owner_seat 过滤客户；主管可看团队；离职客户走继承流程后再允许新坐席发送。所有出站必须留操作人。

会话与消息相关 method，对照 QiWe API文档（https://doc.qiweapi.com/）。先做到「回调能写进列表、坐席能回一条」。

5. 文件与图片

列表里不要直接塞二进制。存资源 ID 或下载任务，点击再拉。下载失败要可重试，并注意客户隐私，访问需登录态。

6. 注意点

• 回调重推导致重复气泡：用 msgId 去重
• 坐席连点发送：前端防抖 + 后端幂等键
• QIWe API 掉线时工作台应明确提示「设备离线」
• 不同设备的聊天记录不要混进同一条会话时间线而不标来源

7. 总结

企业微信会话管理二次开发的目标，是把企微通道变成可分配、可审计的坐席工作台。会话模块只提供数据，分配规则在你的业务里。