Conversation Pinning

The conversation pinning feature provides the following capabilities:

• Pin a conversation in the conversation list: Controlled by the isTop property of the RCConversation object.
• Pin a conversation among those with the same tag (requires the use of the Conversation Tag feature): Controlled by the isTop property of the RCConversationTagInfo 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 RCConversation object, and this state will be synchronized to the server. RC will automatically synchronize the pinned conversation state data for the user. The client can actively retrieve or obtain the latest data through a listener.

Set Conversation Pinning

Use setConversationToTop:targetId:isTop:completion: to pin a conversation.

// Set the conversation type and target ID
RCConversationType conversationType = ConversationType_PRIVATE;
NSString *targetId = @"your_target_id";

// Set the conversation to top or not
BOOL isTop = YES;

[[RCCoreClient sharedCoreClient] setConversationToTop:conversationType
                                             targetId:targetId
                                                isTop:isTop
                                           completion:^(BOOL success) {}];

Parameter	Type	Description
conversationType	RCConversationType	Conversation type, supports one-to-one chat, group chat, and system conversation.
targetId	NSString	Conversation ID
isTop	BOOL	Whether to pin
completion	Block	Callback for pinning result

The client automatically generates conversations and conversation lists from local message data and synchronizes the pinned state across multiple devices where the user is logged in. If the conversation to be pinned does not exist locally or on other devices where the user is logged in (the conversation has not been generated or has been removed) when calling this API, the SDK will directly create the conversation and pin it.

Set Conversation Pinning with Optional Time Update

Use setConversationToTop:targetId:isTop:needUpdateTime:completion: to pin a conversation.

// Set the conversation type and target ID
RCConversationType conversationType = ConversationType_PRIVATE;
NSString *targetId = @"your_target_id";

// Set the conversation to top or not
BOOL isTop = YES;

[[RCCoreClient sharedCoreClient] setConversationToTop:conversationType
                                             targetId:targetId
                                                isTop:isTop
                                       needUpdateTime:YES
                                           completion:^(BOOL success) {}];

Parameter	Type	Description
conversationType	RCConversationType	Conversation type, supports one-to-one chat, group chat, and system conversation.
targetId	NSString	Conversation ID
isTop	BOOL	Whether to pin
needUpdateTime	BOOL	Whether to update time
completion	Block	Callback for pinning result

The client automatically generates conversations and conversation lists from local message data and synchronizes the pinned state across multiple devices where the user is logged in. If the conversation to be pinned does not exist locally or on other devices where the user is logged in (the conversation has not been generated or has been removed) when calling this API, the SDK will directly create the conversation and pin it.

Get Pinning Status

tip

• Supported starting from version 5.1.5.
• Starting from version 5.3.0 of RCCoreClient, it is recommended to use the asynchronous result-returning interface below, while the original synchronous interface is deprecated.

Actively retrieve the pinned status of a specific conversation.

RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];
[[RCCoreClient sharedCoreClient] getConversationTopStatus:iden completion:^(BOOL){
    // Asynchronous callback, whether retrieval was successful
}];

Parameter	Type	Description
conversationIdentifier	RCConversationIdentifier	Conversation identifier, requires specifying the conversation type (RCConversationType) and Target ID.
completion	Block	Returns whether the setting was successful.

Get Pinned Conversation List

Actively retrieve all pinned conversations of a specified conversation type.

NSArray *conversations = [[RCIMClient sharedRCIMClient] getTopConversationList:@[@(ConversationType_PRIVATE),@(ConversationType_GROUP)]];

Parameter	Type	Description
conversationTypes	NSArray	Array of conversation types, requires converting RCConversationType to NSNumber to build the Array

Upon successful retrieval, returns a list of RCConversation objects.

Pin a Conversation Among Conversations with the Same Tag

tip

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

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 field in RCConversationTagInfo to control the pinned state of a conversation among conversations with the same tag.

Pin a Conversation Under a Tag

Set a specific conversation to be pinned among all conversations with a specified tag. For example, pin the private chat conversation with "Tom" among all conversations tagged with "Training Class".

NSString targetId = @"useridoftom";
NSString *tagId = @"peixunban";
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:targetId];

[[RCCoreClient sharedCoreClient] setConversationToTopInTag:tagId conversationIdentifier:iden isTop:isTop success:^{

        } error:^(RCErrorCode errorCode) {

        }];

Parameter	Type	Description
tagId	String	Tag ID
conversationIdentifier	RCConversationIdentifier	Conversation identifier, requires specifying the conversation type (RCConversationType) and Target ID.
isTop	BOOL	Whether to pin
successBlock	Block	Success callback
errorBlock	Block	Failure callback. The errorCode parameter returns RCErrorCode.

Get Pinning Status of a Conversation Under a Tag

tip

Starting from version 5.3.0 of RCCoreClient, it is recommended to use the asynchronous result-returning interface below, while the original synchronous interface is deprecated.

Query whether a specific conversation is pinned among all conversations with the same tag. Upon successful retrieval, returns whether it is pinned.

RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

[[RCCoreClient sharedCoreClient] getConversationTopStatusInTag:iden tagId:@"tagId" completion:^(BOOL){
        // Asynchronous callback, returns the pinned status
}];

Parameter	Type	Description
tagId	NSString	Tag ID
conversationIdentifier	RCConversationIdentifier	Conversation identifier, requires specifying the conversation type (RCConversationType) and Target ID.
completion	Block	Asynchronous callback, returns whether it is pinned

Enable Synchronization of Empty Pinned Conversations (SDK Version ≧ 5.10.0)

After reinstalling or logging in on a different device, pinned conversations will be displayed in the conversation list, including empty pinned conversations.

Starting from version 5.10.0, support for enabling or disabling the synchronization of empty pinned conversations is available.

This can be set during SDK initialization via the enableSyncEmptyTopConversation property of RCInitOption. If not set, the SDK defaults to not automatically synchronizing empty pinned conversations.

Note If the synchronization of empty pinned conversations is enabled, when paginating to retrieve conversation data, the first page should pass 0 for startTime, and subsequent pages should pass the operationTime value of the conversation object.

RCInitOption *initOption = [[RCInitOption alloc] init];
// Enable synchronization of empty pinned conversations
initOption.enableSyncEmptyTopConversation = YES;
// Initialize SDK
[[RCCoreClient sharedCoreClient] initWithAppKey:@"your_appkey" option:initOption];