Conversation Pinning

IMKit supports displaying pinned conversations.

tip

IMKit can pin conversations to the top of the conversation list based on their pinned property, but does not provide built-in UI for setting this feature.

Limitations

• IMKit does not provide built-in UI for pinning conversations.

Usage

You need to implement the conversation pinning feature in your UI. When a user pins a conversation, the status will be synchronized to the server. RC automatically syncs pinned conversation status data across devices. Clients can receive sync notifications via listeners.

Setting Pinned Status

When a conversation is pinned, it appears at the top of the conversation list. All pinned conversations are sorted in descending order by conversation time.

The IMKit SDK does not directly provide this method—you need to use the IMLib method to pin conversations.

Method Prototype

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

Parameters

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. Supports one-to-one chat, group chat, and system conversation.
targetId	NSString	Target ID of the conversation.
isTop	BOOL	Whether to pin the conversation.
completion	Block	Callback for the pinning operation 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 IMKit SDK typically generates conversations and conversation lists automatically from local message data. If a pinned conversation does not exist locally, the SDK will create it automatically.

Listening for Pinned Status Sync

The IM service supports conversation status synchronization (including pinned and Do Not Disturb status data). After setting a conversation status sync listener, your client will receive notifications when conversation status changes.

When pinned or Do Not Disturb status data is synchronized, the SDK dispatches the following notification:

FOUNDATION_EXPORT NSString *const RCKitDispatchConversationStatusChangeNotification;  

The notification's object is an array of RCConversationStatusInfo objects, and userInfo is nil.

1. Register the notification listener:

[[NSNotificationCenter defaultCenter] addObserver:self  
                                             selector:@selector(onConversationStatusChanged:)  
                                                 name:RCKitDispatchConversationStatusChangeNotification  
                                               object:nil];  

2. Update your conversation status upon receiving the notification:

- (void)onConversationStatusChanged:(NSNotification *)notification {  
    NSArray<RCConversationStatusInfo *> *conversationStatusInfos = notification.object;  
}  

Retrieving Pinned Status and Pinned Conversations

You can proactively fetch conversation pinned status data and pinned conversations from the client.

The IMKit SDK does not directly provide this method—you need to use IMLib methods. For details, refer to the IMLib documentation under Conversation Pinning, specifically Retrieving Pinned Status and Retrieving Pinned Conversation List.

Controlling Pinned Conversation Display Order

To customize the display order of pinned conversations at the top of the list, modify the data source. Override the willReloadTableData: method in RCConversationListViewController to reorganize the data source and return it, adjusting the pinned conversation order as needed.

/*!  
  Callback before reloading incremental data source.  

  @param dataSource      Incremental data source to be loaded (elements are RCConversationModel objects)  
  @return                Modified data source (elements are RCConversationModel objects)  

  @discussion You can modify, add, or delete elements in the data source to customize the displayed content.  
              The conversation list will render based on the modified data source you return.  

  Data source elements are conversation cell data models (RCConversationModel objects).  

  Versions 2.9.21 and earlier: dataSource is the full data (conversationListDataSource = dataSource).  
  Versions 2.9.22 and later: dataSource is incremental (conversationListDataSource += dataSource).  
                              To modify full data, adjust conversationListDataSource directly.  
*/  
- (NSMutableArray *)willReloadTableData:(NSMutableArray *)dataSource;