会话与消息事件

先按WebSocket 连接与订阅完成连接和频道订阅；HTTP 写入接口仍是最终来源，访客与客服的初始化入口分别见访客端接口概览和客服端接口概览。

事件	说明	关键字段
message.created	新消息或问候语	mid、uid、agent_id、content、author、sub_type、tmp_mid
message.translated	客服消息翻译增量	mid、translated_content、author
message.read	消息已读	uid、agent_id、mid、reader
message.revoked	消息撤回	uid、mid
typing	对方正在输入	uid、agent_id、content
conversation.transferred	会话已转接	agent、visitor、from、message
conversation.ended	会话已结束	service_session_id、invite_rating、invite_resolved
conversation.updated	会话置顶或机器人状态变化	uid、agent_id、pinned_at 或 bot
conversation.deleted	客服侧会话已隐藏	uid、agent_id
session.rated	访客提交评分	service_session_id、stars
session.resolved	访客提交解决状态	service_session_id、resolved

客户端接到事件后，应以 mid 去重。实时事件可能重复或在断线期间遗漏，因此消息列表接口仍是最终一致性来源。

按频道处理事件

频道	典型事件	前端动作
访客频道	message.created、message.read、message.revoked、conversation.ended、评分与解决状态事件	更新当前对话消息、已读状态和结束提示。
客服频道	消息、已读、撤回、转接、结束、隐藏、输入中和会话更新事件	更新当前会话与会话列表；转出或结束时移除/关闭当前会话。
商户全局频道	settings.updated、agent.presence.updated、visitor.updated、上下文/标签/访客字段配置事件	局部刷新设置、在线状态和访客信息，不应重建整页。

全局频道的事件是增量补丁。只更新事件实际携带的字段，避免用不完整的实时负载覆盖初始化接口返回的完整对象。

消息事件的合并规则

message.created 是最常见事件。推荐按以下顺序合并：

1. 读取 mid；同一 mid 已存在时只补充缺失字段，不追加新行。
2. 若事件携带 tmp_mid，先匹配本地待发送消息，再用服务端 mid 替换临时 ID。
3. 按 mid 重新排序；不要按浏览器接收时间排序。
4. 消息撤回时按 uid + mid 幂等移除或标记撤回。
5. 翻译事件只更新原消息的译文，不创建第二条聊天消息。

会话事件的合并规则

事件	推荐处理
conversation.transferred	原客服从会话列表移除；目标客服读取完整会话资料后加入。若当前页正打开该会话，停止继续发送并返回列表。
conversation.ended	当前会话结束；停止输入/发送，按返回字段决定是否展示评分或解决状态入口。
conversation.updated	仅更新置顶、机器人接待模式等事件携带字段。
conversation.deleted	仅在当前客服视角隐藏会话，不等同于结束会话。
typing / conversation.typing	仅作为临时提示；正式消息到达、离开会话或结束会话时清除。

事件负载的兼容处理

• 对未知事件记录可脱敏的事件名和字段结构，但不要让客户端崩溃。
• 对缺失的可选字段使用安全默认值；对缺少 mid 的消息类事件不要创建新消息。
• 服务端可能向消息事件补充标准化消息字段。客户端应优先使用服务端返回的 mid、author、sub_type、content 与时间字段。
• 自定义前端升级前应同时验证 HTTP 初始化数据、事件订阅、断线补拉和多标签页消息去重。