发送消息

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

提示

客户端 SDK 发送消息存在频率限制，每秒最多只能发送 5 条消息。

发送消息

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）

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、文件等消息类型。

文本消息

ITextMessageBody 参数说明

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

代码示例

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

图片消息

IImageMessageBody 参数说明

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: '' // 图片的远程访问地址
})

文件消息

IFileMessageBody 参数说明

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

代码示例

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

高清语音

IHQVoiceMessageBody 参数说明

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,
})

短视频消息

ISightMessageBody 参数说明

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 消息

IGIFMessageBody 参数说明

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

代码示例

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

引用消息

IReferenceMessageBody 参数说明

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

代码示例

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

位置消息

ILocationMessageBody 参数说明

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

代码示例

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

富文本消息

IRichContentMessageBody 参数说明

参数	类型	必填	说明
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

Global IM UIKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

验证码短信

发送消息​

sendMessage 接口说明​

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

内置消息类型​

文本消息​

图片消息​

文件消息​

高清语音​

短视频消息​

GIF 消息​

引用消息​

位置消息​

富文本消息​

Emoji 消息​

Emoji 代码示例​

Emoji 插件​

拓展属性​

发送输入状态​

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

问题场景​

解决方案​

遗留问题​

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

发送消息

sendMessage 接口说明

关于发送媒体消息的说明

内置消息类型

文本消息

图片消息

文件消息

高清语音

短视频消息

GIF 消息

引用消息

位置消息

富文本消息

Emoji 消息

Emoji 代码示例

Emoji 插件

拓展属性

发送输入状态

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

问题场景

解决方案

遗留问题

如何实现转发、群发消息