跳到主要内容

收发消息

本文介绍了如何从客户端发送超级群消息。

前置条件​

建议先阅读超级群概述和超级群私有频道概述，了解在 App 业务中如何使用频道和超级群频道功能特性。

发送消息​

基础接口 sendMessage 可用来发送所有自定义消息或 IMLib 中的内置类型消息。如发送文件、图片、高清语音、小视频、动图类型消息，可参见下文描述的语法糖方法。

注意

2026 年 5 月 29 日起，新注册客户的除图片消息（RC:ImgMsg）、流式消息（RC:StreamMsg）、语音消息（RC:VcMsg）、视频消息（RC:SightMsg）、位置消息（RC:LBSMsg）、合并转发消息（RC:CombineV2Msg，RC:CombineMsg）、引用消息（RC:ReferenceMsg）外，其他消息的 content 消息体大小限制不超过 10 KB。实际限制以连接成功后 getAppSettings 返回的 AppSettings.messageSizeLimit 为准。消息体大小按消息 content 序列化为 JSON 后的字节数计算。

sendMessage 方法接收 conversation、message 与 options 三个参数：

  • conversation： 消息需要投送的目标会话。参见 IConversationOption。

    参数类型说明
    conversationTypeConversationType会话类型（RongIMLib.ConversationType.ULTRA_GROUP）
    targetIdstring接收方 Id
    channelIdstring频道 Id（可选项）

  • message：待发送的消息内容，可以是如 RongIMLib.TextMessage 的 IMLib 内置消息实例，也可以是通过 RongIMLib.registerMessageType() 实现的自定义消息实例。

  • options：可选参数，用于定义发送行为中的一些可选项，如是否可扩展，推送等。参见 ISendMessageOptions。

    options 参数类型说明
    isStatusMessageboolean（已废弃）是否为状态消息（可选项）
    disableNotificationboolean是否发送静默消息（可选项）
    pushContentstringPush 信息（可选项）
    pushDatastringPush 通知携带的附加信息（可选项）
    isMentionedboolean是否为 @ 消息（可选项）
    mentionedType1｜2@ 消息类型，1: @ 所有人 2: @ 指定用户（可选项）
    mentionedUserIdListstring[]被 @ 的用户 Id 列表（可选项）
    directionalUserIdListstring[]用于发送普通群组定向消息，超级群暂不支持该功能。
    isVoipPushboolean当对方为 iOS 设备且未在线时，其将收到 Voip Push. 此配置对 Android 无影响（可选项）
    canIncludeExpansionboolean是否允许消息被拓展
    expansion[key: string]: string消息拓展内容数据（可选项）
    isFilerWhiteBlacklistboolean黑/白名单（可选项）
    pushConfigIPushConfig移动端推送配置（可选项）（与 Android、iOS 端的 MessagePushConfig 作用相似）。详见下方的 IPushConfig 参数说明。

    • IPushConfig 参数说明

      参数类型说明
      pushTitlestring推送标题，在没有设置的情况下：单聊通知标题显示为发送者名称，群聊通知标题显示为群名称；自定义消息，默认不显示标题；
      pushContentstring推送内容
      pushDatastring远程推送附加信息
      iOSConfigIiOSPushConfig（可选项）
      androidConfigIAndroidPushConfig（可选项）
      disablePushTitleboolean是否显示推送标题. 仅针对 iOS 平台有效
      forceShowDetailContentboolean是否强制推送
      templateIdstring推送模板 ID

代码示例

以发送文本消息为例：

javascript
// 定义消息投送目标会话
const conversation = {
  conversationType: RongIMLib.ConversationType.ULTRA_GROUP,
  targetId: '<目标 Id>',
  channelId: '<频道ID>',
}
// 实例化待发送消息，RongIMLib.TextMessage 为内置文本型消息
const message = new RongIMLib.TextMessage({ content: '' })
// 发送
RongIMLib.sendMessage(conversation, message).then((res) => {})

语法糖​

发送 FileMessage、ImageMessage、HQVoiceMessage、SightMessage、GIFMessage 五种消息时，在构建消息实例过程中均需要一个远程资源地，这意味着业务层需要将待发送的本地资源先行上传，再构建消息实例，过程较为复杂。

为此，IMLib 实现了相应的语法糖方法以封装本地资源的上传过程、以及消息构建过程，便于业务层更易于集成。

发送文件消息​

javascript
RongIMLib.sendFileMessage(
  {
    conversationType: RongIMLib.ConversationType.ULTRA_GROUP,
    targetId: '',
    channelId: '',
  },
  {
    file, // 待上传文件
    user: { id: '', name: '', portraitUri: '', extra: '' }, // 消息中携带的用户信息，非必填
    extra: '', // 消息中携带的透传信息，非必填
  },
  {
    onProgress(progress) {}, // 上传进度监听，可选
    onComplete(fileInfo) {
      // 上传完成时的回调钩子，可选
      console.log(fileInfo.url) // 文件存储地址
      // 如果需要构建自定义消息，return new ABCMesssage('')
      // ABCMesssage 定义通过自定义消息实现 `const ABCMesssage = RongIMLib.registerMessageType(...)`
      // 无 return 返回值的情况下，SDK 默认发送 FileMessage
    },
  },
  {
    // ... 其他配置项，可选
  }
).then(({ code, data: message }) => {
  if (code === 0) {
    // 发送成功
  }
})

发送图片消息​

javascript
RongIMLib.sendImageMessage(
  {
    conversationType: RongIMLib.ConversationType.ULTRA_GROUP,
    targetId: '',
    channelId: '',
  },
  {
    file, // 待上传文件
    user: { id: '', name: '', portraitUri: '', extra: '' }, // 消息中携带的用户信息，非必填
    extra: '', // 消息中携带的透传信息，非必填
  },
  {
    onProgress(progress) {}, // 上传进度监听，可选
    onComplete(fileInfo) {
      // 上传完成时的回调钩子，可选
      console.log(fileInfo.url) // 文件存储地址
      // 如果需要构建自定义消息，return new ABCMesssage('')
      // ABCMesssage 定义通过自定义消息实现 `const ABCMesssage = RongIMLib.registerMessageType(...)`
      // 无 return 返回值的情况下，SDK 默认发送 ImageMessage
    },
  },
  {
    // ... 其他配置项，可选
  }
).then(({ code, data: message }) => {
  if (code === 0) {
    // 发送成功
  }
})

发送高清语音消息​

提示

如果您的业务同时使用了 Android/iOS 端的 IMKit SDK，请使用默认的 aac 格式，因为 IMKit 的音频录制、播放只实现了对 aac 格式的支持，默认无法播放其他格式。如果您的 Android/iOS App 会自行处理音频录制、播放，可以按需选用格式。

javascript
RongIMLib.sendHQVoiceMessage(
  {
    conversationType: RongIMLib.ConversationType.ULTRA_GROUP,
    targetId: '',
    channelId: '',
  },
  {
    file, // 待上传文件
    user: { id: '', name: '', portraitUri: '', extra: '' }, // 消息中携带的用户信息，非必填
    extra: '', // 消息中携带的透传信息，非必填
  },
  {
    onProgress(progress) {}, // 上传进度监听，可选
    onComplete(fileInfo) {
      // 上传完成时的回调钩子，可选
      console.log(fileInfo.url) // 文件存储地址
      // 如果需要构建自定义消息，return new ABCMesssage('')
      // ABCMesssage 定义通过自定义消息实现 `const ABCMesssage = RongIMLib.registerMessageType(...)`
      // 无 return 返回值的情况下，SDK 默认发送 HQVoiceMessage
    },
  },
  {
    // ... 其他配置项，可选
  }
).then(({ code, data: message }) => {
  if (code === 0) {
    // 发送成功
  }
})

发送短视频消息​

提示

如果您的业务同时使用了 Android/iOS 端的 IMKit SDK，必须使用 H.264 + AAC 编码的文件，因为 IMKit 的短视频录制、播放只实现了该编码组合的支持。

javascript
RongIMLib.sendSightMessage(
  {
    conversationType: RongIMLib.ConversationType.ULTRA_GROUP,
    targetId: '',
    channelId: ''
  },
  {
    file, // 待上传文件
    duration: number, // 视频时长
    thumbnail: string, // 视频首帧缩略图，应为 Base64 字符串,
    name: string // 文件名，可选项，默认读取文件真实名称
    user: { id: '', name: '', portraitUri: '', extra: '' }, // 消息中携带的用户信息，可选参
    extra: '', // 消息中携带的透传信息，可选参
  },
  {
    onProgress (progress) {},  // 上传进度监听，可选
    onComplete (fileInfo) { // 上传完成时的回调钩子，可选
      console.log(fileInfo.url) // 文件存储地址
      // 如果需要构建自定义消息，return new ABCMesssage('')
      // ABCMesssage 定义通过自定义消息实现 `const ABCMesssage = RongIMLib.registerMessageType(...)`
      // 无 return 返回值的情况下，SDK 默认发送 SightMessage
    }
  },
  {
    // ... 其他配置项，可选
  }
).then(({ code, data: message }) => {
  if (code === 0) {
    // 发送成功
  }
})

接收消息​

超级群会话中通过消息监听器通知业务层。调用 addEventListener 设置消息接收监听器。所有接收到的消息都会在此接口方法中回调。可在任意位置多次监听。

JavaScript
const Events = RongIMLib.Events
const listener = (evt) => {
  console.log(evt.messages)
};
RongIMLib.addEventListener(Events.MESSAGES, listener)

上方示例的 listener 中返回 IMessageEvent 对象，其 messages 属性中包含接收到的消息（IAReceivedMessage）的列表。