Skip to main content

Get Conversations

The IMLib SDK automatically generates corresponding conversations in the local database based on messages sent and received by users, and maintains a conversation list. Applications can retrieve the conversation list from the local database. Starting from version 5.20.0, the SDK supports returning ultra group conversation information in the conversation list. You can mix and sort one-to-one chats, group chats, and ultra group conversations according to your business needs. This feature requires [submitting a ticket] for activation.

Get a Single Conversation​

You can use [getConversation:targetId:completion:] to retrieve detailed information about a specific conversation.

Method Signature​



- (void)getConversation:(RCConversationType)conversationType
               targetId:(NSString *)targetId
             completion:(nullable void(^)(RCConversation *_Nullable conversation))completion;


#### Parameters
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| conversationType | [RCConversationType] | Conversation type. For one-to-one chat, use ConversationType_PRIVATE |
| targetId | NSString | Conversation targetId |
| completion | Block | Callback that returns an [RCConversation] object |


#### Example Code
```objectivec
[[RCCoreClient sharedCoreClient] getConversation:ConversationType_PRIVATE
                                      targetId:@"targetId"
                                    completion:^(RCConversation *conversation) {

}];


## Batch Get Conversation Information

In addition to retrieving single conversations, you can also batch get conversation details through the IMLib SDK.

:::tip


- Client SDK supports batch conversation retrieval starting from version 5.8.2.


- Supported conversation types: one-to-one chat, group chat, and system conversations.
:::

Use the `getConversations:success:error:` method to query multiple conversations. If only some conversations exist locally, the `successBlock` will only return locally available conversations. If none of the requested conversations are found locally, the `errorBlock` callback will be triggered.


#### Method Signature
```objectivec


- (void)getConversations:(NSArray<RCConversationIdentifier *> *)conversationIdentifiers
                 success:(nullable void(^)(NSArray<RCConversation *> * conversations))successBlock
                   error:(nullable void (^)(RCErrorCode status))errorBlock;


#### Parameters
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| conversationIdentifiers | NSArray | Array of conversation identifiers to query (max 100 per request) |
| success | Block | Success callback returning an array of conversation information |
| error | Block | Error callback returning an error code |


#### Example Code
```objectivec
// Assume we have conversation identifiers conIden1 and conIden2
RCConversationIdentifier *conIden1 = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"tId1"];

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

NSArray *conversationIdentifiers = @[
    conIden1,
    conIden2
    // Add more identifiers as needed
];

[[RCCoreClient sharedCoreClient] getConversations:conversationIdentifiers
                                          success:^(NSArray<RCConversation *> * _Nonnull conversations) {
                                              // Handle successful retrieval
                                          }
                                          error:^(RCErrorCode status) {
                                              // Handle error
                                              NSLog(@"Error fetching conversations: %@", @(status));
                                          }];


## Sync Server Conversations to Local

:::tip
Available since SDK version 5.20.0. Requires [submitting a ticket] to enable this feature.
:::

For scenarios like device switching or app reinstallation, use `getRemoteConversationListWithSuccess:error:` to sync server conversations to local (up to 1000 conversations). This only triggers the sync operation - use the `RCConversationDelegate` to monitor sync results. The `remoteConversationListDidSync:` callback indicates completion.

```objectivec
// Initiate remote conversation sync
[[RCCoreClient sharedCoreClient] getRemoteConversationListWithSuccess:^{
    // Success
} error:^(RCErrorCode errorCode) {
    // Failure
}];
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| success | Block | Success callback |
| error | Block | Error callback |

```objectivec
// Register conversation sync delegate
[[RCCoreClient sharedCoreClient] setRCConversationDelegate:self];

// Sync completion callback


- (void)remoteConversationListDidSync:(RCErrorCode)code {
    if (RC_SUCCESS == code ) {
        // Sync complete
    }
}


## Get Conversation List

The conversation list is generated and maintained locally by the IMLib SDK. Unless the app was reinstalled or the user logged in from a different device, you can retrieve all historical conversations stored locally.


### Paginated Conversation List

Use [getConversationList:count:startTime:completion:] to paginate through locally stored conversations. Results are returned in reverse chronological order, with pinned conversations appearing first by default.

For the initial request, pass `0` as `startTime`. Subsequent requests should use the `operationTime` from the returned [RCConversation] objects.

:::tip
Starting from version 5.6.8, use `operationTime`. For versions before 5.6.8, also use `sentTime`.
:::


#### Method Signature
```objectivec


- (void)getConversationList:(NSArray<NSNumber *> *)conversationTypeList
                      count:(int)count
                  startTime:(long long)startTime
                 completion:(nullable void(^)(NSArray<RCConversation *> *_Nullable conversationList))completion;
For strictly time-ordered results (without pinned priority), use this variant (available since 5.6.9):

```objectivec


- (void)getConversationList:(NSArray<NSNumber *> *)conversationTypeList
                      count:(int)count
                  startTime:(long long)startTime
                topPriority:(BOOL)topPriority
                 completion:(nullable void(^)(NSArray<RCConversation *> *_Nullable conversationList))completion;


#### Parameters
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| conversationTypeList | NSArray | Array of conversation types (RCConversationType as NSNumber) |
| count | int | Number of conversations to retrieve |
| startTime | long long | Timestamp for pagination (0 for initial request) |
| topPriority| boolean | Whether to prioritize pinned messages (SDK ≥ 5.6.9) |
| completion | Block | Success callback returning conversation list |


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

[[RCCoreClient sharedCoreClient] getConversationList:@[@(ConversationType_PRIVATE)]
                                               count:100
                                           startTime:0
                                         topPriority:NO
                                          completion:^(NSArray<RCConversation *> *conversationList) {
}];


### Get Unread Conversation List


:::tip

This interface has been available since IMLib SDK version 5.3.2.
:::

You can use [getUnreadConversationList:completion:] to retrieve a list of conversations with unread messages for specified types, supporting one-to-one chat, group chat, and system conversations. It returns an [RCConversation] list, with conversations sorted in reverse chronological order (top-pinned conversations appear first).


#### Interface Prototype
```objectivec


- (void)getUnreadConversationList:(NSArray<NSNumber *> *)conversationTypeList
                       completion:(nullable void(^)(NSArray<RCConversation *> *_Nullable conversationList))completion;


#### Parameter Description
| Parameter | Type | Description |
|:---|:---|:---|
| conversationTypeList | NSArray | Array of conversation types (requires converting RCConversationType to NSNumber) |
| completion | Block | Callback for successful retrieval of conversation list |


### Get Unread Mention Conversations

:::tip

This interface has been available since IMLib SDK version 5.28.0.
:::

Use [getUnreadMentionMeConversationList:completion:] to retrieve conversations containing unread @mentions. Supports one-to-one chat, group chat, system conversations, ultra groups, and other conversation types, returning an [RCConversation] list.

Results are sorted in reverse chronological order, with pinned conversations prioritized at the top.


#### Interface Prototype
```objectivec


- (void)getUnreadMentionMeConversationList:(RCGetUnreadMentionMeConversationListParams *)params
                                completion:(nullable void(^)(NSArray<RCConversation *> *conversations,
                                                             RCErrorCode code))completion;


#### Parameter Description (RCGetUnreadMentionMeConversationListParams)
| Parameter | Type | Description |
|:---|:---|:---|
| `conversationTypes` | NSArray | Target conversation type array (requires converting RCConversationType to NSNumber) |
| `topPriority` | BOOL | Whether to prioritize pinned conversations (YES = pinned first, NO = time-sorted only). Default: YES |
| `timestamp` | long long | Query start time (0 = latest conversations). Unit: milliseconds |
| `count` | NSUInteger | Number of results (valid range: [1,100]). Default: 0 |


#### Example Code
```objectivec
// Create parameter object
RCGetUnreadMentionMeConversationListParams *params = [[RCGetUnreadMentionMeConversationListParams alloc] init];

// Set target types: private, group, ultra group
params.conversationTypes = @[@(ConversationType_PRIVATE), @(ConversationType_GROUP), @(ConversationType_ULTRAGROUP)];
params.count = 100;
params.timestamp = 0; // Query latest conversations

// Call the method
[[RCCoreClient sharedCoreClient] getUnreadMentionMeConversationList:params
                                                         completion:^(NSArray<RCConversation *> * _Nullable conversations, RCErrorCode code) {
    NSLog(@"getUnreadMentionMeConversationList:%@", conversations);
}];


### Get Conversation List by Type

:::tip
Available since SDK version 5.20.0.
:::

Use `getConversationListByFilters:option:completion:` to retrieve conversations by type.

```objectivec
RCConversationTypeFilter *filter = [[RCConversationTypeFilter alloc] initWithType:ConversationType_GROUP];
RCConversationListOption *option = [[RCConversationListOption alloc] init];
option.startTime = 0;
option.count = 20;
option.topPriority = YES;
[[RCChannelClient sharedChannelManager] getConversationListByFilters:@[filter]
                                                              option:option
                                                          completion:^(NSArray<RCConversation *> *conversations, RCErrorCode code) {
    // get conversations.
}];
| Parameter | Type | Description |
| :--------------- | :----------------------- | :--------- |
| filter | NSArray | Filter conditions |
| option | RCConversationListOption | List configuration |
| completion | Block | Success callback |


#### Example Code
```objectivec
[[RCCoreClient sharedCoreClient] getUnreadConversationList:@[@(ConversationType_GROUP),@(ConversationType_SYSTEM),@(ConversationType_PRIVATE)]
                                                completion:^(NSArray<RCConversation *> * _Nullable conversationList) {

}];


### Handling Reinstallation or Device Switching

If users reinstall the app or log in from a new device, they may find empty conversation lists or missing conversations because:


- Uninstallation deletes the local database, removing all message history


- New devices lack local message history


- With [Multi-Device Message Synchronization](https://console.rongcloud.io/agile/im/service/config#Multi%20Client) enabled, the server automatically syncs messages from midnight onward after connection. While this recreates some conversations, differences may occur compared to the original list.

To recover conversation lists after reinstallation/device switching: <!--public-cloud-only start-->
Last updated on