WuKongIM中API发送消息与SDK消息存储机制解析

在WuKongIM即时通讯系统的开发过程中，开发者经常会遇到通过API接口发送消息与通过SDK发送消息在存储行为上的差异问题。本文将深入分析这两种消息发送方式的区别，并提供最佳实践方案。

核心问题分析

通过WuKongIM的API接口/message/send发送消息时，虽然消息能够成功送达，但在客户端刷新后无法从消息列表中获取。而使用WKSDK.shared().chatManager.send()方法发送的消息则会被SDK正常存储和检索。

这种差异源于WuKongIM系统对消息处理的不同机制：

1. SDK发送的消息：会自动进行本地持久化存储，并维护消息序列，确保消息可检索
2. API发送的消息：默认作为"穿透消息"处理，不会自动持久化到客户端本地数据库

解决方案

对于需要通过API发送系统消息并希望客户端能够持久化的场景，可以通过以下两种方式解决：

1. 设置sync_once参数

在API调用时，将sync_once参数设置为0（默认为1）。这个参数的含义是：

• 0：普通消息，会被客户端持久化存储
• 1：命令消息，作为穿透消息处理，不会显示在会话列表中

2. 混合使用API和SDK

对于需要发送系统通知的场景，可以采用以下架构：

1. 后端API创建群组
2. 客户端SDK发送系统通知消息
3. 后端通过Webhook监听群组创建事件
4. 触发客户端发送对应的系统消息

最佳实践建议

1. 系统消息设计：对于邀请通知等系统消息，建议使用专门的系统消息类型，而非普通文本消息

2. 消息持久化策略：

   • 临时性通知：使用API发送，sync_once=1
   • 需要持久化的通知：使用API发送，sync_once=0或通过SDK发送

3. NestJS后端集成：在后端系统中，可以通过WuKongIM的管理API创建消息，但需要注意设置正确的消息属性以确保客户端能够正确处理

技术实现细节

WuKongIM的消息处理流程中，消息的持久化行为由多个因素决定：

• 消息的sync_once标志
• 消息的类型属性
• 消息的存储标记

客户端SDK在接收到消息后，会根据这些属性决定是否将消息存入本地数据库。理解这些机制对于构建稳定可靠的即时通讯应用至关重要。

通过合理配置消息属性和选择适当的发送方式，开发者可以灵活控制消息的存储行为，满足不同场景下的业务需求。