Conversation Pinning

IMKit provides functionality to pin conversations and display pinned conversations.

Usage

When a conversation is pinned, this status will be synchronized to the server. RC automatically synchronizes pinned conversation status data across devices for users. Clients can receive synchronization notifications through listeners or actively fetch the latest data.

Note: Synchronization of pinned conversations is enabled by default. However, empty conversations won't be synchronized by default starting from version 5.10.1. To enable synchronization for empty conversations, use the enableSyncEmptyTopConversation interface in InitOption with parameter true to enable or false to disable.

Customization

If IMKit's default implementation doesn't meet your requirements, you can use the APIs provided by IMKit.

Pin a Conversation

When a conversation is pinned, it will appear at the top of the conversation list. All pinned conversations are sorted in descending order based on conversation time. Clients typically generate conversations and conversation lists automatically using local message data. If the conversation you want to pin doesn't exist locally, you can create it using the needCreate parameter.

Interface

IMCenter.getInstance().setConversationToTop(conversationType, targetId, isTop, needCreate, callback);

Parameters

Parameter	Type	Description
conversationType	ConversationType	Conversation type
targetId	String	Conversation ID
isTop	boolean	Whether to pin (true for pin, false to unpin)
needCreate	boolean	Whether to create the conversation if it doesn't exist
callback	ResultCallback<Boolean>	Callback interface

Example Code

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = "Conversation ID";
boolean isTop = true;
boolean needCreate = true;

IMCenter.getInstance().setConversationToTop(conversationType, targetId, isTop, needCreate, new
    ResultCallback<Boolean>() {

        @Override
        public void onSuccess(Boolean success) {

        }

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

        }
    });

Listen for Pinned Status Synchronization

The IM service supports a synchronization mechanism for conversation status (pinned status and Do Not Disturb status data). After setting up a conversation status synchronization listener, you'll receive notifications when conversation status changes on the local device.

When pinned or Do Not Disturb status data is synchronized, the SDK triggers the onStatusChanged method of ConversationStatusListener. For details, see Multi-Device Synchronization for Do Not Disturb/Pinned Conversations.

public interface ConversationStatusListener {
  void onStatusChanged(ConversationStatus[] conversationStatus);
}

Get Pinned Status and Pinned Conversations

You can actively fetch pinned status data and pinned conversations from the client, but IMKit SDK doesn't provide direct methods for this. You'll need to use methods from IMLib.

For details, see Get Pinned Status and Get Pinned Conversation List in the IMLib documentation Conversation Pinning.