RongIMLib - v5.12.3

传入从用户身份令牌（Token），向融云聊天服务器发起连接请求。

• 注意：

1. 必须在 SDK 初始化 init 之后，调用 connect() 方法进行连接。否则可能没有回调。
2. SDK 本身有重连机制，在一个应用生命周期内不须多次调用connect()
3. 在应用生命周期调用一次即可。

建立 IM 连接示例：

const token = '<Your-token>';
const res = await RongIMLib.connect(token);
console.info('建立 IM 连接结果：', res);

调用后将不再接收消息，不可发送消息，不可获取历史消息，不可获取会话列表

• 适用场景：注销账号，切换账号时，推荐使用此方法

断开连接示例：

await RongIMLib.disconnect();
console.info('成功断开');

将移除对某一特定事件的所有监听函数

移除事件示例：

RongIMLib.removeEventListeners(Events.MESSAGES);

清理所有事件示例：

RongIMLib.clearEventListeners();

初始化 IM SDK，传入 Appkey 及相关配置信息

初始化示例：

RongIMLib.init({ appkey: 'appkey' });
console.log('初始化完成');

反初始化，清空所有监听及计时器，停止日志上报等业务

• 适用场景：

1. 应用退出时，推荐使用此方法
2. 需要更换 appkey 时，需要调用此方法后，重新使用新 Appkey 在次调用 init 方法

反初始化示例：

await RongIMLib.destroy();
console.log('反初始化完成');

获取 IM 连接状态示例：

const status = RongIMLib.getConnectionStatus();
console.log('获取 IM 连接状态：', status);

获取当前用户 id 示例：

const userId = RongIMLib.getCurrentUserId();
console.log('获取当前用户 id：', userId);

获取当前设备的唯一标识

获取 deviceId 示例：

const deviceId = RongIMLib.getDeviceId();
console.log('获取 deviceId：', deviceId);

获取会话列表接口需要开通单群聊消息云存储之后才可以从服务端获取到数据，服务端会话列表存储上限为 1000

• 注意： Electron 平台调用时会忽略参数传值，固定返回所有会话列表。建议 Electron 平台客户考虑使用其他获取会话列表的接口 超过 1000 会根据最后一条消息时间排序，删除最早的会话

count: 20, startTime: 0, order: 0

获取会话列表示例：

const conversationList = await RongIMLib.getConversationList();
console.info('获取会话列表结果：', conversationList);

通过该方法获取的会话可能并不存在于当前的会话列表中，此处只作为功能性封装语法糖

获取指定会话数据示例：

const options = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const conversation = await RongIMLib.getConversation(options);
console.info('获取指定会话数据结果：', conversation);

移除指定的会话，不会删除会话内的消息

• 注意：

1. 删除会话不会删除会话的未读数，推荐在删除会话前先调用清除指定会话未读数 clearMessagesUnreadStatus接口，以防止未读数异常
2. 会话是有消息生成，如会话中在产生新消息会重新生成会话

移除指定的会话示例：

const options = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const conversation = await RongIMLib.removeConversation(options);
console.info('移除指定的会话结果：', conversation);

支持按照 NotificationLevel 类型进行免打扰级别设置，级别描述如下：

• -1: 全部消息通知（接收全部消息通知 -- 显示指定关闭免打扰功能）
• 0: 未设置（向上查询群或者APP级别设置）//存量数据中0表示未设置
• 1: 群聊超级群仅@消息通知（现在通知）单聊代表全部消息通知
• 2: @ 指定用户通知
• 3: @ 群用户组通知，通知用户组暂未实现，暂不暴露出去
• 4: @ 群全员通知
• 5: 消息通知被屏蔽，即不接收消息通知

5.3.0

设置会话免打扰示例：

const options = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const notificationLevel = RongIMLib.NotificationLevel.NOT_MESSAGE_NOTIFICATION;
const res = await RongIMLib.setConversationNotificationLevel(options, notificationLevel);
console.info('设置会话免打扰结果：', res);

@since 5.3.0 已废弃，请使用 setConversationNotificationLevel

查询通过 setConversationNotificationLevel 接口设置的指定会话和频道免打扰

1. Electron 平台，从 5.8.4 版本开始支持 setConversationNotificationLevel 接口。

5.3.0

查询指定会话和频道免打扰示例：

const options = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const conversation = await RongIMLib.getConversationNotificationLevel(options);
console.info('查询指定会话和频道免打扰结果：', conversation);

已废弃 @since 5.3.0, 5.3.0以上版本请使用 getConversationNotificationLevel 接口

获取已设置免打扰状态的所有会话，接口仅 Web 端支持

5.1.1

获取免打扰状态列表示例：

const list =  await RongIMLib.getBlockedConversationList();
console.info('获取免打扰状态列表结果：', list);

isUpdateTime 默认为 true

设置会话是否置顶示例：

const isTop = true
const options = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const res = await RongIMLib.setConversationToTop(options, isTop);
console.info('设置会话是否置顶结果：', res);

注意：该接口在 Web 平台返回数据中将不包含 latestMessage 字段。

5.6.0

获取置顶会话列表示例：

const res = await RongIMLib.getTopConversationList();
console.info('获取置顶会话列表数结果：', res);

注意：该接口在 Web 平台返回数据中将不包含 latestMessage 字段。

5.7.0

获取未读会话列表示例：

const res = await RongIMLib.getUnreadConversationList();
console.info('获取未读会话列表结果：', res);

发送消息的基础接口，可用来发送 IMLib 中的内置类型消息或自定义消息。针对不同的特定消息类型

发送文本消息示例：

const content = {content: 'hello world'};
const message = new RongIMLib.TextMessage(content);
const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId'
}
const sendRes = await RongIMLib.sendMessage(conversation, message);
console.info('消息发送结果：', sendRes);

发送文本消息的快捷方式，等同于使用 new TextMessage() 创建消息体后调用 sendMessage() 方法

发送文本消息示例：

const messageBody = {content: 'hello world'};
const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId'
}
const sendRes = await RongIMLib.sendTextMessage(conversation, messageBody);
console.info('消息发送结果：', sendRes);

发送文件消息的快捷方式，等同于使用 new FileMessage() 创建消息体后调用 sendMessage() 方法，支持文件上传，上传成功后自动发送消息

发送文本消息示例：

const msgBody = { file }; // file 为待上传文件
const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId'
}
const sendRes = await RongIMLib.sendFileMessage(conversation, msgBody);
console.info('消息发送结果：', sendRes);

发送图片消息的快捷方式，等同于使用 new ImageMessage() 创建消息体后调用 sendMessage() 方法，支持图片上传，上传成功后自动发送消息

发送图片消息示例：

const msgBody = { file }; // file 为待上传图片
const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId'
}
const sendRes = await RongIMLib.sendImageMessage(conversation, msgBody);
console.info('消息发送结果：', sendRes);

发送 GIF 图片消息的快捷方式，等同于使用 new GIFMessage() 创建消息体后调用 sendMessage() 方法，支持 GIF 图片上传，上传成功后自动发送消息

发送 GIF 图片消息示例：

const msgBody = { file }; // file 为待上传 GIF 图片
const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId'
}
const sendRes = await RongIMLib.sendGIFMessage(conversation, msgBody);
console.info('消息发送结果：', sendRes);

待发送的文件必须为 AAC 音频文件。 发送高清语音消息的快捷方式，等同于使用 new HQVoiceMessage() 创建消息体后调用 sendMessage() 方法，支持高清语音上传，上传成功后自动发送消息

发送高清语音消息示例：

const msgBody = { file }; // file 为待上传高清语音
const conversation = {
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId'
}
const sendRes = await RongIMLib.sendHQVoiceMessage(conversation, msgBody);
console.info('消息发送结果：', sendRes);

发送的小视频消息必须是 MP4 文件，且音频编码为 AAC，视频编码 H264，否则可能造成 iOS 或 Android 接收后不可播放问题。 发送小视频消息的快捷方式，等同于使用 new SightMessage() 创建消息体后调用 sendMessage() 方法，支持小视频上传，上传成功后自动发送消息

发送小视频消息示例：

const msgBody = { file, duration: 10, thumbnail: 'base64' }; // file 为待上传小视频，duration 为小视频时长，thumbnail 为小视频封面 base64
const conversation = {
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId'
}
const sendRes = await RongIMLib.sendSightMessage(conversation, msgBody);
console.info('消息发送结果：', sendRes);

获取历史消息，支持分页加载，可指定时间戳、数量、排序方式等参数进行分页获取。

1. Count 最大值为 100，超过 100 时返回错误码 34232：开发者接口调用时传入的 count 非法
2. 如果 SDK < 5.7.4，范围为 [1-20]；如果 SDK ≧ 5.7.4，范围为 [1-100]。默认值 20

• 注意：

1. Electron 获取的是本地数据库
2. Web 获取的是远端历史消息，Web 端不具备持久化的数据存储能力，无法在本地持久化存储历史消息记录与会话列表，因此需要从融云服务端获取数据。
3. 请确保已开通单群聊消息云端存储服务，如未开通服务请移步到融云开发者后台的 IM 服务管理模块开启。

options = { timestamp: 0, count: 20, order: 0 }

获取历史消息示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const messages = await RongIMLib.getHistoryMessages(conversation);
console.info('获取历史消息结果：', messages);

获取远程历史消息，支持分页加载，可指定时间戳、数量、排序方式等参数进行分页获取。

1. Count 最大值为 100，超过 100 时返回错误码 34232：开发者接口调用时传入的 count 非法
2. 如果 SDK < 5.7.4，范围为 [1-20]；如果 SDK ≧ 5.7.4，范围为 [1-100]。默认值 20

• 注意： 需要开启单群聊消息云存储服务后，才可以从远端拉取历史消息，服务请移步到融云开发者后台的 IM 服务管理模块开启。

options = { timestamp: 0, count: 20, order: 0 }

获取远程历史消息示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const messages = await RongIMLib.getRemoteHistoryMessages(conversation);
console.info('获取远程历史消息结果：', messages);

发送单聊已读回执，用于标记已读消息

• 实现已读功能步骤：

1. 在用户查看了某单聊会话的未读消息后，调用 sendReadReceiptMessage 发送已读回执。
2. 通过 addEventListener 设置消息回执监听器。
3. SDK 在收到消息已读回执时派发 READ_RECEIPT_RECEIVED 事件。

• 注意：

1. 在 Web 平台，SDK 不会记录每个会话和消息的已读状态，您需要在 localStorage 中记录每个会话的已读时间。在渲染消息列表时，根据 localStorage 中时间判断消息是否已读，更新对应的消息界面。
2. 在 Electron 平台，收到 READ_RECEIPT_RECEIVED 通知时，您需要调用 electronExtension.setMessageStatusToRead 方法更新消息已读状态，并更新对应的消息界面。
3. 调用 sendReadReceiptMessage 接口不会清除未读数，需单独调用清除未读数接口 clearMessagesUnreadStatus。

单聊消息回执示例：

const targetId = 'targetId';
const messageUId = 'BS4O-QEBR-VJM6-9GPP';
const timestamp = 1632728573423;

const readReceiptRes = await RongIMLib.sendReadReceiptMessage(targetId, messageUId, timestamp);
console.info('单聊消息回执：', readReceiptRes)

实现群聊中按需获取己方发送消息的阅读状态请求。与群聊已读回执响应接口 sendReadReceiptResponseV2 配套使用。单独调用无法实现群回执能力

群已读回执请求示例：

const targetId = 'targetId';
const messageUId = 'BS4O-QEBR-VJM6-9GPP';
const readReceiptRes = await RongIMLib.sendReadReceiptRequest(targetId, messageUId);
console.info('群已读回执请求：', readReceiptRes)

已废弃，@since 5.1.1。请替换使用 sendReadReceiptResponseV2 方法

实现群聊中按需获取己方发送消息的阅读状态响应。 与群聊已读回执请求接口 sendReadReceiptRequest 配套使用。单独调用无法实现群回执能力

• 注意：

5.9.4 版本之后，SDK 内部维护了已读回执请求信息，并在历史消息列表里携带已读回执信息：readReceiptInfo, 在 Web 平台和 Electron 平台实现不同之处： Web 和 Electron 平台的区别：

1. 在 Web 平台，SDK 内部会缓存每个群会话的最新 30 个已读回执信息（以已读回执请求的发送时间为准），缓存有效期为 24H。 在发送消息回执响应时无需传 messageList 字段，SDK 会把该会话下的所有请求组织好然后发送响应。

2. 在 Electron 平台，用户需先获取历史消息，取出 message.messageDirection = MessageDirection.RECEIVE , readReceiptInfo. isReceiptRequestMessage = true 并且 readReceiptInfo.hasRespond = false 的数据组织成参数 messageList 来发送回执响应。

5.1.1

群已读回执响应示例：

const targetId = 'targetId';
const messageList = {
 'senderUserId': ['messageUId1', 'messageUId2'],
}
const readReceiptRes = await RongIMLib.sendReadReceiptResponseV2(targetId, messageList);
console.info('群已读回执响应：', readReceiptRes);

由于未读消息数存储在本地，服务器不存未读消息数量。当用户多端登录时，需要同步未读消息数以保证多端未读数一致

多端同步阅读状态示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const timestamp = 1632728573423; // 阅读消息的 sendTime
const syncReadStatusRes = await RongIMLib.sendSyncReadStatusMessage(conversation, timestamp);
console.info('多端同步阅读状态：', syncReadStatusRes);

融云对撤回消息的操作者不作限制。 如需避免用户撤回非本人发送的消息，可以提交工单申请打开IMLib SDK 只允许撤回自己发送的消息。从融云服务端进行限制，禁止用户撤回非本人发送的消息。

撤回消息示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const options = {
 messageUId: 'messageUId',
 sentTime: 1632728573423,
}
const recallRes = await RongIMLib.recallMessage(conversation, options);
console.info('撤回消息结果：', recallRes);

根据消息的 ID、时间戳和方向（发送或接收）从服务端删除指定单个会话中的一条或一组消息。

• 注意：

1. 删除消息仅会删除本端消息，不会删除对端消息。A 与 B 之间的消息，A 删除消息后，B 仍然可以看到消息。如 B 需要无法查看需要调用撤回消息 recallMessage接口。
2. 仅适用于 App Key 已开通单群聊消息云端存储 的 App。
3. 服务端默认不会删除对应的离线消息补偿，如需彻底删除消息补偿，请提交工单，申请开通删除服务端历史消息时同时删除多端补偿的离线消息。

按消息 UId 删除消息示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
};
const messages = [{
 messageUId: 'BS4O-P5AO-D1O6-9GPP', // 消息 UId
 sentTime: 1632728573423, // 消息发送时间
 messageDirection: RongIMLib.MessageDirection.SEND, // 消息方向
}];
const deleteRes = await RongIMLib.deleteMessages(conversation, messages);
console.info('删除消息结果：', deleteRes);

根据时间戳删除指定单个会话中早于（含）指定时间戳的所有消息。

按时间戳删除消息示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const timestamp = 1632728573423;
const clearRes = await RongIMLib.clearHistoryMessages(conversation, timestamp);
console.info('清除消息结果：', clearRes);

消息扩展功能可为消息增加基于 Key/Value 的状态标识。消息的扩展信息可在发送前、后设置或更新，可用于实现消息评论、礼物领取、订单状态变化等业务需求。

• 注意：

1. 单条消息单次最多可设置 20 个扩展信息 KV 对，总计不可超过 300 个扩展信息 KV 对。
2. 消息扩展（Key、Value 扩展信息）会被存储。如已开通历史消息云存储功能，从服务端获取的历史消息也会携带已设置的扩展信息。
3. 仅支持单聊、群聊会话类型，不支持聊天室类型。
4. 仅当发送消息时指定 canIncludeExpansion 值为 true，才可对消息进行拓展。

更新（添加、替换）消息扩展属性示例：

const expansion = { key1: 'value1' };
// message 为 IAReceivedMessage 类型消息体，此处不做具体示例，可在消息监听或者获取历史消息接口获取需要操作的 message
const updateRes = await RongIMLib.updateMessageExpansion(expansion, message);
console.info('更新消息扩展属性结果：', updateRes);

删除消息扩展信息中指定的 Key

keys 需删除消息扩展的 keys

message 原始消息体

删除扩展存储示例：

const keys = ['key1'];
// message 为 IAReceivedMessage 类型消息体，此处不做具体示例，可在消息监听或者获取历史消息接口获取需要操作的 message
const removeRes = await RongIMLib.removeMessageExpansionForKey(keys, message);
console.info('删除扩展存储结果：', removeRes);

发送输入状态消息，用于展示对方正在输入的状态

发送输入状态消息示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const typingContentType = RongIMLib.MessageType.TEXT;
const typingRes = await RongIMLib.sendTypingStatusMessage(conversation, typingContentType);
console.info('发送typing消息结果：', typingRes);

const messageUId = 'messageUId';
const targetId = 'targetId';
const getReaderRes = await RongIMLib.getMessageReader(targetId, messageUId);
console.info('获取群已读列表结果：', getReaderRes);

获取指定会话中的第一条未读消息，仅支持 Electron 平台

获取第一条未读消息示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const firstUnreadRes = await RongIMLib.getFirstUnreadMessage(conversation);
console.info('获取第一条未读消息结果：', firstUnreadRes);

5.9.0

获取指定会话中的第一条未读消息信息

• 注意：

1. 当没有未读消息时，返回的 data 为 null
2. 当第一条未读消息被撤回时，此信息不会更新

获取第一条未读消息信息示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const firstUnreadMessageInfoRes = await RongIMLib.getFirstUnreadMessageInfo(conversation);
console.info('获取第一条未读消息信息结果：', firstUnreadMessageInfoRes);

请使用 {@link RongIMLib.ElectronExtension.insertMessage} 代替

获取本地消息, 通过本地消息 ID 或 messageUId 获取消息, 仅支持 Electron 平台

获取消息示例：

const messageUId = 'BS4O-P5AO-D1O6-9GPP';
const getMessageRes = await RongIMLib.getMessage(messageUId);
console.info('获取消息结果：', getMessageRes);

获取会话下所有未读的 @ 消息示例：

const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const getUnreadMentionedRes = await RongIMLib.getUnreadMentionedMessages(conversation);
console.info('获取会话下所有未读的 @ 消息结果：', getUnreadMentionedRes);

已废弃，@since 5.4.0。请替换使用 electronExtension.searchMessages 方法

已废弃，@since 5.4.0。请替换使用 electronExtension.deleteMessagesByTimestamp 方法

已废弃，@since 5.4.0。请替换使用 electronExtension.clearMessages 方法

已废弃，@since 5.4.0。请替换使用 electronExtension.searchConversationByContent 方法

清除时间戳前的未读数，仅支持 Electron 平台。

清除时间戳前的未读数示例：

const conversation = {
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId',
}
const timestamp = 1626955200000;
const clearRes = await RongIMLib.clearUnreadCountByTimestamp(conversation, timestamp);
console.info('清除时间戳前的未读数结果：', clearRes);

已废弃，@since 5.4.0。请替换使用 electronExtension.setMessageReceivedStatusInfo 方法

接口会创建并加入聊天室。如果聊天室已存在，则直接加入聊天室

从 @since 5.8.3 开始废弃该方法，请使用 joinExistChatRoom 代替

聊天室已存在，在获取 chatRoomId 后可以调用 joinExistChatRoom 加入聊天室。该方法只能加入已存在的聊天室。

• 注意：

1. Electron 平台从 5.7.0 开始提供该接口
2. 从 5.8.3 开始，成功回调的 data 数据中返回聊天室信息和禁言状态，详见 IChatroomJoinResponse
3. 断网重连场景下，SDK 重新加入聊天室成功后，会按照加入聊天室时传入的 count 值拉取固定数量的消息。拉取的消息有可能在本地已存在，App 可能需要进行排重后再显示

options.count 为 10

加入已存在的聊天室示例：

const chatRoomId = 'chatroomId';
const options = { count: 10 };
const res = await RongIMLib.joinExistChatRoom(chatRoomId, options);
console.log('加入已存在的聊天室结果：', res);

客户端用户可主动退出聊天室，退出后不再接收聊天室消息

退出聊天室示例：

const chatRoomId = 'chatroomId';
const res = await RongIMLib.quitChatRoom(chatRoomId);
console.log('退出聊天室结果：', res);

获取聊天室的信息，返回聊天室成员总数和指定数量（最多 20 个）的聊天室成员的列表，包括该成员的用户 ID 以及加入聊天室的时间

• 注意：

1. count 或 order 有一个为 0 时，只返回成员总数，不返回成员列表信息， order 人员排序方式，1 为正序，2 为倒序，默认为 0 不返回
2. 单个设备每秒钟支持调用一次，每分钟单个设备最多调用 20 次

查询聊天室房间信息示例：

const chatRoomId = 'chatroomId';
const options = { count: 10, order: 1 };
const res = await RongIMLib.getChatRoomInfo(chatRoomId, options);
console.log('查询聊天室房间信息结果：', res);

设置聊天室属性，支持设置 Key-Value 类型的属性信息

• 功能局限性：

1. 聊天室销毁后，聊天室中的自定义属性同时销毁。
2. 每个聊天室中，最多允许设置 100 个属性信息，以 Key-Value 的方式进行存储。
3. 客户端 SDK 未针对聊天室属性 KV 的操作频率进行限制。建议每个聊天室，每秒钟操作 Key-Value 频率保持在 100 次及以下（一秒内单次操作 100 个 KV 等同于操作 100 次）。

• 注意：

1. 使用该接口需要开通 聊天室属性自定义设置 功能，您可以前往控制台的免费基础功能页面开启服务。
2. 仅聊天室中不存在此属性或属性设置者为己方时可设置成功

设置单个属性示例：

const chatRoomId = 'chatroomId';
const options = {
 key: 'key',
 value: 'value',
};
const res = await RongIMLib.setChatRoomEntry(chatRoomId, options);
console.log('设置单个属性结果：', res);