消息介绍

消息基本结构

属性名	类型	说明
conversationType	RCIMIWConversationType	会话类型
messageType	RCIMIWMessageType	消息的类型
targetId	string	会话 ID
channelId	string	所属会话的业务标识，长度限制 20 字符
messageId	number	本地数据库中存储的消息的唯一 ID 值。发送新消息时无需指定该 ID，否则会导致消息入库失败。在失败重发消息时，可以填入已入库的消息的 ID，请确保使用上一次发送失败的消息实例。
messageUId	string	服务器消息唯一 ID（在同一个 Appkey 下全局唯一）
offLine	boolean	是否是离线消息，只在接收消息的回调方法中有效，如果消息为离线消息，则为 YES ，其他情况均为 NO
groupReadReceiptInfo	RCIMIWGroupReadReceiptInfo	群阅读回执状态
receivedTime	number	消息的接收时间（Unix 时间戳、毫秒）
sentTime	number	消息的发送时间（Unix 时间戳、毫秒）
receivedStatus	RCIMIWReceivedStatus	消息的接收状态
sentStatus	RCIMIWSentStatus	消息的发送状态
senderUserId	string	消息的发送者 ID
direction	RCIMIWMessageDirection	消息的方向
userInfo	RCIMIWUserInfo	消息携带的用户信息
mentionedInfo	RCIMIWMentionedInfo	消息的 @ 信息
pushOptions	RCIMIWMessagePushOptions	消息推送配置
extra	string	消息的附加字段
expansion	Map<string, string>	消息扩展信息列表，该属性在消息发送时确定，发送之后不能再做修改扩展信息只支持单聊和群组，其它会话类型不能设置扩展信息默认消息扩展字典 key 长度不超过 32 ，value 长度不超过 4096 ，单次设置扩展数量最大为 20，消息的扩展总数不能超过 300

消息类型

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

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

撤回消息类型（RCIMIWMessageType.recall）：客户端本地存储，但不计入未读消息数
命令消息类型（RCIMIWMessageType.command）：客户端不进行本地存储，不计入未读消息数
命令通知消息类型（RCIMIWMessageType.commandNotification）：客户端本地存储，不计入未读消息数。
自定义消息类型（RCIMIWMessageType.custom）：由 App 自定义存储策略（RCIMIWCustomMessagePolicy）进行控制。
原生自定义普通消息类型（RCIMIWMessageType.nativeCustom）：消息的存储策略由 App 注册原生自定义消息的 RCIMIWNativeCustomMessagePersistentFlag 进行控制。
原生自定义媒体消息类型（RCIMIWMessageType.nativeCustomMedia）：消息的存储策略由 App 注册原生自定义媒体消息的 RCIMIWNativeCustomMessagePersistentFlag 进行控制。消息可携带本地媒体文件，SDK 会在发送时将文件自动上传到服务端。

自定义消息与原生自定义消息类型区别：

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

提示

原生自定义消息 5.12.1 版本及以上支持。

文本消息

类型：RCIMIWMessageType.text

专有可访问属性：

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

构建文本消息

TypeScript
let message = await engine.createTextMessage(
      type,
      targetId,
      channelId,
      text,
    );

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

语音消息

类型：RCIMIWMessageType.voice

专有可访问属性：

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

构建语音消息

TypeScript
recorderManager.onStop(async function (res) {
  //转为平台路径
  let path = 'file:///' + plus.io.convertLocalFileSystemURL(res.tempFilePath);
  let message = await engine.createVoiceMessage(type, targetId, channelId, path, duration);
})

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

图片消息

类型：RCIMIWMessageType.image

专有可访问属性：

属性名	类型	说明
thumbnailBase64String	string	图片的缩略图数据
original	boolean	是否为原图

构建图片消息

TypeScript
uni.chooseImage({
  count: 1,
  success: async (res) => {
    if (res.tempFilePaths.length < 0) return;
    //转为平台路径
    let path = 'file:///' + plus.io.convertLocalFileSystemURL(res.tempFilePaths[0])
    //创建图片消息
    let 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	number	文件大小，单位为 Byte

构建文件消息

TypeScript
//项目本地路径：前面加www是因为手机存储中生成的项目对应的该文件前面有www文件夹,请根据自身情况使用可找到文件的路径并转为平台路径
const path = 'file://' + plus.io.convertLocalFileSystemURL('../www/static/assets/sendFileMessage.docx');
//创建文件消息
let message = await engine.createFileMessage(type,targetId,channelId,path);

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

小视频消息

类型：RCIMIWMessageType.sight

专有可访问属性：

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

构建小视频消息

TypeScript
//选择视频
uni.chooseVideo({
  count: 1,
  sourceType: ['album', 'camera'],
  success: async (res) => {
    const duration = parseInt(res.duration);
    const path = plus.io.convertLocalFileSystemURL(res.tempFilePath);
    //创建消息
    let message = await engine.createSightMessage(type, targetId, channelId, path, duration);
    //发送消息
    let code = await engine.sendMediaMessage(message);
  }
});

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

GIF图消息

类型：RCIMIWMessageType.gif

专有可访问属性：

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

构建 GIF 消息

TypeScript
uni.chooseImage({
  count: 1,
  success: async (res) => {
    if (res.tempFilePaths.length < 0) return;
    // 转为平台路径
    const path = 'file:///' + plus.io.convertLocalFileSystemURL(res.tempFilePaths[0]);
    // 创建消息
    let message = await engine.createGIFMessage(type, targetId, channelId, path);
  }
});

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

撤回消息

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

类型：RCIMIWMessageType.recall

专有可访问属性：

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

引用消息

类型：RCIMIWMessageType.reference

专有可访问属性：

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

构建引用消息

TypeScript
let 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	number	经度信息
latitude	number	纬度信息
poiName	string	POI 信息
thumbnailPath	string	缩略图地址

构建位置消息

TypeScript
let message = await engine.createLocationMessage(
      type,
      targetId
      channelId,
      longitude,
      latitude,
      poiName,
      path, // 缩略图本地平台路径
    );

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

命令消息

类型：RCIMIWMessageType.command

专有可访问属性：

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

命令通知消息

类型：RCIMIWMessageType.commandNotification

专有可访问属性：

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

自定义消息

类型：RCIMIWMessageType.custom

专有可访问属性：

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

构建自定义消息

TypeScript
let message = await engine.createCustomMessage(
      type,
      targetId,
      channelId,
      policy,
      messageIdentifier,
      fields,
    );

参数名	参数类型	描述
type	RCIMIWConversationType	会话类型
targetId	string	会话 ID
channelId	string	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
policy	RCIMIWCustomMessagePolicy	消息的存储策略
messageIdentifier	string	消息的标识符，需唯一
fields	{ [propName: string]: Object; }	消息的内容键值对

原生自定义普通消息

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

类型：RCIMIWMessageType.nativeCustom

专有可访问属性：

属性名	类型	说明
fields	{ [propName: string]: Object; }	自定义消息的内容
searchableWords	Array<string>	自定义消息的搜索关键字
messageIdentifier	string	自定义消息的唯一标识

构建原生自定义普通消息

提示

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

注册原生自定义消息

TypeScript

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

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

构建原生自定义消息

TypeScript

let code = await engine.createNativeCustomMessage(
  type, targetId, channelId, messageIdentifier, fields);

参数名	参数类型	描述
type	RCIMIWConversationType	会话类型
targetId	string	会话 ID
channelId	string	频道 ID，仅支持超级群使用，其他会话类型传 null 即可。
messageIdentifier	string	消息的标识符，需唯一
fields	{ [propName: string]: Object; }	消息的内容键值对

提示

fields 字段使用规范说明

以下字段为 SDK 内部保留字段，禁止开发者直接在 fields 对象的一级字段中使用，否则会被 SDK 主动丢弃： name, user, extra, audit, localPath, remoteUrl, burnDuration, mentionedInfo

注意：保留字段仅禁止用于一级字段，通过二级对象封装可正常使用。一级字段若使用保留字段，SDK 会静默过滤且不产生错误提示。

建议开发者将自定义字段统一封装到二级对象中，例如：

fields = {
    "customContent": {  # 自定义字段容器
        "user": "user1",              # 自定义用户字段
        "burnDuration": 10,           # 自定义阅后即焚时长
        "extra": "extra",             # 自定义扩展信息
        "mentionedInfo": "@all",      # 自定义提及信息
        "audit": "pending",           # 自定义审核状态
        "otherKey": "otherValue"      # 其他自定义字段
    }
}

原生自定义媒体消息

类型：RCIMIWMessageType.nativeCustomMedia

专有可访问属性：

属性名	类型	说明
fields	{ [propName: string]: Object; }	自定义消息的内容
searchableWords	Array<string>	自定义消息的搜索关键字
messageIdentifier	string	自定义消息的唯一标识

构建原生自定义媒体消息

提示

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

注册原生自定义媒体消息

TypeScript

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

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

构建原生自定义媒体消息

TypeScript

let code = await engine.createNativeCustomMediaMessage(
  type, targetId, channelId, messageIdentifier, path, fields);

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

无效类型

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

类型：RCIMIWMessageType.unknown

专有可访问属性：

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

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

Global IM UIKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

验证码短信

消息基本结构​

消息类型​

文本消息​

构建文本消息​

语音消息​

构建语音消息​

图片消息​

构建图片消息​

文件消息​

构建文件消息​

小视频消息​

构建小视频消息​

GIF图消息​

构建 GIF 消息​

撤回消息​

引用消息​

构建引用消息​

位置消息​

构建位置消息​

命令消息​

命令通知消息​

自定义消息​

构建自定义消息​

原生自定义普通消息​

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

注册原生自定义消息​

构建原生自定义消息​

原生自定义媒体消息​

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

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

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

无效类型​

消息基本结构

消息类型

文本消息

构建文本消息

语音消息

构建语音消息

图片消息

构建图片消息

文件消息

构建文件消息

小视频消息

构建小视频消息

GIF图消息

构建 GIF 消息

撤回消息

引用消息

构建引用消息

位置消息

构建位置消息

命令消息

命令通知消息

自定义消息

构建自定义消息

原生自定义普通消息

构建原生自定义普通消息

注册原生自定义消息

构建原生自定义消息

原生自定义媒体消息

构建原生自定义媒体消息

注册原生自定义媒体消息

构建原生自定义媒体消息

无效类型