版本：2.X

消息发送

功能描述

消息属性	消息描述	消息属性	消息描述
消息类名	各端消息名	ObjectName	传输层名称，与消息类名一一对应
存储属性	存储 / 不存储	计数属性	计数 / 不计数
离线属性	缓存 / 不缓存	消息尺寸	128 KB
推送属性	是/否	推送内容	详见各消息类送方式

存储属性

存储属性	存储分类	支持平台	详细描述
存储	客户端	Android、iOS	发送、接收该消息后，本地数据库存储 Web 端和小程序端因本地存储不可靠，不支持客户端消息存储，但可通过历史消息云存储服务获取历史记录
存储	云端	Android、iOS、Web	默认不在云端进行存储，需开通历史消息云存储服务，开通后，可在融云服务端存储 6 个月的历史消息，供客户端按需拉取
不存储	客户端	Android、iOS	发送、接收该消息后，本地数据库不存储
不存储	云端	Android、iOS、Web	无论是否开通历史消息云存储服务，该消息均不存储

计数属性

接收收到消息时，会话是否累计未读数。

计数属性	支持平台	详细描述
计数	iOS、Android、Web	会话未读消息数 + 1，该属性只影响会话列表未读数计数，App 应用角标可根据每个会话列表未读数累加获得
不计数	iOS、Android、Web	会话未读消息数不变

离线属性

接收人当前不在线时，是否进行离线缓存。

离线属性	详细描述
存储	消息进行离线缓存，默认 7 天。接收人在 7 天内上线，均可接收到该消息。超过 7 天后，消息被离线缓存淘汰。如有需要，可通过云端存储拉取到该消息
不存储	消息不进行离线缓存，所以只有接收人在线时，才可收到该消息。该消息不进行历史消息云存储、不进入云端存储（ Log 日志）、不进行消息同步（消息路由）

推送属性

接收人是否接收推送，当离线属性为存储时，该属性生效。离线属性为 不存储 时属性无效。

由于 Web、小程序、PC 端没有推送平台，无法收到推送提醒。

推送属性	平台	推送方式	详细描述
推送	iOS、Android	APNS、华为、小米、魅族、OPPO、vivo、FCM、融云	当有离线缓存消息时，进行远程推送提醒，内容为该推送提醒显示的内容
不推送	iOS、Android	--	当有离线缓存消息时，不进行远程推送提醒

危险

发送消息必须在成功连接融云服务器成功之后进行。
每秒最多发送 5 条消息。

发送普通消息

API 参考：sendMessage

参数需按顺序传入，顺序为参数说明中的字段顺序。

sendMessage 参数说明

参数	类型	必填	说明	最低版本
conversationType	Number	是	会话类型，单聊会话传入 RongIMLib.ConversationType.PRIVATE	2.2.0
targetId	String	是	单聊会话 ID	2.2.0
msg	Object	是	消息	2.2.0
callback	Object	是	回调对象	2.2.0
callback.onSuccess	Function	是	成功回调	2.2.0
callback.onError	Function	是	失败回调	2.2.0
isMentioned	Boolean	否	是否为 @ 消息	2.2.0
pushContent	String	否	Push 显示内容	2.2.0
pushData	String	否	Push 通知时附加信息	2.2.0
~~methodType~~	Number	否	该参数已废弃	2.6.0
config	Object	否	其他设置项	2.5.3

config 说明：

参数	类型	必填	说明	最低版本
userIds	Array	否	接收定向消息的用户 id	2.2.0
isVoipPush	Boolean	否	为 true 时, 对端不在线的 iOS 会收到 Voip Push. Android 无影响	2.5.3
disableNotification	Boolean	否	是否发送静默消息，设置为 true 后不会发送 Push 信息和本地通知提醒	2.5.9
canIncludeExpansion	Boolean	否	是否支持扩展	2.6.0
expansion	Object	否	扩展内容	2.6.0
isStatusMessage	Boolean	否	是否为状态消息	2.6.0
~~isStatus~~	Boolean	否	该参数已废弃，请使用 `isStatusMessage` 替代该参数。在 `isStatusMessage` 有值的情况下，该参数将失效	2.6.0

代码示例

var conversationType = RongIMLib.ConversationType.PRIVATE;  // 群聊, 其他会话选择相应的消息类型即可
var targetId = '接收方的 userId';  // 目标 Id
var msg = new RongIMLib.TextMessage({ content: 'hello RongCloud!', extra: '附加信息'});
  var callBack = {
    onSuccess: function (message) {
      // message 为发送的消息对象并且包含服务器返回的消息唯一 id 和发送消息时间戳
      console.log('发送文本消息成功', message);
    },
    onError: function (errorCode) {
      console.log('发送文本消息失败', errorCode);
    }
  };
var isMentioned = false;  // @ 消息
var pushContent = 'user 发送了一条消息';  // Push 显示内容
var methodType = null; // 已经逐步废弃，填写null即可
var pushData = null;  // Push 通知时附加信息, 可不填
var config = {
  isVoipPush: true, // 发送 voip push
  disableNotification: true // 发送静默消息， 设置为 true 后移动端不会收到 Push 信息和本地通知提醒
};
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, callBack, isMentioned, pushContent, pushData, methodType, config);

message 属性说明

字段名	类型	说明
conversationType	Number	会话类型，单聊会话传入 RongIMLib.ConversationType.PRIVATE
targetId	String	单聊会话 ID
senderUserId	String	发送者 id
content	Object	消息内容
objectName	String	消息的消息标识，融云内置消息以 "RC:" 开头
messageType	String	消息类型
messageId	Number	本地生成的消息 id
messageUId	String	服务端存储的消息 id
messageDirection	Number	消息方向, 发送: 1, 接收: 2, 枚举值通过 `RongIMLib.MessageDirection` 获取
offLineMessage	Boolean	是否为离线消息
sentStatus	Number	发送状态, 枚举值通过 `RongIMLib.SentStatus` 获取, PC 端有效，Web 端无效
sentTime	Number	消息在融云服务端的发送时间
receivedStatus	Number	接收状态, 枚举值通过`RongIMLib.ReceivedStatus` 获取
receivedTime	Number	接收时间
disableNotification	Boolean	消息是否静默，静默消息不会发送 Push 信息和本地通知提醒

文本消息

API 参考：sendMessage

消息说明

消息类名	ObjectName	存储属性	计数属性	离线属性	推送属性	推送内容
TextMessage	RC:TxtMsg	存储	计数	存储	推送	消息内容

TextMessage 参数说明

属性名称	属性类型	是否必填	属性说明
content	String	是	文本消息内容
extra	String	否	附加信息，一般为消息不显示消息内容

代码示例

var textMessageInfo = {
  content: 'hello RongCloud!',
  extra: '附加信息'
}
var msg = new RongIMLib.TextMessage(textMessageInfo);
var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';  // 目标 ID

RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, {
  onSuccess: function (message) {
    // message 为发送的消息对象并且包含服务器返回的消息唯一 id 和发送消息时间戳
    console.log('发送文本消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送文本消息失败', errorCode);
  }
});

图文消息

API 参考：sendMessage

消息说明

消息类名	ObjectName	存储属性	计数属性	离线属性	推送属性	推送内容
RichContentMessage	RC:ImgTextMsg	存储	计数	存储	推送	消息内容

参数说明

属性名称	属性类型	是否必填	属性说明
content	String	是	图文内容
title	String	是	图文标题
imageUri	String	是	图片上传到服务器的 url
url	String	是	富文本消息点击后打开的 URL
extra	String	否	附加信息，一般为消息不显示消息内容

代码示例

var msg = new RongIMLib.RichContentMessage({
  title: '图文标题',
  content: '图文内容',
  imageUri: '图片上传到服务器的 url',
  url: '富文本消息点击后打开的 URL'
});
var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';

RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, {
  onSuccess: function (message) {
    console.log('发送富文本消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送富文本消息失败', errorCode);
  }
});

Emoji 消息

web 端发送 Emoji 消息，开发者直接使用文本消息发送即可。
融云提供 Emoji 插件，内置了 128 个 Emoji 表情的图片, 做消息输入框的表情选项, 也可自行扩展配置。
发消息时, 必须直接发送 Emoji 原生字符. 如：😀 , 转换方法：symbolToEmoji。
Web SDK 接收消息时接收到的是 Unicode 编码格式, 如：”ef600” 需要转化才能正确显示原生 Emoji。

API 参考：sendMessage

代码示例

var textMessageInfo = { content: '😀' }
var msg = new RongIMLib.TextMessage(textMessageInfo);
var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';  // 目标 ID

RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, {
  onSuccess: function (message) {
    // message 为发送的消息对象并且包含服务器返回的消息唯一 id 和发送消息时间戳
    console.log('发送 Emoji 消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送 Emoji 消息失败', errorCode);
  }
});

Emoji 插件

插件兼容性

Chrome	Firefox	Safari	IE	Edge	iPhone	Android
30+	30+	10+	7+	✔️	iOS 8.0+ 的Safari浏览器以及微信浏览器	4.4+系统的Chrome浏览器以及微信浏览器

Emoji 插件引入

<!-- HTTP -->
<script src="http://cdn.ronghub.com/RongEmoji-2.2.10.js"></script>
<!-- HTTPS -->
<script src="https://cdn.ronghub.com/RongEmoji-2.2.10.js"></script>
<!-- 压缩版 -->
<script src="https://cdn.ronghub.com/RongEmoji-2.2.10.min.js"></script>

Emoji 代码示例 : https://rongcloud.github.io/web-emoji-demo/src/index.html

危险

使用 import * as RongIMLib from '@rongcloud/imlib-v2-adapter' 方式引入 SDK 时表情插件调用需要使用 window 前缀。例如：window.RongIMLib.RongIMEmoji.init()
RongEmoji 插件仅支持 cdn 引入方式，暂不支持 npm 引入

Emoji 初始化：默认参数初始化

RongIMLib.RongIMEmoji.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

// 表情信息可参考 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
  }
};
RongIMLib.RongIMEmoji.init(config);

获取列表

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

Emoji 转文字

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

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

文字转 Emoji

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

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

Emoji 转 HTML

Web SDK 接收消息后，消息体内的原生 Emoji 字符会被解码为对应 Unicode 码，需调用转化方法才能正确显示。

var message = '\uf600测试 Emoji';
// 将 message 中的原生 Emoji (包含 Unicode ) 转化为 HTML
RongIMLib.RongIMEmoji.emojiToHTML(message);
// => "<span class='rong-emoji-content' name='[笑嘻嘻]'>😀</span>测试 Emoji"

文字转 HTML

var message = '[露齿而笑]测试 Emoji';
// 将 message 中的 Emoji 对应名称转化为 HTML
RongIMLib.RongIMEmoji.symbolToHTML(message);
// => "<span class='rong-emoji-content' name='[露齿而笑]'>😁</span>测试 Emoji"

位置消息

API 参考：sendMessage

消息说明

消息类名	ObjectName	存储属性	计数属性	离线属性	推送属性	推送内容
LocationMessage	RC:LBSMsg	存储	计数	存储	推送	[位置]

LocationMessage 参数说明

属性名称	属性类型	是否必填	属性说明
longitude	Number	是	经度
latitude	Number	是	纬度
poi	String	是	位置信息
content	String	是	位置缩略图,图片需要是不带前缀的 base64 字符串
extra	String	否	附加信息，一般为消息不显示消息内容

代码示例

var locatMessageInfo = {
  latitude: 40.0317727,
  longitude: 116.4175057,
  poi: '融云',
  content: '/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDABsSFBcUERsXFhceHBsgKE',  // 位置图片 base64
}
var msg = new RongIMLib.LocationMessage(locatMessageInfo);

var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';  // 目标 ID
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, {
  onSuccess: function (message) {
    console.log('发送位置消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送位置消息失败', errorCode);
  }
});

正在输入状态消息

API 参考：sendMessage

消息说明

消息类名	ObjectName	存储属性	计数属性	离线属性	推送属性	推送内容
TypingStatusMessage	RC:TypSts	不存储	不计数	不存储	不推送	无

TypingStatusMessage 参数说明

属性名称	属性类型	是否必填	属性说明
typingContentType	String	是	正在输入的消息 ObjectName
data	String	否	携带信息

代码示例

var typingContentType = 'RC:TxtMsg';
var msg = new RongIMLib.TypingStatusMessage({ typingContentType: typingContentType});

var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';  // 目标 Id
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, {
  onSuccess: function (message) {
    console.log('发送已读通知成功', message);
  },
  onError: function (errorCode) {
    console.log('发送已读通知失败', errorCode);
  }
});

发送媒体消息

API 参考：sendMessage

sendMessage 参数说明

参数	类型	必填	说明	最低版本
conversationType	Number	是	会话类型，单聊会话传入 RongIMLib.ConversationType.PRIVATE	2.2.0
targetId	String	是	单聊会话 ID	2.2.0
msg	Object	是	消息	2.2.0
callback	Object	是	回调对象	2.2.0
callback.onSuccess	Function	是	成功回调	2.2.0
callback.onError	Function	是	失败回调	2.2.0
isMentioned	Boolean	否	是否为 @ 消息	2.2.0
pushContent	String	否	Push 显示内容	2.2.0
pushData	String	否	Push 通知时附加信息	2.2.0
~~methodType~~	Number	否	该参数已废弃	2.6.0
config	Object	否	其他设置项	2.5.3

config 说明：

参数	类型	必填	说明	最低版本
userIds	Array	否	接收定向消息的用户 id	2.2.0
isVoipPush	Boolean	否	为 true 时, 对端不在线的 iOS 会收到 Voip Push. Android 无影响	2.5.3
disableNotification	Boolean	否	是否发送静默消息，设置为 true 后不会发送 Push 信息和本地通知提醒	2.5.9
canIncludeExpansion	Boolean	否	是否支持扩展	2.6.0
expansion	Object	否	扩展内容	2.6.0
isStatusMessage	Boolean	否	是否为状态消息	2.6.0
~~isStatus~~	Boolean	否	该参数已废弃，请使用 `isStatusMessage` 替代该参数。在 `isStatusMessage` 有值的情况下，该参数将失效	2.6.0

代码示例

var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '接收方的 userId';  // 目标 ID

var base64Str = '/9j/4AAQSBAAD/2wBDDBAYEBAQEB....';  // 压缩后的 base64 略缩图, 用来快速展示图片
var imageUri = 'https://www.rongcloud.cn/images/newVersion/log_wx.png';  // 上传到服务器的 url. 用来展示高清图片
var msg = new RongIMLib.ImageMessage({content: base64Str, imageUri: imageUri});

var callBack = {
  onSuccess: function (message) {
    console.log('发送图片消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送图片消息失败', errorCode);
  }
};

var isMentioned = false;  // @ 消息
var pushContent = 'user 发送了一条消息';  // Push 显示内容
var pushData = null;  // Push 通知时附加信息, 可不填
var config = {
  isVoipPush: true // 发送 voip push
};

RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, callBack, isMentioned, pushContent, pushData, config);

message 属性说明

字段名	类型	说明
conversationType	Number	会话类型，单聊会话传入 RongIMLib.ConversationType.PRIVATE
targetId	String	单聊会话 ID
senderUserId	String	发送者 id
content	Object	消息内容
objectName	String	消息的消息标识，融云内置消息以 "RC:" 开头
messageType	String	消息类型
messageId	Number	本地生成的消息 id
messageUId	String	服务端存储的消息 id
messageDirection	Number	消息方向, 发送: 1, 接收: 2, 枚举值通过 `RongIMLib.MessageDirection` 获取
offLineMessage	Boolean	是否为离线消息
sentStatus	Number	发送状态, 枚举值通过 `RongIMLib.SentStatus` 获取, PC 端有效，Web 端无效
sentTime	Number	消息在融云服务端的发送时间
receivedStatus	Number	接收状态, 枚举值通过`RongIMLib.ReceivedStatus` 获取
receivedTime	Number	接收时间
disableNotification	Boolean	消息是否静默，静默消息不会发送 Push 信息和本地通知提醒

图片消息

发送图片消息只需要图片上传后的 url，和图片的略缩图。
融云提供上传插件，文件存储到优先级高的云存储，插件不包含发送消息。
插件提供的是上传方式，开发者也可通过自己的方式将文件上传至自己文件服务。
融云默认上传文件存储有效期为 6 个月，上传的文件不支持迁移。

API 参考：sendMessage

消息发送

消息说明

消息类名	ObjectName	存储属性	计数属性	离线属性	推送属性	推送内容
ImageMessage	RC:ImgMsg	存储	计数	存储	推送	[图片]

ImageMessage 参数说明

属性名称	属性类型	是否必填	属性说明
content	String	是	图片的略缩图，必须是 base64 字符串, 类型必须为 jpg，base64 字符串大小不可超过 10 KB，base64 略缩图必须不带前缀
imageUri	String	是	上传到服务器的 url. 用来展示高清图片
extra	String	否	附加信息，一般为消息不显示消息内容

代码示例

var base64Str = '/9j/4AAQSBAAD/2wBDDBAYEBAQEB....';  // 压缩后的 base64 略缩图, 用来快速展示图片
var imageUri = 'https://www.rongcloud.cn/images/newVersion/log_wx.png';  // 上传到服务器的 url. 用来展示高清图片
var msg = new RongIMLib.ImageMessage({content: base64Str, imageUri: imageUri});
var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';  // 目标 Id
var callback = {
  onSuccess: function (message) {
    console.log('发送图片消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送图片消息失败', errorCode);
  }
};
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, callback);

图片上传

兼容性

Chrome	Firefox	Safari	IE	Edge
49+	52+	✔️	10+	✔️

上传代码示例：https://github.com/rongcloud/rongcloud-web-im-upload

引入

<script src = "./send-data.js"></script>
<script src = "../upload.js"></script>
<script src="./init.js"></script>

上传 token

必须 IM SDK 连接成功后, 才能使用此方法

API 参考：getFileToken

参数说明：

参数	类型	必填	说明
fileType	Number	是	上传类型, 通过 RongIMLib.FileType 获取
callbacks	Object	是	回调对象
fileName	String	否	原文件名

代码示例：

var fileType = RongIMLib.FileType.IMAGE;
RongIMClient.getInstance().getFileToken(fileType, {
  onSuccess: function(data) {
    console.log('上传 token 为', data.token);
  },
  onError: function(error) {
    console.log('get file token error', error);
  }
}, fileName)

开始上传

config 参数说明：

参数	类型	必填	说明
domain	String	是	上传地址，默认为七牛：https://upload.qiniup.com
fileType	Number	是	上传类型
getToken	Function	是	获取 token 回调

代码示例：

<!-- 创建 input 上传按钮 -->
<input id="uploadFile" type="file">

var file;
var fileType = RongIMLib.FileType.IMAGE;
var uploadEl = document.getElementById("uploadFile");

var getFileType = function(filename) {
    // 默认支持两种图片格式，可自行扩展
    var imageType = {
        'jpg': 1,
        'png': 2,
    }
    var index = filename.lastIndexOf('.') + 1,
    type = filename.substring(index);
    return type in imageType ? 'image': 'file';
};

var config = {
    domain: '',
    fileType,
    getToken: function(callback) {
        var caback={
            onSuccess: function(data){
                callback(data.token);
            },
            onError: function(){
                console.error('get file token error', error);
            }
        }
        RongIMClient.getInstance().getFileToken(fileType, caback, fileName);
    }
};

var callback = {
      onProgress: function(loaded, total) {
        var percent = Math.floor(loaded / total * 100);
        console.log('已上传: ', percent);
      },
      onCompleted: function(data) {
        // 上传完成, 调用 getFileUrl 获取文件下载 url
        console.log('上传成功: ', data);
      },
      onError: function(error) {
        console.error('上传失败', error);
      }
};

var initType = {
    file: function(_file){
        config.fileType = RongIMLib.FileType.FILE;
        UploadClient.initFile(config, function(uploadFile){
            uploadFile.upload(_file, callback);
        });
    },
    image: function(_file){
        UploadClient.initImage(config, function(uploadFile){
            uploadFile.upload(_file, callback);
        });
    }
};


uploadEl.onchange = function() {
    // 根据文件名选择不同的初始化方式
    file = this.files[0]; // 上传的 file 对象;
    initType[getFileType(file.name)](file);
}

下载 url

fileType 值需与 getFileToken 时传入的 fileType 值一致

API 参考：getFileUrl

参数说明：

参数	类型	必填	说明
fileType	Number	是	上传类型, 通过 RongIMLib.FileType 获取
filename	String	是	上传后的文件名, 上传成功后可通过 uploadCallbacks 的 onCompleted 中返回的 data 获取 ,对应属性 data.filename
oriname	String	是	文件原名, 上传成功后可通过 uploadCallbacks 的 onCompleted 中返回的 data 获取 , 对应属性 data.name
callbacks	Object	是	回调对象
data	Object	否	uploadCallbacks.onCompleted 回调返回数据
uploadMethod	String	否	服务器类型，上传成功后可通过 uploadCallbacks 的 onCompleted 中返回的 data 获取，对应属性data.uploadMethod

代码示例：

// data 通过 uploadFile.upload 获取
var fileType ; // 文件类型
var filename = data.filename; // 通过 uploadCallbacks 的 onCompleted 中返回的 data 获取
var oriname = data.name; // 通过 uploadCallbacks 的 onCompleted 中返回的 data 获取
var uploadMethod = data.uploadMethod;
RongIMClient.getInstance().getFileUrl(fileType, filename, oriname, {
  onSuccess: function(data) {
    console.log('文件 url 为: ', data.downloadUrl);
  },
  onError: function(error) {
    console.log('get file url error', error);
  }
}, data,uploadMethod)

语音消息

提示

语音上传请参照文件上传进行是实现。
HQVoiceMessage 消息支持版本： v2.5.0 及以上。

API 参考：sendMessage

消息说明

消息类名	ObjectName	存储属性	计数属性	离线属性	推送属性	推送内容
HQVoiceMessage	RC:HQVCMsg	存储	计数	存储	推送	[语音]

HQVoiceMessage 参数说明

属性名称	属性类型	是否必填	属性说明
remoteUrl	String	是	媒体内容上传服务器后的网络地址
type	String	否	编解码类型，默认为 aac 音频
duration	Number	否	语音消息的时长，最长为 60 秒（单位：秒）
extra	String	否	附加信息，一般为消息不显示消息内容

代码示例

var messageInfo = {
  remoteUrl: 'http://rongcloud-file.ronghub.com/1e0e4743249cd9653b.aac',//此地址为模拟地址仅作为示例使用
  duration: 22,
  extra: '附加信息'
}
var msg = new RongIMLib.HQVoiceMessage(messageInfo);
var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';  // 目标 ID

RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, {
  onSuccess: function (message) {
    // message 为发送的消息对象并且包含服务器返回的消息唯一 ID 和发送消息时间戳
    console.log('发送语音消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送语音消息失败', errorCode);
  }
});

文件消息

发送图片消息只需要图片上传后的 url，和图片的略缩图。
融云提供上传插件，文件默认存储到七牛云，插件不包含发送消息。
插件提供的是上传方式，开发者也可通过自己的方式将文件上传至自己文件服务。
融云默认上传文件存储有效期为 6 个月，上传的文件不支持迁移。

API 参考：sendMessage

消息发送

消息类名	ObjectName	存储属性	计数属性	离线属性	推送属性	推送内容
FileMessage	RC:FileMsg	存储	计数	存储	推送	[文件] + 文件名，如：[文件] 123.txt

FileMessage 参数说明

属性名称	属性类型	是否必填	属性说明
name	String	是	文件名称
size	Number	是	文件尺寸，单位: Byte
type	String	是	文件类型
fileUrl	String	是	上传到服务器的 url
extra	String	否	附加信息，一般为消息不显示消息内容

代码示例

var msg = new RongIMLib.FileMessage({
  name: 'RongIMLib.js',  // 文件名,
  size: 1024,            // 文件大小单位 bytes
  type: 'js',            // 文件类型
  fileUrl: 'https://cdn.ronghub.com/RongIMLib.js'  // 文件地址
});
var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';  // 目标 ID
var callback = {
  onSuccess: function (message) {
    console.log('发送文件消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送文件消息失败', errorCode);
  }
};
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, callback);

文件上传

兼容性

Chrome	Firefox	Safari	IE	Edge
49+	52+	✔️	10+	✔️

上传代码示例：https://github.com/rongcloud/rongcloud-web-im-upload

引入

<script src = "./send-data.js"></script>
<script src = "../upload.js"></script>
<script src="./init.js"></script>

上传 token

必须 IM SDK 连接成功后, 才能使用此方法

API 参考：getFileToken

参数说明：

参数	类型	必填	说明
fileType	Number	是	上传类型, 通过 RongIMLib.FileType 获取
callbacks	Object	是	回调对象
fileName	String	否	原文件名

代码示例：

var fileType = RongIMLib.FileType.FILE;
RongIMClient.getInstance().getFileToken(fileType, {
  onSuccess: function(data) {
    console.log('上传 token 为', data.token);
  },
  onError: function(error) {
    console.log('get file token error', error);
  }
}, fileName)

开始上传

config 参数说明：

参数	类型	必填	说明
domain	String	是	上传地址，默认为七牛：https://upload.qiniup.com
fileType	Number	是	上传类型
getToken	Function	是	获取 token 回调

代码示例：

<!-- 创建 input 上传按钮 -->
<input id="uploadFile" type="file">

var file;
var fileType = RongIMLib.FileType.IMAGE;
var uploadEl = document.getElementById("uploadFile");

var getFileType = function(filename) {
    // 默认支持两种图片格式，可自行扩展
    var imageType = {
        'jpg': 1,
        'png': 2,
    }
    var index = filename.lastIndexOf('.') + 1,
    type = filename.substring(index);
    return type in imageType ? 'image': 'file';
};

var config = {
    domain: '',
    fileType,
    getToken: function(callback) {
        var caback={
            onSuccess: function(data){
                callback(data.token);
            },
            onError: function(){
                console.error('get file token error', error);
            }
        }
        RongIMClient.getInstance().getFileToken(fileType, caback, fileName);
    }
};

var callback = {
      onProgress: function(loaded, total) {
        var percent = Math.floor(loaded / total * 100);
        console.log('已上传: ', percent);
      },
      onCompleted: function(data) {
        // 上传完成, 调用 getFileUrl 获取文件下载 url
        console.log('上传成功: ', data);
      },
      onError: function(error) {
        console.error('上传失败', error);
      }
};

var initType = {
    file: function(_file){
        config.fileType = RongIMLib.FileType.FILE;
        UploadClient.initFile(config, function(uploadFile){
            uploadFile.upload(_file, callback);
        });
    },
    image: function(_file){
        UploadClient.initImage(config, function(uploadFile){
            uploadFile.upload(_file, callback);
        });
    }
};


uploadEl.onchange = function() {
    // 根据文件名选择不同的初始化方式
    file = this.files[0]; // 上传的 file 对象;
    initType[getFileType(file.name)](file);
}

下载 url

fileType 值需与 getFileToken 时传入的 fileType 值一致

API 参考：getFileUrl

参数说明：

参数	类型	必填	说明
fileType	Number	是	上传类型, 通过 RongIMLib.FileType 获取
filename	String	是	上传后的文件名, 上传成功后可通过 uploadCallbacks 的 onCompleted 中返回的 data 获取 ,对应属性 data.filename
oriname	String	是	文件原名, 上传成功后可通过 uploadCallbacks 的 onCompleted 中返回的 data 获取 , 对应属性 data.name
callbacks	Object	是	回调对象
data	Object	否	uploadCallbacks.onCompleted 回调返回数据
uploadMethod	String	否	服务器类型，上传成功后可通过 uploadCallbacks 的 onCompleted 中返回的 data 获取，对应属性data.uploadMethod

代码示例：

// data 通过 uploadFile.upload 获取
var fileType ; // 文件类型
var filename = data.filename; // 通过 uploadCallbacks 的 onCompleted 中返回的 data 获取
var oriname = data.name; // 通过 uploadCallbacks 的 onCompleted 中返回的 data 获取
var uploadMethod = data.uploadMethod;
RongIMClient.getInstance().getFileUrl(fileType, filename, oriname, {
  onSuccess: function(data) {
    console.log('文件 url 为: ', data.downloadUrl);
  },
  onError: function(error) {
    console.log('get file url error', error);
  }
}, data,uploadMethod)

小视频消息

注意

此消息类型 Web 端 SDK 仅支持解析展示，不提供录制。
如 Web 端需要发送小视频消息，小视频录制需要开发者自行实现。
如果 App Key 使用 IM 旗舰版或 IM 尊享版，文件存储时长默认为 180 天（不含小视频文件，小视频文件存储 7 天）。注意，IM 商用版（已下线）默认存储 7 天。如需了解IM 旗舰版或 IM 尊享版的具体功能与费用，请参见融云官方价格说明页面及计费说明。

API 参考：sendMessage

消息说明

消息类名	ObjectName	存储属性	计数属性	离线属性	推送属性	推送内容
SightMessage	RC:SightMsg	存储	计数	存储	推送	[小视频]

SightMessage 参数说明

参数	类型	说明
sightUrl	String	上传到文件服务器的小视频地址
content	String	小视频首帧的缩略图进行 Base64 编码的结果值，格式为 JPG，注意在 Base64 进行 Encode 后需要将所有
和
和
替换成空
duration	Number	视频时长，单位：秒
size	Number	视频大小单位 bytes
name	String	发送端视频的文件名，小视频文件格式为 mp4。

代码示例

var params = {
  content: "/9j/4AAQSkZ/2wB...hDSaSiimB//9k=",
  sightUrl: "http://rongcloud...com/video...",
  duration: 10,
  size: 734320,
  name: "video_xx.mp4",
}
var msg = new RongIMLib.SightMessage(params);
var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';  // 目标 ID
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, {
  onSuccess: function (message) {
    // message 为发送的消息对象并且包含服务器返回的消息唯一 ID 和发送消息时间戳
    console.log('发送小视频消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送小视频消息失败', errorCode);
  }
});

GIF 消息

API 参考：sendMessage

消息说明

消息类名	ObjectName	存储属性	计数属性	离线属性	推送属性	推送内容
GIFMessage	RC:GIFMsg	存储	计数	存储	推送	[图片]

GIFMessage 参数说明

参数	类型	说明
gifDataSize	Number	GIF 图片文件大小，单位为 bytes
remoteUrl	String	GIF 图片的服务器地址
width	Number	GIF 图的宽
height	Number	GIF 图的高

代码示例

var messageInfo ={
    gifDataSize:34563,
    height:246,
    remoteUrl:"https://rongcloud-image.cn.ronghub.com/image_jpe64562665566.gif",
    width:263,
}
var msg = new RongIMLib.GIFMessage(messageInfo);
var conversationType = RongIMLib.ConversationType.PRIVATE;  //选择相应的会话类型即可
var targetId = '单聊会话 ID';
var callback = {
    onSuccess: function (message) {
        console.log('发送 GIF 消息成功', message);
    },
    onError: function (errorCode) {
        console.log('发送 GIF 消息失败', errorCode);
    }
};
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, callback);

发送自定义消息

注册

危险

注册自定义消息代码必须在发送、接收该自定义消息之前
推荐将所有注册自定义消息代码放在 init 方法之后, connect 方法之前
注册的消息类型名, 必须多端一致, 否则消息无法互通
请勿使用 RC: 开头的类型名，以免和 SDK 默认的消息名称冲突

参数说明

参数	类型	说明
messageName	String	消息名称
objectName	String	消息类型名
mesasgeTag	Object	存储，计数标识
searchProp	string[]	搜索字段，web 端无需设置，搜索字段值设置为数字时取值范围为 (-Math.pow(2, 64), Math.pow(2, 64)) 且为整数

代码示例

var messageName = 'PersonMessage';  // 消息名称
var objectName = 's:person';  // 消息类型名，请按照此格式命名
var isCounted = true;  // 消息计数
var isPersited = true;  // 消息保存
var mesasgeTag = new RongIMLib.MessageTag(isCounted, isPersited);
var searchProp = ['name', 'age'];  // 搜索字段中的属性名
RongIMClient.registerMessageType(messageName, objectName, mesasgeTag, searchProp);

发送

API 参考：sendMessage

代码示例

var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';
var msg = new RongIMClient.RegisterMessage.PersonMessage({ name: 'zhang', age: 12 });

var callback = {
    onSuccess: function (message) {
        console.log('发送自定义消息成功', message);
    },
    onError: function (errorCode) {
        console.log('发送自定义消息失败', errorCode);
    }
};
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, callback);

配置消息推送

MessagePushConfig 属性介绍

注意

从 SDK 2.8.0 版本开始支持此功能，针对每条 Message 都可以设置此属性，详细查看以下参数说明。

API 参考：sendMessage

参数	类型	说明
pushTitle	String	推送标题，如果没有设置，会使用 SDK 默认的标题显示规则
pushContent	String	推送内容，如果没有，则使用发送消息的 pushContent，最后则会使用 SDK 默认的标题显示规则
pushData	String	远程推送附加信息，如果没有，则使用发送消息的 pushData
forceShowDetailContent	boolean	是否强制显示通知详情，当目标用户设置推送不显示消息详情时，可通过此参数，强制设置该条消息显示推送详情
disablePushTitle	boolean	iOS 平台是否禁用推送标题
iOSConfig	IOSConfig	iOS 平台相关配置
androidConfig	AndroidConfig	Android 平台相关配置

iOSConfig 属性介绍

参数	类型	说明
threadId	String	iOS 平台通知栏分组 ID，相同的 threadId 推送分为一组（iOS10 开始支持）
apnsCollapseId	String	iOS 平台通知覆盖 ID，apnsCollapseId 相同时，新收到的通知会覆盖老的通知，最大 64 字节（iOS10 开始支持）
category	String	iOS 平台通知分类
richMediaUri	String	iOS 平台推送自定义的通知栏消息右侧图标 URL

AndroidConfig 属性介绍

参数	类型	说明
notificationId	String	Android 平台 Push 唯一标识，目前支持小米、华为推送平台，默认开发者不需要进行设置，当消息产生推送时，消息的 messageUId 作为 notificationId 使用
channelIdMi	String	小米的渠道 ID，该条消息针对小米使用的推送渠道，如开发者集成了小米推送，需要指定 channelId 时，可向 Android 端研发人员获取，channelId 由开发者自行创建
channelIdHW	String	华为的渠道 ID，该条消息针对华为使用的推送渠道，如开发者集成了华为推送，需要指定 channelId 时，可向 Android 端研发人员获取，channelId 由开发者自行创建
channelIdOPPO	String	OPPO 的渠道 ID，该条消息针对 OPPO 使用的推送渠道，如开发者集成了 OPPO 推送，需要指定 channelId 时，可向 Android 端研发人员获取，channelId 由开发者自行创建
typeVivo	String	VIVO 推送通道类型，开发者集成了 VIVO 推送，需要指定推送类型时，可进行设置。目前可选值 "0"(运营消息) 和 "1"(系统消息)

Channel ID 需要由开发者进行创建，创建方式如下：

推送通道	配置说明
华为	App 端，调用 Android SDK 创建 Channel ID 接口创建 Channel ID
小米	在小米开放平台管理台上创建 Channel ID 或通过小米服务端 API 创建
OPPO	App 端，调用 Android SDK 创建 Channel ID；在 OPPO 管理台登记该 Channel ID，保持一致性
vivo	调用服务端 API 创建 Channel ID

示例代码

var conversationType = RongIMLib.ConversationType.PRIVATE;
var targetId = '单聊会话 ID';  // 目标 ID
var msg = new RongIMLib.TextMessage({ content: 'hello RongCloud!', extra: '附加信息'});

var callbacks = {
  onSuccess: function (message) {
    console.log('发送消息成功', message);
  },
  onError: function (errorCode) {
    console.log('发送消息失败', errorCode);
  }
}
let config = {
	pushConfig: {
		pushTitle: "推送标题",
		pushContent: "推送内容",
		pushData: "推送附加消息",
		disablePushTitle: false,
		forceShowDetailContent: false,
		iOSConfig: {
			threadId: "threadId",
			apnsCollapseId: "apnsCollapseId"
		},
		androidConfig: {
			notificationId: "notificationId",
			channelIdMi: "channelIdMi",
			channelIdHW: "channelIdHW",
			channelIdOPPO: "channelIdOPPO",
			typeVivo: "typeVivo"
		},
		templateId: "templateId"
	}
};
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, callbacks, null, null, null, null, config);

常见问题

Q1: 收到的表情信息无法解析，表情显示有问题 A1: 解决方案：

Web 端展示 Emoji 时, 都需要调用 emojiToHTML 转成 HTML 或者使用 symbolToEmoji 将 Unicode 转化成原生 Emoji 字符

发送消息时, 必须发送原生 Emoji 字符, 如果发送 HTML, 则认定发送的是字符串

Q2: 表情列表每一个手机展示的表情不一样 A2: 解决方案：

消息体内的原生 Emoji 字符会被解码为对应 Unicode 码，需调用转化方法才能正确显示

不同浏览器, 不同设备, 展示的原生 Emoji 表情都不同

如需多端展示 Emoji 一致, 需使用 emojiToHTML 转化为 HTML 后再展示(此方法为以图片形式展示)。具体方法请参见 Emoji 消息。

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

Global IM UIKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

验证码短信

消息发送

功能描述​

存储属性​

计数属性​

离线属性​

推送属性​

发送普通消息​

文本消息​

图文消息​

Emoji 消息​

代码示例​

Emoji 插件​

位置消息​

正在输入状态消息​

发送媒体消息​

图片消息​

消息发送​

图片上传​

语音消息​

文件消息​

消息发送​

文件上传​

小视频消息​

GIF 消息​

发送自定义消息​

注册​

发送​

配置消息推送​

MessagePushConfig 属性介绍​

iOSConfig 属性介绍​

AndroidConfig 属性介绍​

常见问题​

功能描述

存储属性

计数属性

离线属性

推送属性

发送普通消息

文本消息

图文消息

Emoji 消息

代码示例

Emoji 插件

位置消息

正在输入状态消息

发送媒体消息

图片消息

消息发送

图片上传

语音消息

文件消息

消息发送

文件上传

小视频消息

GIF 消息

发送自定义消息

注册

发送

配置消息推送

MessagePushConfig 属性介绍

iOSConfig 属性介绍

AndroidConfig 属性介绍

常见问题