Get Conversation

tip

• The Web platform lacks persistent data storage capabilities and cannot locally store historical message records and conversation lists. Therefore, data needs to be retrieved from the RC server.The Cloud Storage for One-to-One and Group Messages service is enabled by default. You can retrieve historical messages for one-to-one and group chats from the RC server directly. If you are using an App Key in the production environment, this service is available for Chat Starter Plan or Chat Pro Plan. For specific features and pricing, refer to the Billing Guide document.
• Remote conversation retrieval must be performed after successfully establishing a connection by calling RongIMLib.connect().
• The server conversation list has a storage limit of 1000 conversations, with a validity period matching that of Cloud Storage for One-to-One and Group Messages, defaulting to 6 months.

Conversation List Support for Ultra Groups

Starting from version 5.20.0, the SDK supports returning ultra group conversation information in the conversation list, allowing developers to mix and sort one-to-one, group, and ultra group conversations based on business needs. This feature requires [submitting a ticket] to enable.

Once enabled, after a successful connection, the SDK pulls all conversation data from the server to local memory for maintenance. When developers call the interface, relevant conversation data is returned from memory based on query conditions.

Notes

• After one-to-one and group chat conversations are synchronized, the SDK notifies the Events.CONVERSATIONS_SYNCED event. After ultra group conversations are synchronized, the SDK notifies the Events.ULTRA_GROUP_ENABLE event. It is recommended to fetch and render the conversation list only after receiving both events to avoid data loss or sorting issues.
• The Electron platform has supported ultra group functionality since version 5.28.0.
• The conversation list results only include the default channel conversations of ultra groups, excluding sub-channel conversations.

Retrieve Conversation List

Starting from version 5.28.0, the SDK introduces the [getConversationListByTimestamp] interface to replace the original [getConversationList] interface, addressing ambiguity issues in the original interface.

Ambiguity Issues in the Original [getConversationList] Interface:

1. Non-Electron platforms: The channelId parameter is invalid, and the interface always retrieves conversations by timestamp.
2. Electron platforms:
   • When channelId is a string, its behavior aligns with non-Electron platforms, returning data by timestamp.
   • When channelId is undefined, the interface returns all data stored in the local database.

Parameter Description

Parameter	Type	Required	Description
params	[IGetConversationListByTimestampParams]	Yes	Query parameters

[IGetConversationListByTimestampParams] Structure Attribute Description

Attribute	Type	Required	Description
startTime	number	Yes	Start time for retrieving conversations, in milliseconds. 0 represents the current time.
count	number	Yes	Number of conversations to retrieve
order	number	No	Query direction, which also affects result sorting. This parameter is invalid for Electron platforms. 0 - Query backward from startTime, with results sorted in descending order by time. 1 - Query forward from startTime, with results sorted in ascending order by time.
topPriority	boolean	No	Whether to prioritize pinned conversations in sorting
conversationTypes	Array<ConversationType>	No	Conversation types. If empty or length is 0, all conversation types are retrieved. This parameter is only valid for Electron platforms.

Example Code

const params = {
  startTime: 0,
  count: 10,
};

RongIMLib
  .getConversationListByTimestamp(params)
  .then(res => {
    if (res.isOk) {
      console.log('Retrieval successful:', res.data);
    } else {
      console.log('Retrieval failed:', res.code);
    }
  });

Interface Usage Recommendations

When calling this interface on the Web platform, the retrieved data is from the server-stored conversations. To improve performance and reduce interface call risks, follow these guidelines:

Initial Data Retrieval After pulling offline messages, the business layer can proactively call this interface once and assign the returned conversation data to the rendering data to ensure initial state completeness.

Data Update Method Subsequent conversation updates will be returned via the Conversation Change Notification Event Listener. The business layer can merge the event data with local rendering data without frequently calling the getConversationListByTimestamp interface.

Avoid Frequent Interface Calls Do not call the getConversationListByTimestamp interface every time a message is sent or received to fetch remote conversation lists, as this may cause:

1. Interface errors or request failures.
2. The returned conversation data may not be the latest.
3. Repeated remote data retrieval increases network load and reduces application performance.

Server-Side Sorting Rules

The server sorts conversations by the timestamp of the last message:

• Retrieve the latest conversations: Set order = 0 and startTime = 0 to query conversations older than the current time, returning the latest list.
• Retrieve the earliest conversations from the server: Set order = 1 and startTime = 0 to fetch the earliest conversations from the server, up to 1000 entries.
• Pagination: For paginated queries, use the latestMessage.sendTime of the last [IAReceivedConversation] from the previous response as the new startTime for subsequent requests.

Retrieve All Conversations

When you need to fetch all conversation data at once, use the [getAllConversationList] interface. This multi-platform interface replaces electronExtension.getAllConversationList.

warning

• The retrieve-all-conversations interface is supported starting from version 5.28.0.
• Querying all conversations imposes significant data retrieval pressure, so use it cautiously. We recommend using the [getConversationListByTimestamp] interface for paginated queries.

Example Code

RongIMLib
  .getAllConversationList()
  .then(res => {
    if (res.isOk) {
      console.log('Conversation list retrieved successfully:', res.data);
    } else {
      console.log('Conversation list retrieval failed:', res.code);
    }
  });

Retrieve a Specific Conversation

tip

The conversation retrieved via this method may not exist in the current conversation list. This is purely a functional syntactic sugar.

Call the [getConversation] method to retrieve the specified [IAReceivedConversation].

Interface

RongIMLib.getConversation(conversation)

Parameter Description

Parameter	Type	Required	Description
conversation	[IConversationOption]	Yes	Target conversation

Example Code

const conversationType = RongIMLib.ConversationType.PRIVATE;
const targetId = 'Recipient's userId';

RongIMLib.getConversation({
    conversationType,
    targetId,
}).then(res => {
  if (res.code === 0) {
    console.log(res.code, res.data)
  } else {
    console.log(res.code, res.msg)
  }
})

Retrieve Pinned Conversation List

tip

• Supported since SDK version 5.6.0.

Call [getTopConversationList] to retrieve the pinned conversation list.

Interface

RongIMLib.getTopConversationList(conversationTypes, channelId)

Parameter Description

Parameter	Type	Required	Description
conversationTypes	[ConversationType][]	Yes	Array of conversation types, defaults to all types

Example Code

const conversationTypes = [RongIMLib.ConversationType.PRIVATE, RongIMLib.ConversationType.GROUP, RongIMLib.ConversationType.SYSTEM];

RongIMLib.getTopConversationList(conversationTypes).then(res => {
  if (res.code === 0) {
    console.log(res.code, res.data)
  } else {
    console.log(res.code, res.msg)
  }
})

Retrieve Unread Conversation List

tip

• Supported since SDK version 5.7.0.

Call [getUnreadConversationList] to retrieve the list of conversations with unread messages.

Interface

RongIMLib.getUnreadConversationList(conversationTypes)

Parameter Description

Parameter	Type	Required	Description
conversationTypes	[ConversationType][]	Yes	Array of conversation types

Example Code

const conversationTypes = [RongIMLib.ConversationType.PRIVATE, RongIMLib.ConversationType.GROUP, RongIMLib.ConversationType.SYSTEM];

RongIMLib.getUnreadConversationList(conversationTypes).then(res => {
  if (res.code === 0) {
    console.log(res.code, res.data)
  } else {
    console.log(res.code, res.msg)
  }
})

Retrieve Do Not Disturb Conversation List

Call [getBlockedConversationList] to retrieve the list of conversations with Do Not Disturb configured.

tip

• Starting from version 5.28.0, this interface supports the Electron platform.

Interface

RongIMLib.getBlockedConversationList()


#### Code Example

```js
RongIMLib.getBlockedConversationList().then(res => {
  if (res.code === 0) {
    console.log(res.code, res.data)
  } else {
    console.log(res.code, res.msg)
  }
})
<!-- links -->
[IAReceivedConversation]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IAReceivedConversation.html
[IGetConversationListByTimestampParams]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IGetConversationListByTimestampParams.html
[IConversationOption]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#IConversationOption
[ConversationType]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/enums/ConversationType.html
[MentionedInfo]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#MentionedInfo
[getConversationList]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getConversationList
[getConversation]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getConversation
[getTopConversationList]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getTopConversationList
[getUnreadConversationList]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getUnreadConversationList
[getBlockedConversationList]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getBlockedConversationList
[getConversationListByTimestamp]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getConversationListByTimestamp
[getAllConversationList]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getAllConversationList
[提交工单]: https://console.rongcloud.io/agile/formwork/ticket/create