Skip to main content

Get Conversations

The IMLib SDK automatically generates corresponding conversations in the local database based on messages sent and received by users, while maintaining a conversation list. Applications can retrieve the conversation list from the local database. Starting from version 5.20.0, the SDK supports returning ultra group conversation information in the conversation list, allowing developers to implement mixed sorting of one-to-one, group, and ultra group conversations according to business requirements. This feature requires [submitting a ticket] to enable.

Get a Single Conversation​

Retrieve detailed information about a specific conversation.

Interface​

RongCoreClient.getInstance().getConversation(conversationType, targetId, callback)

Parameter Description​

ParameterTypeDescription
conversationTypeConversationTypeConversation type
targetIdStringConversation ID
callbackResultCallback<Conversation>Callback interface

Example Code​

String conversationType = ConversationType.PRIVATE;
String targetId = "Conversation Id";

RongCoreClient.getInstance().getConversation(conversationType, targetId, new IRongCoreCallback.ResultCallback<Conversation>() {

        @Override
        public void onSuccess(Conversation conversation) {
            // Success with conversation information returned
        }

        @Override
        public void onError(RongIMClient.ErrorCode errorCode) {

        }
});

Batch Get Conversation Information​

In addition to retrieving single conversation information, the IMLib SDK also supports batch retrieval of conversation details.

Interface​

RongCoreClient.getInstance().getConversations(conversationIdentifiers, callback)

Parameter Description​

ParameterTypeDescription
conversationIdentifiersList<ConversationIdentifier>Conversation identifiers
callbackResultCallback<List<Conversation>>Callback interface

Note: The IMLib SDK supports batch conversation retrieval starting from version 5.8.2. Supported conversation types: one-to-one, group, and system.

Use the getConversations() method to query details for multiple conversations.

Example Code​

// Assume we have conversation identifiers conIden1 and conIden2 representing the conversations to query.

List<ConversationIdentifier> conversationIdentifiers = new ArrayList<>();
conversationIdentifiers.add(ConversationIdentifier.obtain(ConversationType.PRIVATE, "tId1", ""));
conversationIdentifiers.add(ConversationIdentifier.obtain(ConversationType.PRIVATE, "tId2", ""));

RongCoreClient.getInstance().getConversations(conversationIdentifiers, new IRongCoreCallback.ResultCallback<List<Conversation>>() {
                    @Override
                    public void onSuccess(List<Conversation> conversations) {
                        // Success with conversation information returned
                    }

                    @Override
                    public void onError(IRongCoreEnum.CoreErrorCode e) {

                    }
                });

Sync Server-Side Conversation Information to Local​

tip

This interface has been available since SDK version 5.20.0. You can submit a ticket to enable this feature.

For scenarios involving device switching or app reinstallation, use the getRemoteConversations() interface to synchronize server-side conversation information to the local device. This interface only triggers the pull operation. After conversation synchronization is complete, use setConversationListener() to monitor the synchronization results. When the onConversationPulled() callback is received, it indicates that the remote conversation list synchronization is complete.

// Initiate a request to pull remote conversations.
RongCoreClient.getInstance().getRemoteConversations(new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {
    }
});
// Register a conversation synchronization listener.
RongCoreClient.getInstance().setConversationListener(new IRongCoreListener.ConversationListener() {
    @Override
    public void onConversationSync() {
    }

    @Override
    public void onConversationPulled(int code) {
    }
});

Get Conversation List​

The conversation list is generated and maintained locally by the SDK. If there has been no reinstallation or device switching, you can retrieve all historical message-generated conversation lists stored on the local device.

Paginated Retrieval of Conversation List​

Retrieve the conversation list generated by the SDK in the local database in paginated form. The returned conversation list is sorted in reverse chronological order. If the result contains conversations set as pinned, pinned conversations will appear at the top by default.

Use the getConversationListByPage method. For the first call, the timestamp (startTime) can be set to 0. Subsequent calls can use the sentTime or operationTime property values of the returned Conversation object as the startTime for the next query. Note: If you are using version 5.6.8 or later, use the operationTime field to avoid potential data omission issues.

tip

This interface supports retrieving ultra group default channel conversations starting from version 5.20.0. To include ultra groups in the list, you need to use Chat Pro Plan (Ultra Group feature is enabled by default for Chat Pro Plan) and submit a ticket to enable this feature.

Interface​

RongCoreClient.getInstance().getConversationListByPage(callback,timeStamp, count, topPriority, conversationTypes);

Parameter Description​

ParameterTypeDescription
callbackResultCallback<List<Conversation>>Method callback.
timeStamplongTimestamp to retrieve conversations older than this timestamp. Set to 0 for the first call to start from the latest. Use actual timestamps for subsequent calls.
countintNumber of conversations to retrieve. It is recommended not to exceed 10, as retrieving too many conversations at once may cause cross-process communication crashes, leading to conversation list retrieval failures and communication interruptions.

When the actual number of retrieved conversations is less than count, it indicates all data has been retrieved.
topPrioritybooleanWhether to prioritize pinned messages. Requires SDK version ≧ 5.6.9.
conversationTypesArray of ConversationTypeSpecify the conversation types to retrieve. Multiple conversation types can be set.

Example Code​

long timeStamp = 0;
int count = 10;
Conversation.ConversationType[] conversationTypes = {ConversationType.PRIVATE, ConversationType.GROUP};

RongCoreClient.getInstance().getConversationListByPage(new IRongCoreCallback.
        ResultCallback<List<Conversation>>() {

    @Override
    public void onSuccess(List<Conversation> conversations) {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode ErrorCode) {

    }
},timeStamp, count, conversationTypes);

To ensure the returned conversation list is strictly sorted in reverse chronological order, use the overloaded method with the topPriority parameter and set it to false. This overloaded method is only available in version 5.6.9 and later.

long timeStamp = 0;
int count = 10;
boolean topPriority = false;

Conversation.ConversationType[] conversationTypes = {ConversationType.PRIVATE, ConversationType.GROUP};

RongCoreClient.getInstance().getConversationListByPage(new IRongCoreCallback.
        ResultCallback<List<Conversation>>() {

    @Override
    public void onSuccess(List<Conversation> conversations) {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode ErrorCode) {

    }
},timeStamp, count, topPriority, conversationTypes);

Retrieving Unread Conversation List​

tip

This API supports retrieving ultra group default channel conversations starting from version 5.20.0. To include ultra groups in the list, you need to use Chat Pro Plan (Ultra Group feature is enabled by default for Chat Pro Plan) and submit a ticket to request activation.

Interface​

RongCoreClient.getInstance().getUnreadConversationList(callback, conversationTypes);

Use the getUnreadConversationList method of RongCoreClient to retrieve a list of conversations with unread messages of specified types, supporting one-to-one chat, group chat, and system conversations. The returned conversation list is sorted in reverse chronological order, with pinned conversations appearing first.

Parameter Description​

ParameterTypeDescription
callbackResultCallback<List<Conversation>>Callback interface
conversationTypesArray of ConversationTypeConversation type array

Example Code​

ConversationType[] conversationTypes = {ConversationType.PRIVATE, ConversationType.GROUP, ConversationType.SYSTEM};

RongCoreClient.getInstance().getUnreadConversationList(new IRongCoreCallback.ResultCallback<List<Conversation>>() {

        @Override
        public void onSuccess(List<Conversation> conversations) {
            // Successfully returns conversation information
        }

        @Override
        public void onError(IRongCoreEnum.CoreErrorCode e) {

        }
}, conversationTypes);

Retrieving Conversation List by Type​

tip

This interface has been available since SDK version 5.24.0.

Use the getConversationListByFilters interface to retrieve conversation lists by conversation type.

Interface​

List<ConversationTypeFilter> filters = new ArrayList<>();
ConversationTypeFilter filter = new ConversationTypeFilter();
filter.setType(Conversation.ConversationType.PRIVATE);
filter.setChannelId("ChannelId"); // Channel ID list for filtering channel IDs. Valid values include "" or strings; null is not allowed
filters.add(filter);

ConversationListOption option = new ConversationListOption();
option.setCount(20); // Number of conversations to retrieve, default is 20. When the actual number of retrieved conversations is less than count, it indicates all data has been fetched.
option.setStartTime(0); // Conversation timestamp in milliseconds. Retrieves conversation lists before this timestamp; 0 means starting from the latest.
option.setTopPriority(true); // Sorting method for query results. If true, pinned conversations are prioritized; otherwise, results are sorted only by conversation time.

 ChannelClient.getInstance().getConversationListByFilters(filters, option, new IRongCoreCallback.ResultCallback<List<Conversation>>() {
    @Override
    public void onSuccess(List<Conversation> conversations) {
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
    }
});

Parameter Description​

ParameterTypeDescription
filtersListFilter conditions
optionConversationListOptionQuery conditions
calbbackResultCallbackCallback interface

Example Code​

ConversationType[] conversationTypes = {ConversationType.PRIVATE, ConversationType.GROUP, ConversationType.SYSTEM};

RongCoreClient.getInstance().getUnreadConversationList(new IRongCoreCallback.ResultCallback<List<Conversation>>() {

        @Override
        public void onSuccess(List<Conversation> conversations) {
            // Successfully returns conversation information
        }

        @Override
        public void onError(IRongCoreEnum.CoreErrorCode e) {

        }
}, conversationTypes);

Handling Scenarios After Reinstallation or Device Switching​

If your users reinstall the app or log in from a different device, they may find the conversation list empty or perceive that some conversations are missing.

Reasons include:

  • Uninstalling deletes the local database, resulting in no historical messages locally and an empty conversation list after reinstallation.

  • Logging in from a different device may result in no local historical message data, leading to an empty conversation list.

  • If your App Key has enabled the Multi-Device Message Synchronization feature, the server will also activate the message compensation function. The server automatically synchronizes messages from the same day after 00:00 when the SDK successfully connects. After receiving the compensated messages from the server, the IMLib SDK can generate partial conversations and conversation lists. Compared to before uninstalling or switching devices, there may be a perception that some conversations are missing.

If you wish to retrieve the previous conversation list after reinstallation or device switching, consider the following solutions:

  • Request to increase the number of days for message compensation, up to a maximum of 7 days. Note: Setting this period too long may cause excessive message compensation for users with extremely high message volumes, leading to performance issues on the client side. If needed, please submit a ticket.

  • Maintain the conversation list on your own server and retrieve the required historical messages from the server via API.

Last updated on