发送消息
本文介绍了 IMLib 如何发送消息。
客户端 SDK 发送消息存在频率限制，每秒最多只能发 送 5 条消息。
2026 年 5 月 29 日起，新注册客户的除图片消息（RC:ImgMsg）、流式消息（RC:StreamMsg）、语音消息（RC:VcMsg）、视频消息（RC:SightMsg）、位置消息（RC:LBSMsg）、合并转发消息（RC:CombineV2Msg，RC:CombineMsg）、引用消息（RC:ReferenceMsg）外，其他消息的 content 消息体大小限制不超过 10 KB。
前置条件
在发送消息前，需完成以下前置条件：
- 完成 SDK 初始化
需先完成融云 SDK 的初始化配置，确保应用已正确集成融云服务并完成基础参数设置(如 App Key 等)。具体操作请参考 SDK 初始化指南。
- 建立与融云服务端的连接
确保客户端已通过有效 Token 成功连接至融云服务端。连接状态可通过监听 SDK 提供的连接状态回调判断。若连接失败，需排查 Token 有效性、网络环境等问题。
- 创建待发送的消息实体
根据消息类型(如文本、图片、语音等)，创建对应的消息对象。具体可参考消息介绍，了解各类消息的构造方法及参数要求(如 RCIMIWTextMessage 的文本内容、RCIMIWImageMessage 的图片路径等)。
完成以上步骤后，方可调用融云 SDK 的消息发送接口(如 sendMessage)执行消息发送操作。
发送普通消息
开发者在发送文本消息、引用消息、自定义消息时，可以使用下面接口发送。
方法
Future<int> sendMessage(RCIMIWMessage message, {RCIMIWSendMessageCallback? callback});
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
message | RCIMIWMessage | 发送的消息实体 |
callback | RCIMIWSendMessageCallback | 发送消息的事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数，仅触发 callback 回调。 |
返回值
| 返回值 | 描述 |
|---|---|
| Future<int> | 当次接口操作的状态码。0 代表接口调用成功，具体业务结果需要从接口回调获取，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码 |
代码示例
以下示例中，message 是通过前置条件第三步创建的消息实体，engine 是已初始化的 RCIMIWEngine 实例。
RCIMIWSendMessageCallback? callback = RCIMIWSendMessageCallback(
onMessageSaved: (RCIMIWMessage? message) {
//...
}, onMessageSent: (int? code, RCIMIWMessage? message) {
//...
});
int? ret = await engine?.sendMessage(message, callback);
发送时开启逐条消息已读（V5）
如果需要让接收方对单条消息发送已读回执，发送前请将消息对象的 needReceipt 设为 true：
message.needReceipt = true;
await engine.sendMessage(message, callback: callback);
详细流程(发送回执、监听回执、查询已读用户)请参考逐条消息已读功能。
发送媒体消息
开发者在发送图片消息、语音消息、视频消息、文件消息、GIF 消息时，可以使用下面接口发送。
方法
Future<int> sendMediaMessage(RCIMIWMediaMessage message, {RCIMIWSendMediaMessageListener? listener});
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
message | RCIMIWMediaMessage | 发送的媒体消息实体 |
listener | RCIMIWSendMediaMessageListener | 发送媒体消息的事件监听 |
返回值
| 返回值 | 描述 |
|---|---|
| Future<int> | 当次接口操作的状态码。0 代表接口调用成功，具体业务结果需要从接口回调获取，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码 |
代码示例
RCIMIWSendMediaMessageListener? listener = RCIMIWSendMediaMessageListener(
onMediaMessageSaved: (RCIMIWMediaMessage? message) {
//...
},
onMediaMessageSending: (RCIMIWMediaMessage? message, int? progress) {
//...
},
onSendingMediaMessageCanceled: (RCIMIWMediaMessage? message) {
//...
},
onMediaMessageSent: (int? code, RCIMIWMediaMessage? message) {
//...
});
int? ret = await engine?.sendMediaMessage(message, listener);
如何处理消息发送失败
对于客户端本地会存储的消息类型（参见消息介绍），如果触发消息入库的回调（onMessageSaved / onMediaMessageSaved），表示此时该消息已存入本地数据库，并已进入本地消息列表。
- 如果入库成功后消息发送失败（未能触发
onMessageSent/onMediaMessageSent），App 可以在 UI 临时展示这条发送失败的消息，并缓存onMessageSaved抛出的消息实例，在合适的时机重新调用sendMessage/sendMediaMessage发送。请注意，如果不复用该消息实例，而是重发相同内容的新消息，本地消息列表中会存储内容重复的两条消息。 - 如果入库失败，您可以检查参数是否合法，设备存储是否可正常写入。
对于客户端本地不存储的消息，如果发送失败（未能触发 onMessageSent/onMediaMessageSent），App 可缓存消息实例再重试发送，或直接新建消息实例进行发送。
如何实现转发、群发消息
转发消息：IMLib SDK 未提供转发消息接口。App 实现转发消息效果时，可调用发送消息接口发送。
群发消息：群发消息是指向多个用户发送消息。更准确地说，是向多个 Target ID?发送消息，一个 Target ID 可能代表一个用户，一个群组，或一个聊天室。客户端 SDK 未提供直接实现群发消息效果的 API。您可以考虑以下实现方式：