发送消息

本文介绍了如何从客户端发送消息，适用于单聊、群聊、聊天室。

提示

客户端 SDK 发送消息存在频率限制，每秒最多只能发送 5 条消息。
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 方法用于发送 IMLib 中的内置类型消息或自定义消息。

以调用 sendMessage 往群聊中发送 @张三的文本消息为例。

定义目标群聊会话，并实例化待发送消息。因为发送的是群聊 @ 消息，所以需要添加 mentionedInfo。

JavaScript
// 定义消息投送目标会话, 这里定义一个群组类型会话
const conversation = { conversationType: RongIMLib.ConversationType.GROUP, targetId: '<目标 Id>' }
// 实例化待发送消息，RongIMLib.TextMessage 为内置文本型消息
const message = new RongIMLib.TextMessage({
  // 文本内容
  content: '文本内容',
  // （可选）消息中附加信息，透传到对端
  extra: '消息中附加信息',
  // 群组消息中，如果需要发送 @ 消息，可添加 mentionedInfo 字段
  mentionedInfo: {
    // @ 类型：全部、个人
    type: RongIMLib.MentionedType.SINGAL,
    // @ 用户列表
    userIdList: [zhangsan],
    // @ 内容
    mentionedContent: ''
  }
})

构造发送选项 ISendMessageOptions，用于定义发送行为中的一些可选配置。因为发送的是群聊 @ 消息，必须将 options 中的 isMentioned 设置为 true。

JavaScript
// 配置属性
const options = {
  // 如果需要发送 @ 消息，isMentioned 需设置为 true
  isMentioned: true,
  // 消息发送前的回调，可以使用此回调返回的 message 用于列表渲染
  onSendBefore: (message) => {
    console.log('消息发送前的回调', message)
  }
}

发送消息。如果消息发送成功，可以根据返回结果中的 messageId 字段将列表中的该消息状态改为发送成功。

JavaScript
// 发送消息
RongIMLib.sendMessage(conversation, message, options).then(res => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    // 消息发送成功，可以根据返回结果中的 messageId 字段将列表中的该消息状态改为发送成功。
    console.log('消息发送成功', res.data)
  } else {
    console.log('消息发送失败', res.code, res.msg)
  }
})

如果消息发送失败，可以根据返回结果中的 messageId 字段将列表中的该消息状态改为发送失败，并重发消息。

客户端遇到消息发送失败时，可能有以下情况：
1. 消息未送达融云服务器，或送达融云服务端后返回发送失败的情况（其他人也没有收到）。
2. 某些极端情况下（例如弱网环境），消息可能已成功送达收件方。但发送端未能及时收到融云服务端回执，超时后认为发送失败。此时客户端重发消息后会导致对方重复收到消息。关于该问题的详细解释可参考 FAQ。

重新发送消息。重发消息需与原始消息保持一致。

提示

SDK 从 5.5.1 版本开始，支持重发消息时在 options 中传入原消息的 messageId。融云服务端不会去除重复消息，应用层可通过该 ID 自行判断消息是否属于重复消息，并进行相应处理。该 ID 可以从 onSendBefore 回调返回的 message 对象或返回结果中获取。

JavaScript
// 定义消息投送目标会话, 这里定义一个群组类型会话
const conversation = { conversationType: RongIMLib.ConversationType.GROUP, targetId: '<目标 Id>' }
// 实例化待发送消息，RongIMLib.TextMessage 为内置文本型消息
const message = new RongIMLib.TextMessage({ content: '文本内容' })
// 配置属性
const options = {
  // 重发消息的 messageId, 可以从 onSendBefore 回调返回的 message 对象中 或 返回结果中获取
  messageId: 0
}

RongIMLib.sendMessage(conversation, message, options).then(res => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    // 消息发送成功，可以根据返回结果中的 messageId 字段将列表中的该消息状态改为发送成功。
    console.log('消息发送成功', res.data)
  } else {
    // 消息发送失败，可以根据返回结果中的 messageId 字段将列表中的该消息状态改为发送失败。
    console.log('消息发送失败', res.code, res.msg)
  }
})

sendMessage 接口说明

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

conversation 定义目标会话。详见 IConversationOption。

参数类型说明
conversationType ConversationType 会话类型
targetId string 接收方 Id
message 是待发送的消息内容，支持 IMLib 内置消息（例如 RongIMLib.TextMessage）实例，或者通过 RongIMLib.registerMessageType() 实现的自定义消息实例。

参数	类型	说明
`conversationType`	`ConversationType`	会话类型
`targetId`	`string`	接收方 Id

options 定义发送行为中的一些可选配置，如是否可拓展，推送等。参见 ISendMessageOptions

参数	类型	说明
~~isStatusMessage~~	`boolean`	（已废弃）是否为状态消息（可选项）
`disableNotification`	`boolean`	是否发送静默消息（可选项）
`pushContent`	`string`	Push 信息（可选项）
`pushData`	`string`	Push 通知携带的附加信息（可选项）
`isMentioned`	`boolean`	是否为 @ 消息，只当 `conversationType` 值为 `ConversationType.GROUP` 时有效（可选项）
~~mentionedType~~	~~`1｜2`~~	~~@ 消息类型，1: @ 所有人 2: @ 指定用户（可选项）~~ 已废弃
~~mentionedUserIdList~~	~~string[]~~	~~被 @ 的用户 Id 列表（可选项）~~ 已废弃
`directionalUserIdList`	`string[]`	用于发送群定向消息，只当 `conversationType` 值为 `ConversationType.GROUP` 时有效（可选项）
`isVoipPush`	`boolean`	当对方为 iOS 设备且未在线时，其将收到 Voip Push. 此配置对 Android 无影响（可选项）
`canIncludeExpansion`	`boolean`	是否允许消息被拓展
`expansion`	[key: string]: string	消息拓展内容数据（可选项）
`isFilerWhiteBlacklist`	`boolean`	黑/白名单（可选项）
`pushConfig`	`IPushConfig`	移动端推送配置（可选项）（与 Android、iOS 端的 MessagePushConfig 作用相似）
`onSendBefore`	`Function`	消息发送前的回调。（≥ 5.4.0）
`messageId`	`number`	重发消息时，传要重发消息的 messageId，重发消息的所有参数需与原始消息一致。（≥ 5.5.1）
`disableUpdateLastMessage`	`boolean`	禁止更新会话最后一条消息，默认为 false。（≥ 5.12.2）
`needReceipt`	`boolean`	是否需要对方发送回执，默认为 false（≥ 5.20.0）
`quoteInfo`	`IQuoteInfo`	描述消息引用关系（≥ 5.38.0）

IPushConfig 参数说明

参数	类型	说明
`pushTitle`	`string`	推送标题，在没有设置的情况下：单聊通知标题显示为发送者名称，群聊通知标题显示为群名称；自定义消息，默认不显示标题；
`pushContent`	`string`	推送内容
`pushData`	`string`	远程推送附加信息
`iOSConfig`	`IiOSPushConfig`	（可选项）
`androidConfig`	`IAndroidPushConfig`	（可选项）
`disablePushTitle`	`boolean`	是否显示推送标题. 仅针对 iOS 平台有效
`forceShowDetailContent`	`boolean`	是否强制推送
`templateId`	`string`	推送模板id

以发送文本消息为例：

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

关于发送媒体消息的说明

重要

小程序平台 IMLib SDK 未提供发送媒体消息的语法糖方法。

如需在小程序平台实现发送图片、GIF、文件等媒体消息，请使用 sendMessage 方法，您需要自行实现消息中的文件上传逻辑。

以融云微信小程序 Demo 中的实现为例，完整示例请您参考 Demo 源码中的 chat.js。

内置消息类型

IMLib 提供了预定义的文本、语音、图片、Gif、文件等消息类型。

文本消息

ITextMessageContent 参数说明

Key	类型	必填	说明
`content`	`string`	是	文本内容

代码示例

JavaScript
new RongIMLib.TextMessage({ content: '' })

图片消息

IImageMessageContent 参数说明

Key	类型	必填	说明
`content`	`string`	是	图片缩略图，应为 Base64 字符串。自行生成缩略图（建议最长边不超过 240 像素），进行 Base64 编码后放入 `content` 中。Base64 字符串长度建议为 5k，最大不超过 10k。注意，部分工具图片转 Base64 输出结果会携带 Data URI 前缀。例如：`data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD`。请丢弃其中 Data URI 前缀，仅保留数据部分，例如：`/9j/4AAQSkZJRgABAgAAZABkAAD`。
`imageUri`	`string`	是	图片的远程访问地址
thumWidth	number	否	缩略图宽度（5.18.0 版本开始支持）｜
thumHeight	number	否	缩略图高度（5.18.0 版本开始支持）｜

代码示例

JavaScript
new RongIMLib.ImageMessage({
  content: '', // 图片缩略图，应为 Base64 字符串，且不可超过 80KB
  imageUri: '' // 图片的远程访问地址
})

文件消息

IFileMessageContent 参数说明

Key	类型	必填	说明
`name`	`string`	是	文件名称
`size`	`number`	是	图片尺寸，单位 `Byte`
`type`	`string`	是	文件类型
`fileUrl`	`string`	是	文件远程下载地址

代码示例

JavaScript
new RongIMLib.FileMessage({
  name: '',
  size: 1000,
  type: '',
  fileUrl: ''
})

高清语音

IHQVoiceMessageContent 参数说明

Key	类型	必填	说明
`remoteUrl`	`string`	是	远程媒体资源地址
`duration`	`number`	是	语音时长，单位 `s`。请务必保证待发送的语音时长保持在 60s 以内
`type`	`string`	否	编码类型，默认 `aac`。如果您的业务同时使用了 Android/iOS 端的 IMKit SDK，请使用默认的 `aac` 格式，因为 IMKit 的音频录制、播放只实现了对 `aac` 格式的支持，默认无法播放其他格式。如果您的 Android/iOS App 会自行处理音频录制、播放，可以按需选用格式。

代码示例

JavaScript
new RongIMLib.HQVoiceMessage({
  remoteUrl: '<aac 文件地址>',
  duration: 60,
})

短视频消息

ISightMessageContent 参数说明

Key	类型	必填	说明
`sightUrl`	`string`	是	远程视频资源地址。如果您的业务同时使用了 Android/iOS 端的 IMKit SDK，必须使用 `H.264` + `AAC` 编码的文件，因为 IMKit 的短视频录制、播放只实现了该编码组合的支持。
`content`	`string`	是	小视频首帧缩略图的 Base64 字符串。自行生成缩略图（建议最长边不超过 240 像素），进行 Base64 编码后放入 `content` 中。Base64 字符串长度建议为 5k，最大不超过 10k。注意，部分工具图片转 Base64 输出结果会携带 Data URI 前缀。例如：`data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD`。请丢弃其中 Data URI 前缀，仅保留数据部分，例如：`/9j/4AAQSkZJRgABAgAAZABkAAD`。
`duration`	`number`	是	视频时长。请注意服务端的默认视频时长上限为 2 分钟。若需调整上限，请联系商务。
`size`	`number`	是	视频大小，单位 `Byte`
`name`	`number`	是	视频名称

代码示例

JavaScript
new RongIMLib.SightMessage({
  sightUrl: "<视频资源的远程地址>",
  content: "<缩略图base64>"
  duration: 10,
  size: 100,
  name: "视频名称"
})

GIF 消息

IGIFMessageContent 参数说明

Key	类型	必填	说明
`gifDataSize`	`number`	是	GIF 图片文件大小，单位 `Byte`
`remoteUrl`	`string`	是	GIF 图片的远程存储地址
`width`	`number`	是	图片宽度
`height`	`number`	是	图片高度

代码示例

JavaScript
new RongIMLib.GIFMessage({
  gifDataSize: 30,
  remoteUrl: '<图片地址>',
  width: 300,
  height: 200
})

引用消息

IReferenceMessageContent 参数说明

参数	类型	必填	说明
`referMsgUserId`	string	是	被引用消息的发送用户 Id
`referMsg`	any	是	引用消息对象
content	string	是	输入的文本消息内容
`objName`	string	是	引用的消息类型

代码示例

JavaScript
new RongIMLib.ReferenceMessage({
  referMsgUserId: '<引用消息的用户ID>',
  referMsg: {
    content: '引用消息文本'
  },
  referMsgUid: '引用消息的 messageUId',
  content: '发送的消息内容',
  objName: RongIMLib.MessageType.TEXT
})

发送带引用关系信息的消息

ReferenceMessage 消息类型会把回复内容固定封装为 RC:ReferenceMsg。从 5.38.0 版本开始，SDK 支持通过 quoteInfo 在实际发送的消息上表达引用关系。带引用关系信息的消息不是新的消息类型，消息内容仍保持文本、图片、GIF、小视频、普通语音、高清语音、文件、位置、自定义消息等实际类型。

发送带引用关系信息的消息时，请在 sendMessage 的 options.quoteInfo 中传入被引用消息的 messageUId、senderId 和 objectName。旧版 ReferenceMessage 仍然可以继续使用。

JavaScript
// 此处以回复文本消息举例，实际业务层可按需构建任意类型消息。
const msg = new RongIMLib.TextMessage({ content: '<回复内容>' });

const conversation = {
  conversationType: RongIMLib.ConversationType.GROUP,
  targetId: '<目标 Id>'
};

const options = {
  quoteInfo: {
    objectName: '<被引用消息的 messageType>',
    senderId: '<被引用消息的 senderUserId>',
    messageUId: '<被引用消息的 messageUId>'
  }
};

const res = await RongIMLib.sendMessage(conversation, msg, options);

接收端收到包含 quoteInfo 数据的消息后，可通过 getMessagesByUIds 接口批量查询被引用消息的原始内容数据。

JavaScript
const quoteInfo = message.quoteInfo;
if (quoteInfo) {
  const res = await RongIMLib.getMessagesByUIds({
    conversationIdentifier: {
      conversationType: message.conversationType,
      targetId: message.targetId,
    },
    messageUIds: [quoteInfo.messageUId]
  });
}

位置消息

ILocationMessageContent 参数说明

参数	类型	必填	说明
longitude	number	是	经度
latitude	number	是	维度
poi	string	是	位置信息
content	string	是	位置缩略图，图片需要是不带前缀的 Base64 字符串

代码示例

JavaScript
new RongIMLib.LocationMessage({
  latitude: '<位置的经度>',
  longitude: '<位置的纬度>',
  poi: '位置信息',
  content: '<base64>'
})

图文消息

IRichContentMessageContent 参数说明

参数	类型	必填	说明
title	string	是	标题
content	string	是	简介内容
`imageUri`	string	是	展示的图片地址
url	string	是	文章链接地址

代码示例

JavaScript
new RongIMLib.RichContentMessage({
  title: '标题',
  content: '内容简介',
  imageUri: '<图片地址>',
  url: '<文章链接地址>'
})

Emoji 消息

Web 端发送 Emoji 消息时，直接以文本消息类型（TextMessage）发送即可。

融云提供 Emoji 插件，内置了 128 个 Emoji 表情的图片。可用于消息输入框的表情选项，也可自行扩展配置。
发消息时，必须直接发送 Emoji 原生字符。如：😀 ，转换方法：symbolToEmoji。

Emoji 代码示例

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

Emoji 插件

引入 Emoji 插件
- 从 CDN 获取：https://cdn.ronghub.com/RongIMEmoji-2.2.6.js
- 从微信 IM SDK 5.2.2 Demo 获取：https://downloads.rongcloud.cn/%E5%BE%AE%E4%BF%A1%20IM%20SDK%205.2.2%20Demo.zip

Emoji 初始化（默认参数）

JavaScript
const RongEmoji = require('../lib/RongIMEmoji-2.2.6.js');
RongEmoji.init();

Emoji 初始化（自定义表情配置）

config 参数说明：

参数	类型	必填	说明	插件最低版本
`size`	`Number`	否	表情大小, 默认 24, 建议 18 - 58	2.2.6
`url`	`String`	否	Emoji 背景图片 url	2.2.6
`lang`	`String`	否	Emoji 对应名称语言, 默认 zh	2.2.6
`extension`	`Object`	否	扩展表情	2.2.6

JavaScript
// 表情信息可参考 http://unicode.org/emoji/charts/full-emoji-list.html
var config = {
  size: 25,
  url: '//f2e.cn.ronghub.com/sdk/emoji-48.png',
  lang: 'en',
  extension: {
    dataSource: {
      u1F914: { // 自定义 u1F914 对应的表情
        en: 'thinking face', // 英文名称
        zh: '思考', // 中文名称
        tag: '🤔', // 原生 Emoji
        position: '0 0' // 所在背景图位置坐标
      }
    },
    url: '//cdn.ronghub.com/thinking-face.png' // 新增 Emoji 背景图 url
  }
};
RongEmoji.init(config);

获取列表

JavaScript
var list = RongEmoji.list;
/*list => [{
  unicode: 'u1F600',
  emoji: '😀',
  node: span,
  symbol: '[笑嘻嘻]'
}]
*/

Emoji 转文字

在不支持原生 Emoji 渲染时，可显示对应名称，适用于消息输入。

JavaScript
var message = '😀😁测试 Emoji';
// 将 message 中的原生 Emoji 转化为对应名称
RongEmoji.emojiToSymbol(message);
// => '[笑嘻嘻][露齿而笑]测试 Emoji'

文字转 Emoji

发送消息时，消息体里必须使用原生 Emoji 字符。

JavaScript
var message = '[笑嘻嘻][露齿而笑]测试 Emoji';
// 将 message 中的 Emoji 对应名称转化为原生 Emoji
RongEmoji.symbolToEmoji(message);
// => '😀😁测试 Emoji'

拓展属性

所有消息均支持 user 与 extra 两种拓展属性，便于业务层基于自身需求透传业务数据信息。

user: 用于在消息中携带用户数据，目前仅支持 user.id、user.name、user.portraitUri、user.extra 四个属性定义。
extra: 字符串类型数据，融云不解析，由业务层自行定义序列化与反序列化逻辑。

代码示例

JavaScript
new RongIMLib.TextMessage({
  content: '',
  extra: '',
  user: {
    id: '',
    name: '',
    portraitUri: '',
    extra: ''
  }
})

发送输入状态

当需要同步输入状态到指定会话，可以通过调用 sendTypingStatusMessage 方法实现。

代码示例

JavaScript
RongIMLib.sendTypingStatusMessage({
  conversationType: RongIMLib.ConversationType.PRIVATE,
  targetId: '<targetId>'
}, RongIMLib.MessageType.TEXT)

为什么发送失败后重发消息可能导致消息重复

发送端处于弱网情况下可能出现该问题。

问题场景

A 向 B 发送消息后，消息成功到达服务端，并成功下发到接收者 B。但 A 由于网络等原因可能未收到服务端返回的 ack，导致 A 认为没有发送成功。此时如果 A 重发消息，此时 B 就会收到与之前重复的消息。

解决方案

融云服务端不处理消息重复。从 SDK 5.5.1 版本开始，支持在重发消息携带原消息的 messageId。应用层可在消息重复时自行处理。

发送消息后和接收消息时，消息中会携带 messageId 字段，这个字段是由客户端生成的消息 ID。从 Web 端重发消息时，在 options 参数中传入发送失败消息的 messageId。应用层在展示消息前，可根据 senderUserId 和 messageId 滤除重复消息后再进行展示。

遗留问题

撤回重发的消息时，会出现只能撤回一条，另一条还存在的问题。
收到的消息重复时，即时页面上通过过滤方式使消息显示一条，但未读数依然会显示 2 个。

如何实现转发、群发消息

转发消息：IMLib SDK 未提供转发消息接口。App 实现转发消息效果时，可调用发送消息接口发送。

群发消息：群发消息是指向多个用户发送消息。更准确地说，是向多个 Target ID^?发送消息，一个 Target ID 可能代表一个用户，一个群组，或一个聊天室。客户端 SDK 未提供直接实现群发消息效果的 API。您可以考虑以下实现方式：

App 循环调用客户端的发送消息 API。请注意，客户端 SDK 限制发送消息的频率上限为每秒 5 条。
App 在业务服务端接入即时通讯服务端 API（IM Server API），由 App 业务服务端群发消息。IM Server API 的发送单聊消息接口支持单次向多个用户发送单聊消息。您也可以通过发送群聊消息、发送聊天室消息接口实现单次向多个群组或多个聊天室发送消息。

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

北极星数据查询

发送消息​

sendMessage 接口说明​

关于发送媒体消息的说明​

内置消息类型​

文本消息​

图片消息​

文件消息​

高清语音​

短视频消息​

GIF 消息​

引用消息​

发送带引用关系信息的消息​

位置消息​

图文消息​

Emoji 消息​

Emoji 代码示例​

Emoji 插件​

拓展属性​

发送输入状态​

为什么发送失败后重发消息可能导致消息重复​

问题场景​

解决方案​

遗留问题​

如何实现转发、群发消息​

发送消息

sendMessage 接口说明

关于发送媒体消息的说明

内置消息类型

文本消息

图片消息

文件消息

高清语音

短视频消息

GIF 消息

引用消息

发送带引用关系信息的消息

位置消息

图文消息

Emoji 消息

Emoji 代码示例

Emoji 插件

拓展属性

发送输入状态

为什么发送失败后重发消息可能导致消息重复

问题场景

解决方案

遗留问题

如何实现转发、群发消息