Skip to main content

Pinning Conversations

The conversation pinning feature provides the following capabilities:

  • Pin conversations in the conversation list: Controlled through the isTop property of the Conversation object.
  • Pin conversations within the same tag group (requires [conversation tags] feature): Controlled through the isTop property of the ConversationTagInfo class.
  • Starting from version 5.20.0, ultra group conversations can be pinned. Ultra group functionality requires [submitting a ticket] to enable.

Pinning Conversations in the Conversation List​

When a conversation is pinned in the conversation list, the SDK modifies the isTop field of the Conversation object. This status will be synchronized to the server. RC automatically synchronizes pinned conversation status data for users. Clients can actively retrieve or listen for the latest data.

Setting Conversation Pinning​

Use setConversationToTop to pin a conversation.

Interface​

RongIMClient.getInstance().setConversationToTop(conversationType, targetId, isTop, callback);

Parameter Description​

ParameterTypeDescription
conversationTypeConversationTypeConversation type, supports one-to-one, group, system, and ultra group conversations.
targetIdStringConversation ID
isTopbooleanWhether to pin. true for pin, false for unpin.
callbackResultCallback<Boolean>Callback interface

Example Code​

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) {

        }
    }) ;

The client automatically generates conversations and conversation lists from local message data, and synchronizes pinned status across multiple devices where the user is logged in. When calling this API, if the conversation doesn't exist or has been removed, the SDK handles it as follows:

  • For SDK versions ≧ 5.6.8: When the conversation to be pinned doesn't exist locally or on other devices where the user is logged in, the SDK automatically creates and pins the conversation.
  • For SDK versions < 5.6.8: You must use the overloaded method with the needCreate parameter and set it to true for the SDK to automatically create and pin the conversation. See API reference setConversationToTop.

Setting Conversation Pinning with Optional Time Update (SDK version ≧ 5.8.2)​

Use setConversationToTop to pin a conversation.

Interface​

RongCoreClient.getInstance().setConversationToTop(conversationType, targetId, isTop, needCreate, needUpdateTime, callback)

Parameter Description​

ParameterTypeDescription
conversationTypeConversationTypeConversation type, supports one-to-one, group, system, and ultra group conversations.
targetIdStringConversation ID
isTopbooleanWhether to pin. true for pin, false for unpin.
needCreatebooleanWhether to create. true to create, false to not create.
needUpdateTimebooleanWhether to update time. true to update, false to not update.
callbackResultCallback<Boolean>Callback interface

Example Code​

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) {

        }
    }) ;
ParameterTypeDescription
conversationTypeConversationTypeConversation type, supports one-to-one, group, and system conversations.
targetIdStringConversation ID
isTopbooleanWhether to pin. true for pin, false for unpin.
needCreatebooleanWhether to create. true to create, false to not create.
needUpdateTimebooleanWhether to update time. true to update, false to not update.
callbackResultCallback<Boolean>Callback interface

Batch Setting Conversation Pinning​

Use the setConversationsToTop:isTop:option:completion: interface to batch pin conversations.

List<ConversationIdentifier> identifiers = new ArrayList<>();
ConversationIdentifier identifier = ConversationIdentifier.obtain(
    Conversation.ConversationType.PRIVATE,
    "targetId",
    ""
);
identifiers.add(identifier);
ConversationTopOption option = new ConversationTopOption(true, true);

RongCoreClient.getInstance().setConversationsToTop(identifiers, true, option, new IRongCoreCallback.ResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean aBoolean) {
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode code) {
    }
});
ParameterTypeDescription
conversationIdentifiersConversationIdentifierList of conversation identifiers
isTopbooleanWhether to pin
optionConversationTopOptionConfiguration options, supports setting whether to update time and create conversations
callbackIRongCoreCallback.ResultCallbackCallback for pinning results

Listening for Pinning Status Synchronization​

The SDK provides a conversation status (pinning and Do Not Disturb status data) synchronization mechanism. After setting up a conversation status synchronization listener, you'll receive notifications when conversation status changes.

When conversation pinning or Do Not Disturb status is synchronized, it triggers the onStatusChanged method of ConversationStatusListener. For details, see Multi-Device Do Not Disturb/Pinning Synchronization.

tip

Starting from version 5.24.0, ConversationStatusListener includes a conversation status synchronization completion callback. When synchronization completes, it triggers the onConversationStatusSync method callback.

Example Code​

public interface ConversationStatusListener {
  // Multi-device synchronization listener for conversation status (pinning and Do Not Disturb)
  void onStatusChanged(ConversationStatus[] conversationStatus);
  // Conversation status synchronization completion
  void onConversationStatusSync(IRongCoreEnum.CoreErrorCode code);
}

Getting Conversation Pinning Status​

tip

This feature is supported starting from SDK version 5.1.5.

Actively retrieve the pinned status of a specified conversation.

Interface​

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

Parameter Description​

ParameterTypeDescription
targetIdStringConversation ID
conversationTypeConversationTypeConversation type
callbackIRongCoreCallback.ResultCallbackCallback result

Retrieve Pinned Conversation List​

Actively retrieve all pinned conversations of specified conversation types.

Parameter Description​

ParameterTypeDescription
callbackResultCallback<List<Conversation>>Callback interface
conversationTypesConversation.ConversationType...Conversation type array

Sample Code​

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);

Pinning Conversations Among All Tagged Conversations​

tip

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

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

Pinning a Conversation Under a Tag​

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

Interface​

RongCoreClient.getInstance().setConversationToTopInTag(tagId, conversationIdentifier, isTop, callback)

Parameter Description​

ParameterTypeDescription
tagIdStringTag ID
conversationIdentifierConversationIdentifierConversation identifier, requiring specification of conversation type (ConversationType) and Target ID.
isTopbooleanWhether to pin
callbackOperationCallbackOperation callback

Sample Code​

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) {

            }
        });

Retrieving Pinned Status of a Conversation Under a Tag​

Query whether a specified conversation is pinned among all conversations sharing the same tag. Returns the pinned status upon successful retrieval.

Sample Code​

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) {

            }
        });

Enabling 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 from a different device, Rong Cloud allows you to decide whether to retain pinned conversations in the conversation list, including empty conversations that contain no messages. By default, these pinned states are preserved.

You can choose whether to enable the synchronization of pinned conversations during SDK initialization. Call the enableSyncEmptyTopConversation method of the InitOption class and pass true or false as a parameter to 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);
Last updated on