图解消息流转

本页用一张图和分步说明解释消息从发送方到接收方的完整链路，包括在线投递、离线补发、多端同步与聊天室广播。

总览​

消息始终由发送方客户端先发往 IM Server，由服务端完成校验、持久化、分配 seq，再扇出给接收方与回调地址。

发送流程​

1. 客户端发送消息

   客户端发送 send 帧，携带 conversationType、targetId、消息内容与 clientMsgId。

2. 服务端校验与幂等

   校验连接、目标会话、禁言与频率；同一用户相同 clientMsgId 在 10 分钟内幂等。

3. 持久化并分配 seq

   写入消息存储，按会话分配单调递增 seq，返回 send_ack。

4. 扇出

   向接收方在线会话投递 message；发送方其他端收到 direction=SEND 副本；触发 message.routed 回调。

5. 接收端 ack

   接收端持久化后 ack；服务端推进用户级已读游标。

接收流程​

• 在线：服务端通过长连接直接投递，客户端按 messageId 去重；
• 离线：消息进入离线队列，每个会话最多 500 条；
• 重连：服务端按 deliveredSeq 重放，最后发送 sync_done 表示补发结束；
• 客户端：收到 sync_done 后触发 CONNECTED，开始正常 ping/pong。

离线补发​

WS open → server hello
server message* (offline replay, seq 升序)
server sync_done
client ping/pong
SDK 触发 CONNECTED

多端同步​

同一账号的多个在线设备都会收到消息副本；发送方其他端 direction=SEND 且 clientMsgId 相同，接收方 direction=RECEIVE。任一端 ack 推进用户级游标。

聊天室​

聊天室消息不持久化、不补发；加入后获取最近 50 条，发送时广播给房内在线成员，退出或断连触发成员变更事件。

可靠性约束​

相关文档​

• WebSocket 协议参考（由协议契约生成）
• 基础功能
• 回调服务