消息
理解消息是什么、如何找到接收范围，以及发送成功、送达和已读为什么不是一回事。
消息（Message）是 WuKongIM 传递信息的基本单位。文字、图片、文件、通知、音视频信令或 IoT 指令，都可以作为消息内容发送。
普通持久消息会进入目标频道，可实时投递并供离线设备稍后同步。消息里的业务含义和展示方式由你的应用定义；特殊瞬时或命令分支具有不同边界。
为什么消息重要
- 承载业务内容：同一条消息通道可以承载聊天内容，也可以承载自定义业务事件。
- 支持实时与离线场景：普通持久消息可实时投递，并在离线或重连后从已提交的频道历史中恢复。
- 可以追踪与去重：客户端发送编号、服务端消息 ID 和频道内序号分别帮助重试、查询和排序。
与其他概念的关系
- 频道决定消息发到哪里、谁有机会接收，以及消息在哪个范围内排序。
- 用户是消息的发送者或频道参与者。
- 设备是用户发送、实时接收和离线恢复消息的具体端点。
- 会话把频道中的最近消息和未读状态呈现给某个用户。
一条消息包含什么
从应用开发者的角度，可以把一条消息理解为“谁，把什么，发到哪里”：
| 信息 | 作用 | 常见字段 |
|---|---|---|
| 发送者 | 标识消息来自哪个用户 | from_uid |
| 目标 | 指定消息所属的频道 | channel_id、channel_type |
| 内容 | 保存文字、图片信息或自定义数据 | payload |
| 客户端发送编号 | 标识一次逻辑发送，重试时用于幂等 | client_msg_no |
| 服务端身份与位置 | 用于查询、去重和频道内排序 | message ID、message_seq |
例如，应用可以把一条文本消息的 Payload 定义为：
{
"type": 1,
"content": "周六上午 9 点集合"
}type 的取值和其他字段由业务与客户端共同约定。建议为自定义 Payload 设计版本和兼容策略。
一条持久消息经历什么
- 客户端生成稳定的
client_msg_no，并指定频道与 Payload。 - WuKongIM 检查身份、频道状态和发送权限。
- 消息按顺序写入该频道并达到提交边界。
- 发送方收到发送确认，在线接收者获得实时投递。
- 未实时收到的设备在重连后按频道进度同步缺失消息。
发送成功不等于对方已读
发送确认表示这次发送已经达到对应的服务端处理边界。它不表示每台设备都已收到，更不表示最终用户已经阅读。送达回执、已读回执和业务执行结果应分别设计。
三个容易混淆的编号
| 编号 | 谁生成 | 你通常用它做什么 |
|---|---|---|
client_msg_no | 发送方 | 对同一次发送进行幂等重试；重试时保持不变 |
| message ID | 服务端 | 标识服务端接受的一条消息，用于结果关联和诊断 |
message_seq | 频道消息日志 | 表示消息在当前频道中的位置和顺序 |
消息顺序只在同一个频道内有意义。不要用两个不同频道的 message_seq 推断全局先后关系。
开发时记住
- 必须可靠到达或需要离线恢复的内容，应使用普通持久消息。
- 重试同一次发送时复用原
client_msg_no，不要生成一条新的业务消息。 - Payload 是业务合同，需要限制大小、校验字段并做好版本兼容。
NoPersist、SyncOnce等特殊行为不要仅凭名称猜测，使用前查看 Message Flags。