Conversation Pinning

The conversation pinning feature provides the following capabilities:

Pin conversations in the conversation list: Controlled via the isTop property of the RCConversation object.
Pin conversations within the same tag (requires [Conversation Tags] feature): Controlled via the isTop property of the [RCConversationTagInfo] class.
Starting from v5.20.0, ultra group conversations support pinning (requires submitting a [ticket] for activation).

Listening for Pinning Status Synchronization

The SDK provides a conversation status synchronization mechanism (for both pinning and Do Not Disturb statuses). After setting up the status synchronization listener, local clients will receive notifications when conversation statuses change.

When conversation pinning or Do Not Disturb statuses are synchronized, the onStatusChanged method of ConversationStatusListener is triggered. For details, see Multi-device Do Not Disturb/Pinning Synchronization.

Pinning Conversations in the Conversation List

When you pin a specific conversation in the conversation list, the IMLib SDK modifies the isTop field of [RCConversation], and this status will be synchronized to the server. RC automatically synchronizes pinned conversation statuses for users. Clients can actively retrieve or listen for the latest data.

tip

Starting from v5.3.0, it's recommended to use the asynchronous result-returning interface, while the original synchronous interface is deprecated.

Setting Conversation Pinning

Use [setConversationToTop:targetId:isTop:completion:] to pin conversations.

Interface Prototype

- (void)setConversationToTop:(RCConversationType)conversationType
                    targetId:(NSString *)targetId
                       isTop:(BOOL)isTop
                  completion:(nullable void(^)(BOOL ret))completion;

Parameter Description

Parameter	Type	Description
conversationType	[RCConversationType]	Conversation type (supports one-to-one, group, and system conversations)
targetId	NSString	Conversation ID
isTop	BOOL	Whether to pin
completion	Block	Callback for pinning result

Example Code

// 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) {}];

The client automatically generates conversations and conversation lists from local message data, and synchronizes pinning statuses across all logged-in devices. If the conversation to be pinned doesn't exist locally or on other logged-in devices (either not yet generated or already removed) when calling this API, the SDK will directly create and pin the conversation.

Setting Conversation Pinning with Optional Time Update

Use [setConversationToTop:targetId:isTop:needUpdateTime:completion:] to control whether to update the conversation timestamp when pinning.

Interface Prototype

- (void)setConversationToTop:(RCConversationType)conversationType
                    targetId:(NSString *)targetId
                       isTop:(BOOL)isTop
              needUpdateTime:(BOOL)needUpdateTime
                  completion:(nullable void(^)(BOOL result))completion;

Parameter Description

Parameter	Type	Description
conversationType	[RCConversationType]	Conversation type (supports one-to-one, group, system, and ultra group conversations)
targetId	NSString	Conversation ID
isTop	BOOL	Whether to pin
needUpdateTime	BOOL	Whether to update conversation timestamp
completion	Block	Callback for pinning result

Example Code

// 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, group, system, and ultra group conversations)
targetId	NSString	Conversation ID
isTop	BOOL	Whether to pin
needUpdateTime	BOOL	Whether to update timestamp
completion	Block	Callback for pinning result

Batch Setting Conversation Pinning

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

    RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] init];
    identifier.type = ConversationType_GROUP;
    identifier.targetId = @"tId";
    RCConversationTopOption *option = [[RCConversationTopOption alloc] init];
    option.needCreateConversation = YES;
    option.needUpdateTime = YES;
    [[RCCoreClient sharedCoreClient] setConversationsToTop:@[identifier]
                                                     isTop:YES
                                                    option:option
                                                completion:^(RCErrorCode code) {
        // set conversation top
    }];

Parameter	Type	Description
conversationIdentifiers	[RCConversationIdentifier]	List of conversation identifiers
isTop	BOOL	Whether to pin
option	RCConversationTopOption	Configuration (supports setting timestamp update and conversation creation)
completion	Block	Callback for pinning result

Checking Pinning Status

tip

Supported since v5.1.5.

You can actively check the pinning status of a specific conversation.

Interface Prototype

- (void)getConversationTopStatus:(RCConversationIdentifier *)conversationIdentifier
                      completion:(nullable void(^)(BOOL ret))completion;

Parameter Description

Parameter	Type	Description
conversationIdentifier	[RCConversationIdentifier]	Conversation identifier (requires specifying [RCConversationType] and Target ID)
completion	Block	Returns whether the operation succeeded

Example Code

RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];
[[RCCoreClient sharedCoreClient] getConversationTopStatus:iden completion:^(BOOL){
    //Asynchronous callback indicating whether retrieval succeeded
}];
### Retrieving Pinned Conversation List

You can actively retrieve all pinned conversations of specified types.
#### Interface Prototype
```objectivec
- (void)getTopConversationList:(NSArray<NSNumber *> *)conversationTypeList

completion:(nullable void(^)(NSArray<RCConversation *>  *_Nullable conversationList))completion;


#### Parameter Description
| Parameter | Type | Description |
| :------ | :------ | :--------- |
| conversationTypes | NSArray | Array of conversation types, requires converting [RCConversationType] to NSNumber to build the Array |
| completion | Block | Returns a list of [RCConversation] objects upon successful retrieval. |


#### Example Code
```objectivec
[[RCCoreClient sharedCoreClient] getTopConversationList:@[@(ConversationType_PRIVATE)]
                                                 completion:^(NSArray<RCConversation *> *conversationList) {
}];


## Pinning Conversations Across All Tagged Conversations

:::tip

 These related interfaces are only available in `RCCoreClient`. Pinning a conversation across all conversations marked with the same tag is achieved by modifying the `RCConversationTagInfo.isTop` field, which does not affect the `isTop` field in [RCConversation].
:::

If the app implements the [conversation tag] feature, app users may mark multiple conversations with the same tag and need to pin one of them. The SDK provides the `isTop` field in [RCConversationTagInfo] to control the pinned status of a conversation among all conversations sharing the same tag.


### Pinning a Conversation Under a Tag

You can pin a specified conversation among all conversations marked with a given tag. For example, pinning a private chat with **Tom** among all conversations tagged with **Training Class**.


#### Interface Prototype
```objectivec


- (void)setConversationToTopInTag:(NSString *)tagId
           conversationIdentifier:(RCConversationIdentifier *)conversationIdentifier
                            isTop:(BOOL)top
                          success:(nullable void (^)(void))successBlock
                            error:(nullable void (^)(RCErrorCode errorCode))errorBlock;


#### Parameter Description
| Parameter | Type | Description |
| :-----|:-----|:----|
| tagId | String | Tag ID |
| conversationIdentifier | [RCConversationIdentifier] | Conversation identifier, requiring specification of conversation type ([RCConversationType]) and Target ID. |
|isTop | BOOL | Whether to pin |
| successBlock | Block | Success callback |
| errorBlock | Block | Failure callback. The `errorCode` parameter returns [RCErrorCode]. |


#### Example Code
```objectivec
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) {

        }];


### Retrieving Pinned Status of a Conversation Under a Tag

You can check whether a specified conversation is pinned among all conversations sharing the same tag. Upon successful retrieval, it returns whether the conversation is pinned.


#### Interface Prototype
```objectivec


- (void)getConversationTopStatusInTag:(RCConversationIdentifier *)conversationIdentifier
                                tagId:(NSString *)tagId
                           completion:(nullable void(^)(BOOL ret))completion;


#### Parameter Description
| Parameter | Type | Description |
| ---- | ---- | ---- |
| tagId | NSString | Tag ID |
| conversationIdentifier | [RCConversationIdentifier] | Conversation identifier, requiring specification of conversation type ([RCConversationType]) and Target ID. |
| completion | Block | Asynchronous callback returning pinned status |


#### Example Code
```objectivec
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

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


## Enabling Synchronization of Empty Pinned Conversations (SDK Version ≥ 5.10.0)

When users reinstall the app or log in from a different device, pinned conversations may appear in the conversation list, including empty pinned conversations.

Starting from version 5.10.1, you can enable or disable the synchronization of empty pinned conversations.
You can configure this during SDK initialization via the `enableSyncEmptyTopConversation` property in `RCInitOption`. If not set, the SDK defaults to not synchronizing empty pinned conversations automatically.
:::tip
If synchronization of empty pinned conversations is enabled, when paginating conversation data, set `startTime` to 0 for the first page, and use the `operationTime` value of the conversation object for subsequent pages.
:::


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

IMLib

IMKit

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

CallLib

CallKit

RTCLib

Chat Server

Chat Server SDK

Audio & Video Server

Conversation Pinning

Listening for Pinning Status Synchronization​

Pinning Conversations in the Conversation List​

Setting Conversation Pinning​

Interface Prototype​

Parameter Description​

Example Code​

Setting Conversation Pinning with Optional Time Update​

Interface Prototype​

Parameter Description​

Example Code​

Batch Setting Conversation Pinning​

Checking Pinning Status​

Interface Prototype​

Parameter Description​

Example Code​

Listening for Pinning Status Synchronization

Pinning Conversations in the Conversation List

Setting Conversation Pinning

Interface Prototype

Parameter Description

Example Code

Setting Conversation Pinning with Optional Time Update

Interface Prototype

Parameter Description

Example Code

Batch Setting Conversation Pinning

Checking Pinning Status

Interface Prototype

Parameter Description

Example Code