消息介绍

消息基本结构

属性名	类型	说明
`conversationType`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	所属会话的业务标识，长度限制 20 字符，仅在超级群下生效
`messageType`	`RCIMIWMessageType`	消息的类型
`messageId`	`int`	本地存储的消息的唯一值（数据库索引唯一值）
`messageUId`	`String`	服务器消息唯一 ID（在同一个 App Key 下全局唯一）
`direction`	`RCIMIWMessageDirection`	消息的方向
`receivedTime`	`int`	消息的接收时间（Unix 时间戳、毫秒）
`sentTime`	`int`	消息的发送时间（Unix 时间戳、毫秒）
`receivedStatus`	`RCIMIWReceivedStatus`	消息的接收状态
`sentStatus`	`RCIMIWSentStatus`	消息的发送状态
`senderUserId`	`String`	消息的发送者 ID
`expansion`	`Map`	消息扩展信息列表，该属性在消息发送时确定，发送之后不能再做修改。扩展信息只支持单聊和群组，其他会话类型不能设置扩展信息。默认消息扩展字典 `key` 长度不超过 32，`value` 长度不超过 4096，单次设置扩展数量最大为 20，消息的扩展总数不能超过 300
`offLine`	`bool`	是否是离线消息(用户离线期间收到的消息)，只在接收消息的回调方法中有效，如果消息为离线消息，则为 `true`，其他情况均为 `false`
`groupReadReceiptInfo`	`RCIMIWGroupReadReceiptInfo`	群阅读回执状态
`userInfo`	`RCIMIWUserInfo`	消息携带的用户信息
`mentionedInfo`	`RCIMIWMentionedInfo`	消息的 @ 信息
`pushOptions`	`RCIMIWMessagePushOptions`	消息推送配置，仅可在发送方进行配置，接收方为空
`extra`	`String`	消息的附加字段，设置后接收方收到消息后也可以拿到数据。
`needReceipt`	`bool`	消息已读回执操作标识。该属性在 SDK 5.20.0 版本开始支持，详情请参考逐条消息已读功能。
`sentReceipt`	`bool`	已读回执是否已发送。该属性在 SDK 5.20.0 版本开始支持，详情请参考逐条消息已读功能。

消息类型与构造方法

IMLib 的消息类型（RCIMIWMessageType）枚举提供了预定义的文本、语音、图片等消息类型，并且支持 App 通过 RCIMIWMessageType.nativeCustom 实现自定义消息。

各类型消息默认会在客户端本地存储，计入未读消息数。以下类型除外：

撤回消息类型（RCIMIWMessageType.recall）：客户端本地存储，但不计入未读消息数
命令消息类型（RCIMIWMessageType.command）：客户端不进行本地存储，不计入未读消息数
命令通知消息类型（RCIMIWMessageType.commandNotification）：客户端本地存储，不计入未读消息数。
自定义消息类型（RCIMIWMessageType.custom）：由 App 自定义存储策略（RCIMIWCustomMessagePolicy）进行控制。
原生自定义普通消息类型（RCIMIWMessageType.nativeCustom）：消息的存储策略由 App 注册原生自定义消息的 RCIMIWNativeCustomMessagePersistentFlag 进行控制。
原生自定义媒体消息类型（RCIMIWMessageType.nativeCustomMedia）：消息的存储策略由 App 注册原生自定义媒体消息的 RCIMIWNativeCustomMessagePersistentFlag 进行控制。

提示

从 5.12.1 版本开始支持原生自定义消息。自定义消息与原生自定义消息类型区别如下：

自定义消息类型：跨平台提供的自定义消息包装类型，用户的自定义消息类型在底层被包装了一次，无法与原生 iOS、Android SDK 注册的自定义消息互通。
原生自定义消息类型：支持与原生 iOS、Android SDK 注册的自定义消息互通。

如何选择自定义消息类型

如果您的自定义消息需要与 Android、iOS 原生 SDK 或服务端 objectName 保持一致，优先使用 registerNativeCustomMessage + createNativeCustomMessage。如果自定义消息需要携带本地媒体文件，使用 registerNativeCustomMediaMessage + createNativeCustomMediaMessage。

消息类型	构建接口	适用场景	是否支持与原生 Android/iOS SDK 互通
`RCIMIWMessageType.custom`	`createCustomMessage`	Flutter 跨平台包装类型，适合仅在 Flutter 端内部使用的自定义消息。	否
`RCIMIWMessageType.nativeCustom`	`registerNativeCustomMessage` + `createNativeCustomMessage`	原生自定义普通消息，适合需要与原生 Android/iOS SDK 或服务端 `objectName` 对齐的普通业务消息。多端互通场景优先使用。	是
`RCIMIWMessageType.nativeCustomMedia`	`registerNativeCustomMediaMessage` + `createNativeCustomMediaMessage`	原生自定义媒体消息，适合需要携带本地媒体文件的自定义消息。	是

常见问题

多端互通应该使用哪个接口？

如果需要 Flutter 与原生 Android、iOS SDK 互通，普通自定义消息使用 registerNativeCustomMessage + createNativeCustomMessage；媒体自定义消息使用 registerNativeCustomMediaMessage + createNativeCustomMediaMessage。不建议在多端互通场景使用 createCustomMessage。

custom 和 nativeCustom 的核心区别是什么？

custom 是 Flutter SDK 提供的跨平台包装类型，消息内容会在底层被包装一次，不能与原生 Android、iOS SDK 注册的自定义消息直接互通。nativeCustom 使用原生自定义消息机制，messageIdentifier 可与服务端 objectName 对齐，适合多端互通。

什么时候使用 nativeCustomMedia？

当自定义消息需要携带本地媒体文件时，使用 nativeCustomMedia。如果消息只包含业务字段，例如订单、礼物、通知等普通结构化数据，使用 nativeCustom。

为什么必须在初始化之后、连接之前注册原生自定义消息？

SDK 需要在连接和收发消息前知道自定义消息的 messageIdentifier 和存储策略。若未提前注册，客户端收到该类型消息后可能无法正确解析、存储或展示。

messageIdentifier 和服务端 objectName 是什么关系？

messageIdentifier 对应服务端的 objectName，用于唯一标识自定义消息类型。需要多端互通时，各端和服务端应使用同一个标识，并避免使用 RC: 开头的融云官方保留前缀。

文本消息

类型：RCIMIWMessageType.text

专有可访问属性：

属性名	类型	说明
`text`	`String`	文本内容

构建文本消息

Dart
RCIMIWTextMessage? message = await engine.createTextMessage(
      type,
      targetId,
      channelId,
      text,
    );

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`text`	`String`	文本内容

语音消息

提示

语音消息推荐录制格式为 AAC，录制比特率需不低于 56 kbps，以保证音质和兼容性。

类型：RCIMIWMessageType.voice

专有可访问属性：

属性名	类型	说明
`duration`	`int`	语音的长度，单位：秒

构建语音消息

Dart
RCIMIWVoiceMessage? message = await engine.createVoiceMessage(
      type,
      targetId,
      channelId,
      path,
      duration,
    );

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`path`	`String`	语音消息的本地路径，必须为有效路径
`duration`	`int`	语音消息的消息时长

图片消息

类型：RCIMIWMessageType.image

专有可访问属性：

属性名	类型	说明
`thumbnailBase64String`	`String`	图片的缩略图数据
`thumWidth`	`int`	缩略图宽度（像素）
`thumHeight`	`int`	缩略图高度（像素）
`original`	`bool`	是否为原图

构建图片消息

Dart
RCIMIWImageMessage? message = await engine.createImageMessage(
          type,
          targetId,
          channelId,
          path,
        );

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`path`	`String`	图片消息的本地路径，必须为有效路径

文件消息

类型：RCIMIWMessageType.file

专有可访问属性：

属性名	类型	说明
`name`	`String`	文件名
`fileType`	`String`	文件类型
`size`	`int`	文件大小，单位为 Byte

构建文件消息

Dart
RCIMIWFileMessage? message = await engine.createFileMessage(
      type,
      targetId,
      channelId,
      path,
    );

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`path`	`String`	文件消息的本地路径，必须为有效路径

小视频消息

类型：RCIMIWMessageType.sight

专有可访问属性：

属性名	类型	说明
`duration`	`int`	视频时长
`size`	`int`	视频大小
`name`	`String`	视频的名称
`thumbnailBase64String`	`String`	缩略图数据

构建小视频消息

Dart
RCIMIWSightMessage? message = await engine.createSightMessage(
      type,
      targetId,
      channelId,
      path,
      duration,
    );

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`path`	`String`	小视频消息的本地路径，必须为有效路径
`duration`	`int`	小视频消息的视频时长，请注意服务端的默认视频时长上限为 2 分钟。若需调整上限，请联系商务。

GIF 图消息

类型：RCIMIWMessageType.gif

专有可访问属性：

属性名	类型	说明
`dataSize`	`int`	GIF 图的大小，单位字节
`width`	`int`	GIF 图的宽
`height`	`int`	GIF 图的高

构建 GIF 消息

Dart
RCIMIWGIFMessage? message = await engine.createGIFMessage(
      type,
      targetId,
      channelId,
      path
    );

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`path`	`String`	GIF 消息的本地路径

撤回消息

撤回消息不可以主动构建发送，需要撤回消息请调用撤回消息接口。

类型：RCIMIWMessageType.recall

专有可访问属性：

属性名	类型	说明
`admin`	`bool`	是否是管理员操作
`deleted`	`bool`	是否删除
`recallTime`	`int`	被撤回的原始消息的发送时间（毫秒）
`recallActionTime`	`int`	撤回动作的时间（毫秒）
`originalMessage`	`RCIMIWMessage`	被撤回的原消息

引用消息

类型：RCIMIWMessageType.reference

专有可访问属性：

属性名	类型	说明
`text`	`String`	引用文本
`referenceMessage`	`RCIMIWMessage`	被引用的消息

构建引用消息

Dart
RCIMIWReferenceMessage? message = await engine.createReferenceMessage(
      type,
      targetId,
      channelId,
      referenceMessage,
      text,
    );

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`referenceMessage`	`RCIMIWMessage`	引用的消息
`text`	`String`	引用的文本内容

位置消息

类型：RCIMIWMessageType.location

专有可访问属性：

属性名	类型	说明
`longitude`	`double`	经度信息
`latitude`	`double`	纬度信息
`poiName`	`String`	POI 信息
`thumbnailPath`	`String`	缩略图地址

构建位置消息

Dart
RCIMIWLocationMessage? message = await engine.createLocationMessage(
      type,
      targetId,
      channelId,
      longitude,
      latitude,
      poiName,
      thumbnailPath,
    );

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`longitude`	`double`	经度
`latitude`	`double`	纬度
`poiName`	`String`	POI 信息
`thumbnailPath`	`String`	缩略图本地路径，必须为有效路径

命令消息

类型：RCIMIWMessageType.command

专有可访问属性：

属性名	类型	说明
`name`	`String`	命令的名称
`data`	`String`	命令的扩展数据，可以为任意字符串，如存放您定义的 JSON 数据。

Flutter SDK 目前不提供 RCIMIWCommandMessage 命令消息的 create 方法，仅支持接收该类型消息。如需要在客户端发送此消息，需要在 Flutter 层先定义此消息的包装类。详见知识库文档Flutter SDK 如何发送命令消息和命令通知消息？。

命令通知消息

类型：RCIMIWMessageType.commandNotification

专有可访问属性：

属性名	类型	说明
`name`	`String`	命令提醒的名称
`data`	`String`	命令提醒消息的扩展数据，可以为任意字符串，如存放您定义的 JSON 数据。

Flutter SDK 目前不提供 RCIMIWCommandNotificationMessage 命令通知消息的 create 方法，仅支持接收该类型消息。如需要在客户端发送此消息，需要在 Flutter 层先定义此消息的包装类。详见知识库文档Flutter SDK 如何发送命令消息和命令通知消息？。

群组通知消息

类型：RCIMIWMessageType.groupNotification

群组通知消息用于群组相关操作的通知，如成员加入、退出、群组解散等。

专有可访问属性：

属性名	类型	说明
`operation`	`String`	操作类型
`operatorUserId`	`String`	操作者用户 ID
`data`	`String`	操作相关的数据
`message`	`String`	操作的消息内容

提示

群组通知消息通常由服务端在群组操作时自动发送，客户端主要用于接收和解析这些通知。Flutter SDK 目前不提供创建群组通知消息的方法。

自定义消息

类型：RCIMIWMessageType.custom

专有可访问属性：

属性名	类型	说明
`identifier`	`String`	自定义消息的标识符
`policy`	`RCIMIWCustomMessagePolicy`	自定义的消息存储策略
`fields`	Map<String, String>	自定义消息的键值对

构建自定义消息

Dart
RCIMIWCustomMessage? message = await engine.createCustomMessage(
      type,
      targetId,
      channelId,
      policy,
      messageIdentifier,
      fields,
    );

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	`String`	会话 ID
`channelId`	`String`	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`policy`	`RCIMIWCustomMessagePolicy`	消息的存储策略
`messageIdentifier`	`String`	消息的标识符，需唯一
`fields`	Map<String, String>	消息的内容键值对

原生自定义普通消息

原生自定义消息注册后，可与其他平台注册的自定义消息互通。

类型：RCIMIWMessageType.nativeCustom

专有可访问属性：

属性名	类型	说明
`fields`	Map?	自定义消息的内容键值对
`searchableWords`	List<String>?	自定义消息的搜索关键字
`messageIdentifier`	String?	自定义消息的唯一标识符（详见下方说明）

messageIdentifier 命名规范

messageIdentifier 对应服务端的 objectName 参数，用于唯一标识自定义消息类型。命名时请遵循以下规范：

格式要求：建议使用格式 前缀:消息类型，例如 app:txtcontent
长度限制：建议控制在 16 字符以内，以减少对消息体积的影响
命名限制：
- ❌ 不要以 RC: 开头（RC: 为融云官方保留前缀）
- ❌ 避免使用融云内置消息标识符，否则会导致消息冲突
示例：
- ✅ app:order - 订单消息
- ✅ custom:gift - 礼物消息
- ✅ myapp:notice - 通知消息
- ❌ RC:TxtMsg - 错误：使用了保留前缀

构建原生自定义普通消息

提示

原生自定义普通消息需要在 IM 初始化之后，连接之前调用 registerNativeCustomMessage 方法注册。

注册原生自定义消息

Dart

int? code = await engine.registerNativeCustomMessage(messageIdentifier, persistentFlag);

参数名	参数类型	描述
`messageIdentifier`	`String`	消息的唯一标识
`persistentFlag`	`RCIMIWNativeCustomMessagePersistentFlag`	消息的存储策略

构建原生自定义消息

Dart

RCIMIWNativeCustomMessage? customMessage = await engine.createNativeCustomMessage(type, targetId, channelId, messageIdentifier, fields);

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	String?	会话 ID
`channelId`	String?	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`messageIdentifier`	`String`	消息的标识符，需唯一
`fields`	`Map`	消息的内容键值对

原生自定义媒体消息

类型：RCIMIWMessageType.nativeCustomMedia

专有可访问属性：

属性名	类型	说明
`fields`	Map?	自定义消息的内容
`searchableWords`	List<String>?	自定义消息的搜索关键字
`messageIdentifier`	`String`	自定义消息的唯一标识

构建原生自定义媒体消息

提示

原生自定义媒体消息需要在 IM 初始化之后，连接之前调用 registerNativeCustomMediaMessage 方法注册。

注册原生自定义媒体消息

Dart

int? code = await engine.registerNativeCustomMediaMessage(messageIdentifier, persistentFlag);

参数名	参数类型	描述
`messageIdentifier`	`String`	消息的唯一标识
`persistentFlag`	`RCIMIWNativeCustomMessagePersistentFlag`	消息的存储策略

构建原生自定义媒体消息

Dart

RCIMIWNativeCustomMediaMessage? customMediaMessage = await engine.createNativeCustomMediaMessage(type, targetId, channelId, messageIdentifier, path, fields);

参数名	参数类型	描述
`type`	`RCIMIWConversationType`	会话类型
`targetId`	String?	会话 ID
`channelId`	String?	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
`messageIdentifier`	`String`	消息的标识符，需唯一
`path`	`String`	媒体文件的本地路径，必须为有效路径
`fields`	`Map`	消息的内容键值对

无效类型

当接收到无法识别的消息时，会变为无效类型的消息，此消息不可主动构建发送

类型：RCIMIWMessageType.unknown

专有可访问属性：

属性名	类型	描述
`rawData`	`String`	消息数据
`objectName`	`String`	消息的标识

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

北极星数据查询

消息基本结构​

消息类型与构造方法​

如何选择自定义消息类型​

常见问题​

文本消息​

构建文本消息​

语音消息​

构建语音消息​

图片消息​

构建图片消息​

文件消息​

构建文件消息​

小视频消息​

构建小视频消息​

GIF 图消息​

构建 GIF 消息​

撤回消息​

引用消息​

构建引用消息​

位置消息​

构建位置消息​

命令消息​

命令通知消息​

群组通知消息​

自定义消息​

构建自定义消息​

原生自定义普通消息​

构建原生自定义普通消息​

注册原生自定义消息​

构建原生自定义消息​

原生自定义媒体消息​

构建原生自定义媒体消息​

注册原生自定义媒体消息​

构建原生自定义媒体消息​

无效类型​

消息基本结构

消息类型与构造方法

如何选择自定义消息类型

常见问题

文本消息

构建文本消息

语音消息

构建语音消息

图片消息

构建图片消息

文件消息

构建文件消息

小视频消息

构建小视频消息

GIF 图消息

构建 GIF 消息

撤回消息

引用消息

构建引用消息

位置消息

构建位置消息

命令消息

命令通知消息

群组通知消息

自定义消息

构建自定义消息

原生自定义普通消息

构建原生自定义普通消息

注册原生自定义消息

构建原生自定义消息

原生自定义媒体消息

构建原生自定义媒体消息

注册原生自定义媒体消息

构建原生自定义媒体消息

无效类型