Skip to main content

Get Unread Message Count

IMLib SDK allows you to retrieve unread message counts for ultra groups, with the following capabilities:

  • Get unread message counts for all ultra groups, specified ultra groups, or channels that the current user has joined.

  • Get unread mention counts for all ultra groups, specified ultra groups, or channels that the current user has joined.

  • Retrieve total unread message counts by Do Not Disturb level.

  • The maximum returned unread count is 999. If the actual count exceeds 999, the interface will still return 999.

tip

IMLib SDK only provides these interfaces in the ChannelClient.

Get Unread Message Counts for Multiple Ultra Groups​

The SDK supports retrieving unread message counts and unread mention counts for all ultra groups the current user has joined.

Batch Get Unread Message Counts for User's Ultra Groups​

tip

This feature is supported starting from IMLib SDK version 5.4.6.

In community scenarios, if you need to display real-time unread message data across multiple ultra group channels that a user belongs to, you can use getUltraGroupConversationUnreadInfoList to retrieve unread data for up to 20 ultra groups (including all their channels) in a single call. This includes:

  • Unread message count per ultra group channel

  • Unread mention count per ultra group channel

  • Unread mentions specifically targeting the current user per ultra group channel

  • Do Not Disturb level per ultra group channel

Interface Prototype​



- (void)getUltraGroupConversationUnreadInfoList:(nonnull NSArray<NSString *> *)targetIds
                                        success:(nonnull void (^)(NSArray<RCConversationUnreadInfo *> *list))successBlock
                                          error:(nonnull void (^)(RCErrorCode status))errorBlock;


#### Parameter Description
| Parameter      | Type                 | Description                                                                  |
|:---------------|:---------------------|:----------------------------------------------------------------------------|
| targetIds      | NSString             | List of ultra group conversation targetIds (max 20)                         |
| successBlock   | Block                | Success callback returning `RCConversationUnreadInfo` array containing unread message count, total mention count, mentions targeting current user, and Do Not Disturb level |
| errorBlock     | Block                | Failure callback                                                           |


#### Example Code
```objectivec
[[RCChannelClient sharedChannelManager] getUltraGroupConversationUnreadInfoList:targetIds success:^(NSArray<RCConversationUnreadInfo *> * _Nonnull list) {
  for (RCConversationUnreadInfo *info in list) {
    NSString *content = [NSString stringWithFormat:@"%@ %@:%@,%@,%@,%@", info.targetId, info.channelId, @(info.unreadMessageCount), @(info.mentionedCount), @(info.mentionedMeCount), @(info.notificationLevel)];
    NSLog(@"%@", content);
  }
} error:^(RCErrorCode status) {
  // TODO error code
}];


### Get Total Unread Count for All Ultra Groups User Has Joined


#### Interface Prototype
```objectivec


- (void)getUltraGroupAllUnreadCount:(void (^)(NSInteger count))successBlock
                              error:(void (^)(RCErrorCode status))errorBlock;


#### Parameter Description
| Parameter      | Type                 | Description                                                                  |
|:---------------|:---------------------|:----------------------------------------------------------------------------|
| successBlock   | Block                | Success callback returning total unread message count                      |
| errorBlock     | Block                | Failure callback                                                           |


#### Example Code
```objectivec
[[RCChannelClient sharedChannelManager] getUltraGroupAllUnreadCount:^(NSInteger count) {
} error:^(RCErrorCode status) {
}];


### Get Total Unread Mention Count for All Ultra Groups User Has Joined


#### Interface Prototype
```objectivec


- (void)getUltraGroupAllUnreadMentionedCount:(void (^)(NSInteger  count))successBlock
                                       error:(void (^)(RCErrorCode status))errorBlock;


#### Parameter Description
| Parameter      | Type                 | Description                                                                  |
|:---------------|:---------------------|:----------------------------------------------------------------------------|
| successBlock   | Block                | Success callback returning total unread mention count                      |
| errorBlock     | Block                | Failure callback                                                           |


#### Example Code
```objectivec
[[RCChannelClient sharedChannelManager] getUltraGroupAllUnreadMentionedCount:^(NSInteger count) {
} error:^(RCErrorCode status) {
}];


## Get Unread Message Counts for Specified Ultra Groups or Channels


### Get Unread Message Count for All Channels in a Specified Ultra Group

```objectivec


- (void)getUltraGroupUnreadCount:(NSString *)targetId
                         success:(void (^)(NSInteger  count))successBlock
                           error:(void (^)(RCErrorCode status))errorBlock


#### Parameter Description
| Parameter      | Type                 | Description                                                                  |
|:---------------|:---------------------|:----------------------------------------------------------------------------|
| targetId       | NSString             | Ultra group targetId                                                       |
| successBlock   | Block                | Success callback returning unread message count                            |
| errorBlock     | Block                | Failure callback                                                           |


#### Example Code
```objectivec
[[RCChannelClient sharedChannelManager] getUltraGroupUnreadCount:@"targetId" success:^(NSInteger count) {
} error:^(RCErrorCode status) {
}];


### Get Unread Mention Count for a Specified Ultra Group


#### Interface Prototype
```objectivec


- (void)getUltraGroupUnreadMentionedCount:(NSString *)targetId
                               completion:(nullable void(^)(int num))completion;


#### Parameter Description
| Parameter      | Type                 | Description                                                                  |
|:---------------|:---------------------|:----------------------------------------------------------------------------|
| targetId       | NSString             | Ultra group targetId                                                       |
| completion     | Block                | Callback returning unread mention count                                    |


#### Sample Code
```objectivec
[[RCChannelClient sharedChannelManager] getUltraGroupUnreadMentionedCount:@"targetId" completion:^(int num) {

}];


### Get Unread Message Count for Specified Channel in Ultra Group


```objectivec


- (void)getUnreadCount:(RCConversationType)conversationType
              targetId:(NSString *)targetId
             channelId:(nullable NSString *)channelId
            completion:(nullable void(^)(int num))completion;


#### Parameter Description
| Parameter       | Type               | Description                                                              |
|:----------------|:-------------------|:------------------------------------------------------------------------|
| conversationType | RCConversationType | Conversation type. |
| targetId        | NSString           | Ultra group targetId. |
| channelId       | NSString           | Ultra group channelId. |
| completion      | Block              | Callback returning unread message count. |


#### Sample Code
```objectivec
[[RCChannelClient sharedChannelManager] getUnreadCount:ConversationType_ULTRAGROUP targetId:@"targetId" channelId:@"channelId" completion:^(int num) {

}];


### Get Unread Mention Count for Specified Channel

You can directly obtain the unread mention count for the channel from the `RCConversation` object.


- `mentionedCount`: Sum of unread messages mentioning "@all" and "@current user" in the current channel.


- `mentionedMeCount`: Count of unread messages mentioning "@current user" in the current channel. Requires SDK version ≥ 5.4.5.

For specific examples, refer to [Get Channel List](get-channel-list).


### Get Total Unread Message Count for Ultra Group by Do Not Disturb Level

:::tip

 This interface is supported starting from SDK version 5.2.5. Only available in `RCChannelClient`.
:::

You can obtain the total unread message count for conversations and channels that have specified Do Not Disturb levels configured. The IMLib SDK will search based on the provided Do Not Disturb level settings and return the total unread message count for channels that match the settings under the conversation.


#### Interface Prototype
```objectivec


- (void)getUltraGroupUnreadCount:(nonnull NSString *)targetId
                          levels:(nonnull NSArray <NSNumber*>*)levels
                         success:(nullable void (^)(NSInteger count))successBlock
                           error:(nullable void (^)(RCErrorCode status))errorBlock;


#### Parameter Description
| Parameter | Type | Required |
| :-------- | :--- | :------: |
| targetId | NSString | Ultra group conversation targetId. |
| levels | `RCPushNotificationLevel[]` | Array of Do Not Disturb types. See [Do Not Disturb Overview]. |
| successBlock | Block  |  Success callback, returns unread message count. |
| errorBlock | Block  |  Failure callback. |


#### Sample Code
```objectivec
NSArray * pushNotificationLevels = @[@(RCPushNotificationLevelMention)];
[[RCChannelClient sharedChannelManager] getUltraGroupUnreadCount:targetId
                                           levels: pushNotificationLevels
                                         success:^(NSInteger unReadCount) {}
                                           error:^(RCErrorCode status) {}];


### Get Total Unread Mention Count for Ultra Group by Do Not Disturb Level

:::tip

 This interface is supported starting from SDK version 5.2.5. Only available in `RCChannelClient`.
:::

You can obtain the total unread mention count for conversations and channels that have specified Do Not Disturb levels configured. The IMLib SDK will search based on the provided Do Not Disturb level settings and return the total unread mention count for channels that match the settings under the conversation.


#### Interface Prototype
```objectivec


- (void)getUltraGroupUnreadMentionedCount:(nonnull NSString *)targetId
                                   levels:(nonnull NSArray <NSNumber*>*)levels
                                  success:(nullable void (^)(NSInteger count))successBlock
                                    error:(nullable void (^)(RCErrorCode status))errorBlock;


#### Parameter Description
| Parameter | Type | Required |
| :-------- | :--- | :------: |
| targetId | NSString | Ultra group conversation targetId. |
| levels | `RCPushNotificationLevel[]` | Array of Do Not Disturb types. See [Do Not Disturb Overview]. |
| successBlock | Block  |  Success callback, returns unread message count. |
| errorBlock | Block  |  Failure callback. |


#### Sample Code
```objectivec
NSArray * pushNotificationLevels = @[@(RCPushNotificationLevelMention)];
[[RCChannelClient sharedChannelManager] getUltraGroupUnreadMentionedCount:targetId
                                           levels: pushNotificationLevels
                                         success:^(NSInteger unReadCount) {}
                                           error:^(RCErrorCode status) {}];
If you need to obtain the total unread message count for multiple types of conversations, refer to the methods described in [Handling Conversation Unread Count](../conversation/handle-unread-count.md).

<!-- links -->
[Do Not Disturb Overview]: ./do-not-disturb-about.md
Last updated on