Pin Conversation

The pin conversation feature provides the following capabilities:

• Pin a conversation in the conversation list: Controlled by the isTop property of the Conversation object.
• Pin a conversation among conversations with the same tag (requires the use of the Conversation Tag feature): Controlled by the isTop property of the ConversationTagInfo class.

Pin a Conversation in the Conversation List

After setting a specific conversation to be pinned in the conversation list, the SDK will modify the isTop field of the Conversation object. This status will be synchronized to the server. RC automatically synchronizes the pinned conversation status data for users. The client can actively retrieve or obtain the latest data through a listener.

Set a Conversation as Pinned

Use setConversationToTop to pin a conversation.

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

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

        @Override
        public void onSuccess(Boolean success) {

        }

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

        }
    }) ;

Parameter	Type	Description
conversationType	ConversationType	Conversation type, supports one-to-one chat, group chat, and system conversation.
targetId	String	Conversation ID
isTop	boolean	Whether to pin. true to pin, false to unpin.
callback	ResultCallback<Boolean>	Callback interface

The client automatically generates conversations and conversation lists from local message data and synchronizes the pinned status across multiple devices logged in by the user. If the conversation does not exist locally or on other devices logged in by the user when calling this API, the SDK handles it as follows:

• If the SDK version ≧ 5.6.8, the SDK will automatically create the conversation and pin it if the conversation does not exist locally or on other devices logged in by the user.
• If the SDK version < 5.6.8, you must use the overloaded method that supports the needCreate parameter and set it to true for the SDK to automatically create the conversation and pin it. For details, see the API reference setConversationToTop.

Set Conversation Pin with Optional Time Update (SDK version ≧ 5.8.2)

Use setConversationToTop to pin a conversation.

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

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

        @Override
        public void onSuccess(Boolean success) {

        }

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

        }
    }) ;

Parameter	Type	Description
conversationType	ConversationType	Conversation type, supports one-to-one chat, group chat, and system conversation.
targetId	String	Conversation ID
isTop	boolean	Whether to pin. true to pin, false to unpin.
needCreate	boolean	Whether to create. true to create, false to not create.
needUpdateTime	boolean	Whether to update the time. true to update, false to not update.
callback	ResultCallback<Boolean>	Callback interface

Listen for Pin Status Synchronization

The SDK provides a conversation status (pinned status and Do Not Disturb status) synchronization mechanism. After setting the conversation status synchronization listener, if the conversation status changes, the local device will be notified.

After the pinned and Do Not Disturb status data of a conversation is synchronized, the onStatusChanged method of ConversationStatusListener is triggered. For detailed instructions, see Multi-Device Synchronization of Do Not Disturb/Pin.

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

Get Conversation Pin Status

tip

This feature is supported starting from SDK version 5.1.5.

Actively retrieve the pinned status of a specified conversation.

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

Parameter	Type	Description
targetId	String	Conversation ID
conversationType	ConversationType	Conversation type
callback	IRongCoreCallback.ResultCallback	Callback result

Get Pinned Conversation List

Actively retrieve all pinned conversations of a specified conversation type.

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

RongIMClient.getInstance().getTopConversationList(new ResultCallback<List<Conversation>>() {
            @Override
            public void onSuccess(List<Conversation> conversations) {

            }

            @Override
            public void onError(ErrorCode e) {

            }
        }, conversationTypes);

Parameter	Type	Description
callback	ResultCallback<List<Conversation>>	Callback interface
conversationTypes	Conversation.ConversationType...	Conversation type array

Pin a Conversation Among All Conversations with the Same Tag

tip

The related interfaces for this feature are only available in RongCoreClient. Pinning a conversation among all conversations with the same tag is achieved by modifying the ConversationTagInfo.isTop field, which does not affect the isTop field of Conversation.

If the app implements the Conversation Tag feature, app users may use the same tag to mark multiple conversations and need to pin one of them. The SDK provides the isTop property in ConversationTagInfo to control whether a conversation should be pinned among conversations with the same tag.

Pin a Conversation Under a Tag

Pin a specified conversation among all conversations with the same tag. For example, pin the private chat conversation with "Tom" among all conversations tagged with "Training Class".

String targetId = "useridoftom";
ConversationIdentifier conversationIdentifier = new ConversationIdentifier(Conversation.ConversationType.PRIVATE, targetId);
String tagId = "peixunban";

RongCoreClient.getInstance().setConversationToTopInTag(tagId, conversationIdentifier, isTop,
    new IRongCoreCallback.OperationCallback() {
            /**
             * Success callback
             */
            @Override
            public void onSuccess() {

            }

            /**
             * Failure callback
             * @param errorCode Error code
             */
            @Override
            public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

            }
        });

Parameter	Type	Description
tagId	String	Tag ID
conversationIdentifier	ConversationIdentifier	Conversation identifier, requires specifying the conversation type (ConversationType) and Target ID.
isTop	boolean	Whether to pin
callback	OperationCallback	Operation callback

Get Conversation Pin Status Under a Tag

Query whether a specified conversation is pinned among all conversations with the same tag. Returns whether it is pinned upon success.

RongCoreClient.getInstance().getConversationTopStatusInTag(conversationIdentifier, tagId,
    new IRongCoreCallback.ResultCallback<Boolean>() {
            /**
             * Success callback
             */
            @Override
            public void onSuccess(Boolean bool) {

            }
            /**
             * Failure callback
             * @param errorCode Error code
             */
            @Override
            public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

            }
        });

Enable Synchronization of Empty Pinned Conversations

This feature is supported starting from version 5.10.0.

When you uninstall and reinstall the app or log in on a different device, RC allows you to decide whether to retain pinned conversations in the conversation list, including those that do not yet contain any messages. By default, these pinned statuses will be retained.

You can choose whether to enable the synchronization of pinned conversations during SDK initialization. By calling the enableSyncEmptyTopConversation method of the InitOption class and passing true or false as a parameter, you can enable or disable this feature. By default, this feature is disabled.

Sample Code

InitOption initOption = new InitOption.Builder()
    .enableSyncEmptyTopConversation(true)
    .build();
RongCoreClient.init(context, appKey, initOption);