RongIMLib - v5.14.1

支持按照 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);

发送文件消息的快捷方式，等同于使用 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);

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

多端同步阅读状态示例：

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

根据消息的 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);

消息扩展功能可为消息增加基于 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);

根据消息的 Uid 从服务端获取特定批量消息

5.2.0 仅 Web 端 IMLib 支持超级群。Electron 解决方案暂不适用于超级群业务。

从服务端获取特定批量消息示例：

const options = {
conversationType: RongIMLib.ConversationType.ULTRA_GROUP,
targetId: 'targetId',
channelId: 'channelId',
};
// sendTime 为消息的发送时间，此处示例为假数据
const messages = [{ messageUId: 'messageUId1', sendTime: 1626864000000, }];
const res = await RongIMLib.getUltraGroupMessageListByMessageUId(options, messages);
console.log('从服务端获取特定批量消息结果：', res);

设置、更新消息扩展信息，用于超级群消息扩展信息的设置、更新，消息扩展信息 适用场景：原始消息增加状态标识的需求，都可使用消息扩展

1. 消息评论需求，可通过设置原始消息扩展信息的方式添加评论信息。
2. 礼物领取、订单状态变化需求，通过此功能改变消息显示状态。 例如：向用户发送礼物，默认为未领取状态，用户点击后可设置消息扩展为已领取状态 注意：
3. 每次设置消息扩展将会产生内置通知消息，频繁设置扩展会产生大量消息
4. 仅当发送消息时指定 canIncludeExpansion 值为 true，才可对消息进行扩展

5.2.0 仅 Web 端 IMLib 支持超级群。Electron 解决方案暂不适用于超级群业务。

设置、更新消息扩展信息示例：

const expansion = { key1: 'value1' };
const message = {} // 需要设置的消息，类型为 IAReceivedMessage
const res = await RongIMLib.updateExpansionForUltraGroupMessage(expansion, message);
console.log('设置、更新消息扩展信息结果：', res);

删除消息扩展，用于超级群消息扩展信息的删除，消息扩展信息

5.2.0 仅 Web 端 IMLib 支持超级群。Electron 解决方案暂不适用于超级群业务。

删除消息扩展示例：

const expansion = ['key1'];
// message 需要删除扩展的消息，类型为 IAReceivedMessage，此处示例伪代码
const res = await RongIMLib.removeExpansionForUltraGroupMessage(expansion, message);
console.log('删除消息扩展结果：', res);

删除指定消息上的所有扩展，用于超级群消息扩展信息的删除，消息扩展信息

5.2.0 仅 Web 端 IMLib 支持超级群。Electron 解决方案暂不适用于超级群业务。

删除指定消息上的所有扩展示例：

// message 需要删除扩展的消息，类型为 IAReceivedMessage，此处示例伪代码
const res = await RongIMLib.removeAllExpansionForUltraGroupMessage(message);
console.log('删除指定消息上的所有扩展结果：', res);

用户在成功发送超级群消息后，可以主动修改已发送消息的消息内容 消息被修改后，IAReceivedMessage 对象的 isModifyMessage 属性会被更新为 true 注意：

1. 消息类型无法修改。如果改前为文本消息，则传入的新消息内容必须为 ITextMessageBody 类型
2. 无法修改他人发送的消息。

5.2.0 仅 Web 端 IMLib 支持超级群。Electron 解决方案暂不适用于超级群业务。

修改消息示例：

const content = { text: '修改后的消息内容' };
// message 需要修改的消息，类型为 IAReceivedMessage，此处示例伪代码
const res = await RongIMLib.modifyMessage(content, message);
console.log('修改消息结果：', res);

此方法用于订阅一组用户的状态。当这些用户的状态发生变化时，将通过回调接口通知调用者 注意：

1. 一次订阅用户的上限为 200 个, 订阅的用户数最多为 1000 个，一个用户最多可以被 5000 个用户订阅
2. 订阅用户在线状态能力需要开通服务，开通路径： IM 服务 > IM 服务管理 > 客户端用户在线状态订阅

5.9.8

订阅用户状态示例：

const userIds = ['user1', 'user2'];
const subscribeType = RongIMLib.SubscribeType.ONLINE_STATUS;
// 设置订阅时间，取值范围为[60,2592000]（单位:秒）。
const expiry = 60;
const res = await RongIMLib.subscribeUserStatus(userIds, subscribeType, expiry);
console.log('订阅用户状态结果：', res);

Passes the user authentication token (Token) to initiate a connection request to the RC chat server. Note:

1. The connect() method must be called after SDK initialization init to establish the connection. Otherwise, callbacks may not be triggered.
2. The SDK has an automatic reconnection mechanism. It is unnecessary to call connect() multiple times within the application lifecycle.
3. Call it once during the application lifecycle.

Example of establishing an IM connection:

const token = '<Your-token>';
const res = await RongIMLib.connect(token);
console.info('IM connection result:', res);

After calling this method, you will no longer receive messages, cannot send messages, cannot retrieve historical messages, and cannot fetch the conversation list. Use Case: Recommended for account logout or account switching scenarios.

Example of disconnecting:

await RongIMLib.disconnect();
console.info('Disconnected successfully');
```ts

Removes all listener functions for a specific event

Example of removing an event:

RongIMLib.removeEventListeners(Events.MESSAGES);

Example of clearing all events:

RongIMLib.clearEventListeners();

Initializes the IM SDK with the provided Appkey and related configuration information.

Initialization example:

RongIMLib.init({ appkey: 'appkey' });
console.log('Initialization complete');

Uninitializes the SDK, clears all listeners and timers, and stops log reporting and other services. Applicable Scenarios:

1. Recommended for use when the application exits.
2. When changing the appkey, call this method first, then reinitialize using the new Appkey with the init method.

Uninitialization example:

await RongIMLib.destroy();
console.log('Uninitialization completed');

Example of getting IM connection status:

const status = RongIMLib.getConnectionStatus();
console.log('IM connection status:', status);

Example of getting the current user ID:

const userId = RongIMLib.getCurrentUserId();
console.log('Current user ID:', userId);

Retrieves the unique identifier of the current device

Example of getting deviceId:

const deviceId = RongIMLib.getDeviceId();
console.log('Device ID:', deviceId);

Creates and joins a chatroom. If the chatroom already exists, the user will join directly.

This method is deprecated starting from @since 5.8.3. Please use joinExistChatRoom instead.

The chatroom already exists. After obtaining the chatRoomId, you can call joinExistChatRoom to join the chatroom. This method can only be used to join existing chatrooms. Note:

1. This interface is available on the Electron platform starting from version 5.7.0
2. Starting from version 5.8.3, the success callback's data includes chatroom information and mute status. For details, see IChatroomJoinResponse
3. In the case of reconnection after a network disconnection, the SDK will rejoin the chatroom and pull a fixed number of messages based on the count value passed when joining the chatroom. The pulled messages may already exist locally, and the app may need to deduplicate them before displaying.

options.count is 10

Example of joining an existing chatroom:

const chatRoomId = 'chatroomId';
const options = { count: 10 };
const res = await RongIMLib.joinExistChatRoom(chatRoomId, options);
console.log('Result of joining an existing chatroom:', res);

The client user can actively exit the chatroom. After exiting, the user will no longer receive chatroom messages.

Example of exiting a chatroom:

const chatRoomId = 'chatroomId';
const res = await RongIMLib.quitChatRoom(chatRoomId);
console.log('Exit chatroom result:', res);

Retrieves chatroom information, including the total number of members and a list of up to 20 chatroom members, along with their user IDs and join timestamps. Note:

1. If either count or order is 0, only the total number of members is returned, and the member list is not included. The order parameter specifies the sorting order: 1 for ascending, 2 for descending, and 0 (default) for no sorting.
2. A single device can call this API once per second, with a maximum of 20 calls per minute.

Example of querying chatroom information:

const chatRoomId = 'chatroomId';
const options = { count: 10, order: 1 };
const res = await RongIMLib.getChatRoomInfo(chatRoomId, options);
console.log('Chatroom information query result:', res);

Sets chatroom attributes, supporting Key-Value type attribute information. Limitations:

1. Custom attributes in a chatroom will be destroyed when the chatroom is destroyed.
2. Each chatroom allows a maximum of 100 attributes to be stored in Key-Value format.
3. The client SDK does not limit the operation frequency of chatroom attribute Key-Value pairs. It is recommended to keep the Key-Value operation frequency below 100 times per second for each chatroom (a single operation of 100 Key-Value pairs within one second is equivalent to 100 operations).

• Note:

1. To use this interface, you need to enable the Chatroom Custom Attribute Settings feature. You can enable this service on the Basic Features page in the Console.
2. The attribute can only be successfully set if it does not exist in the chatroom or if the attribute setter is the user themselves.

Example of setting a single attribute:

const chatRoomId = 'chatroomId';
const options = {
key: 'key',
value: 'value',
};
const res = await RongIMLib.setChatRoomEntry(chatRoomId, options);
console.log('Result of setting a single attribute:', res);

Batch sets chatroom attributes Limitations: Custom attributes in a chatroom will be destroyed when the chatroom is destroyed. Each chatroom allows a maximum of 100 attributes to be stored in Key-Value pairs. The client SDK does not limit the frequency of Key-Value operations for chatroom attributes. It is recommended to keep the Key-Value operation frequency at or below 100 times per second (a single operation of 100 KVs within one second is equivalent to 100 operations). * Note:

1. To use this interface, you need to enable the Chatroom Custom Attributes feature. You can activate this service on the Basic Features page in the Console.
2. Attributes can only be set successfully if the attribute does not exist in the chatroom or if the attribute setter is yourself.

Example of batch setting attributes:

const chatRoomId = 'chatroomId';
const options = { entries: [{ key: 'key', value: 'value' }] };
const res = await RongIMLib.setChatRoomEntries(chatRoomId, options);
console.log('Batch set attributes result:', res);

Force sets a single chatroom attribute. This can be used to modify attribute values created by others, stored in the form of key = value. When the key does not exist, it represents adding an attribute; when the key already exists, it represents updating the attribute's value. Using force set allows modifying attribute values created by others.

Example of force setting a single attribute:

const chatRoomId = 'chatroomId';
const options = {
 key: 'key',
 value: 'value',
};
const res = await RongIMLib.forceSetChatRoomEntry(chatRoomId, options);
console.log('Result of force setting a single attribute:', res);

Deletes a custom attribute of the chatroom. Only attributes created by the current user can be deleted.

Example of deleting a single attribute:

const targetId = 'chatroomId';
const options = {
key: 'key',
};
const res = await RongIMLib.removeChatRoomEntry(targetId, options);
console.log('Result of deleting a single attribute:', res);

Deletes custom attributes of a chatroom. Only attributes created by the current user can be deleted.

Example of batch deleting chatroom attributes:

const targetId = 'chatroomId';
const options = {
entries: ['key'],
};
const res = await RongIMLib.removeChatRoomEntries(targetId, options);
console.log('Result of batch deleting chatroom attributes:', res);

Forcibly deletes custom attributes of a chatroom. Can delete attributes created by others.

Example of force deletion:

const targetId = 'chatroomId';
const options = {
key: 'key',
};
const res = await RongIMLib.forceRemoveChatRoomEntry(targetId, options);
console.log('Force deletion result:', res);

Retrieves a single chatroom attribute

Example of getting a single attribute:

const targetId = 'chatroomId';
const key = 'key';
const res = await RongIMLib.getChatRoomEntry(targetId, key);
console.log('Get single attribute result:', res);

Retrieves all attributes of the chatroom

Example of retrieving all attributes:

const targetId = 'chatroomId';
const res = await RongIMLib.getAllChatRoomEntries(targetId);
console.log('Result of retrieving all attributes:', res);

The API for retrieving chatroom history messages requires the Cloud Storage for Chatroom Messages service to be enabled. Please ensure the service is activated before use. Once enabled, chatroom history messages are stored in the cloud by default for 2 months.

Example of retrieving chatroom history messages:

const chatRoomId = 'chatroomId';
const options = {
 count: 10,
 order: 1,
 timestamp: 0,
};
const res = await RongIMLib.getChatroomHistoryMessages(chatRoomId, options);
console.log('Retrieved chatroom history messages:', res);

Once the chatroom is successfully bound to the RTC room, the chatroom will not be automatically destroyed as long as the RTC room still exists. Use Case: Chatrooms have an auto-destruction mechanism. In apps that use RC's RTC service, the IM SDK's chatroom feature may be used to implement live chat, bullet comments, and attribute recording. In such cases, you can consider binding the chatroom to the RTC room to ensure the chatroom is not destroyed before the voice chat or live stream ends, preventing the loss of critical data.

5.2.1

Example of binding an RTC room:

const option = {
chatRoomId: 'chatroomId',
rtcRoomId: 'rtcRoomId',
};
const res = await RongIMLib.bindRTCRoomForChatroom(option);
console.log('RTC room binding result:', res);
```ts

The API to get the conversation list requires enabling cloud storage for one-to-one and group messages before data can be retrieved from the server. The server-side conversation list storage limit is 1000. Note: When called on the Electron platform, parameter values are ignored, and all conversation lists are returned by default. Electron platform users are advised to consider using other APIs to retrieve the conversation list. If the limit exceeds 1000, the earliest conversations will be deleted based on the timestamp of the last message.

count: 20, startTime: 0, order: 0 *

Example of getting the conversation list:

const conversationList = await RongIMLib.getConversationList();
console.info('Conversation list result:', conversationList);

The conversation obtained through this method may not exist in the current conversation list. This is only a functional encapsulation syntactic sugar.

Example of fetching specified conversation data:

const options = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}
const conversation = await RongIMLib.getConversation(options);
console.info('Fetched specified conversation data result:', conversation);

Removes the specified conversation without deleting the messages within it Note:

1. Deleting a conversation does not clear its unread count. It is recommended to call the clearMessagesUnreadStatus interface before deleting the conversation to prevent unread count anomalies
2. Conversations are generated by messages. If new messages are generated in the conversation, the conversation will be recreated

Example of removing a specified conversation:

const options = {
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId',
}
const conversation = await RongIMLib.removeConversation(options);
console.info('Result of removing the specified conversation:', conversation);

@since 5.3.0 Deprecated, please use setConversationNotificationLevel

Query the Do Not Disturb settings for a specific conversation and channel set via the setConversationNotificationLevel interface

1. For the Electron platform, support for the setConversationNotificationLevel interface starts from version 5.8.4.

5.3.0

Example of querying Do Not Disturb for a specific conversation and channel:

const options = {
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId',
}
const conversation = await RongIMLib.getConversationNotificationLevel(options);
console.info('Do Not Disturb query result for the specified conversation and channel:', conversation);

Deprecated since 5.3.0. For versions 5.3.0 and above, use the getConversationNotificationLevel interface.

Retrieves all conversations that have Do Not Disturb status enabled. This API is only supported on the Web platform.

5.1.1

Example of getting the Do Not Disturb status list:

const list = await RongIMLib.getBlockedConversationList();
console.info('Result of getting the Do Not Disturb status list:', list);

isUpdateTime Defaults to true

Example of setting whether a conversation is pinned to the top:

const isTop = true
const options = {
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId',
}
const res = await RongIMLib.setConversationToTop(options, isTop);
console.info('Result of setting whether a conversation is pinned to the top:', res);

Note: The latestMessage field will not be included in the returned data on the Web platform.

5.6.0

Example of getting the pinned conversation list:

const res = await RongIMLib.getTopConversationList();
console.info('Number of pinned conversations retrieved:', res);

Note: The returned data on the Web platform will not include the latestMessage field.

5.7.0

Example of getting the unread conversation list:

const res = await RongIMLib.getUnreadConversationList();
console.info('Unread conversation list result:', res);

1. Clearing browser cache may cause inaccuracies in the unread count
2. The unread message count is stored in WebStorage. If the browser does not support or has disabled WebStorage, the unread count will not be saved, and refreshing the browser page will result in the loss of the unread count
3. Deleting a conversation on other devices may cause inaccuracies in the unread count

includeMuted: false

Example of getting the total unread message count for all current conversations:

const totalUnreadCount = await RongIMLib.getTotalUnreadCount();
console.info('Result of getting the total unread message count for all current conversations:', totalUnreadCount);

Finds conversations whose Do Not Disturb configurations match the specified levels and returns the total unread message count across all conversations. Note:

1. Chatroom conversations do not store unread counts, so retrieving unread counts for chatroom conversations is not supported.

5.5.1 Not supported on Electron platform

Example of getting the unread count of conversations with specified Do Not Disturb levels:

const conversationTypes = [RongIMLib.ConversationType.PRIVATE];
const levels = [RongIMLib.NotificationLevel.ALL_MESSAGE];
const totalUnreadCount = await RongIMLib.getTotalUnreadCountByLevels(conversationTypes, levels);
console.info('Result of getting the unread count of conversations with specified Do Not Disturb levels:', totalUnreadCount);

Finds conversations whose Do Not Disturb configuration matches the specified levels and returns the total count of unread mentions across all conversations

5.5.1 Not supported on Electron platform