Handling Unread Message Counts

You can use the interfaces provided by the IMLib SDK to directly retrieve unread message counts in conversations. The specific capabilities include:

Get the total unread message count across all conversations (excluding chatrooms) (getTotalUnreadCountWith).
Get the total unread message count for specified conversations, or the total unread count for specified message types in specified conversations, or the total unread count by conversation type, or the total unread count including/excluding muted conversations (getUnreadCount).

When users interact with your app, the unread count displayed in the UI may need to be updated. In such cases, you can clear the unread status of conversations (clearMessagesUnreadStatus).

tip

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

Get Total Unread Count for All Conversations

You can use getTotalUnreadCountWith to retrieve the total number of unread messages across all conversation types (excluding chatrooms). Upon successful retrieval, it returns the unread count (unreadcount).

[[RCCoreClient sharedCoreClient] getTotalUnreadCountWith:^(int unreadCount) {

}];

Get Total Unread Count for Specified Conversations

You can retrieve the total unread message count for specified conversations. Upon successful retrieval, it returns the unread count (count). Not applicable to chatrooms or ultra groups.

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

Parameter Description

Parameter	Type	Description
conversationType	[RCConversationType]	Conversation type. Not applicable to chatrooms or ultra groups.
targetId	NSString	Conversation targetId.
completion	Block	Asynchronous callback returning the corresponding unread count.

Example Code

[[RCCoreClient sharedCoreClient] getUnreadCount:ConversationType_PRIVATE
                                       targetId:@"targetId"
                                     completion:^(int count) {
}];

Get Total Unread Count for Specified Message Types in Specified Conversations

tip

Available starting from version 5.1.5; only provided in RCCoreClient.

You can retrieve the unread count for one or more specified message types within a specified conversation.

Interface Prototype

- (void)getUnreadCount:(RCConversationIdentifier *)conversationIdentifier
      messageClassList:(NSArray <Class> *)messageClassList
            completion:(nullable void(^)(int count))completion;

Parameter Description

Parameter	Type	Description
conversationIdentifier	[RCConversationIdentifier]	Conversation identifier, requiring specification of conversation type ([RCConversationType]) and Target ID.
messageClassList	NSArray	Array of message types, e.g., @[RCTextMessage.class, RCImageMessage.class]
completion	Block	Asynchronous callback returning the corresponding unread count.

Example Code

RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];
[[RCCoreClient sharedCoreClient] getUnreadCount:iden messageClassList:@[RCTextMessage.class, RCImageMessage.class] completion:^(int count){
  // Asynchronous callback returning the unread message count for the conversation
}];

Get Total Unread Count by Conversation Type

tip

Starting from version 5.20.0, support for retrieving unread counts for ultra group-type conversations is available (requires activation via [ticket submission]).

You can retrieve the unread count for multiple specified conversation types. Upon successful retrieval, it returns the unread count (count).

Interface Prototype

- (void)getUnreadCount:(NSArray<NSNumber *> *)conversationTypes
        containBlocked:(bool)isContain
            completion:(nullable void(^)(int count))completion;

Parameter Description

Parameter	Type	Description
conversationTypes	NSArray	Array of conversation types, requiring conversion of [RCConversationType] to NSNumber for array construction. Not applicable to chatrooms or ultra groups.
isContain	BOOL	Whether to include unread counts from muted conversations.
completion	Block	Asynchronous callback returning the corresponding unread count.

Example Code

[[RCCoreClient sharedCoreClient] getUnreadCount:@[@(ConversationType_PRIVATE),@(ConversationType_GROUP)]
                                 containBlocked:NO
                                     completion:^(int count) {
}];

Get Total Unread Count by Do Not Disturb Level

tip

This interface is supported starting from SDK version 5.2.5. Only available in the RCChannelClient class.

You can retrieve the total unread message count for conversations with specified Do Not Disturb levels. The IMLib SDK will search for conversations based on the provided Do Not Disturb level configuration and return the total unread count for all matching conversations.

Interface Prototype

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

Parameter Description

Parameter	Type	Required
conversationTypes	[RCConversationType] []	Array of conversation types. Not applicable to chatrooms.
levels	`RCPushNotificationLevel[]`	Array of Do Not Disturb levels. See [Do Not Disturb Feature Overview].
successBlock	Block	Success callback returning the unread message count.
errorBlock	Block	Failure callback.

Example Code

NSArray *conversationTypes = @[@(ConversationType_PRIVATE)];
NSArray * pushNotificationLevels = @[@(RCPushNotificationLevelMention)];
[[RCChannelClient sharedChannelManager] getUnreadCount:conversationTypes
                                           levels: pushNotificationLevels
                                         success:^(NSInteger unReadCount) {}
                                           error:^(RCErrorCode status) {}
];

tip

This interface has been supported since SDK version 5.2.5. It is only available in the RCChannelClient class.

You can retrieve the total count of unread @ messages for conversations with specified Do Not Disturb levels. The IMLib SDK will search for conversations based on the provided Do Not Disturb level configurations and return the aggregate count of unread @ messages across all matching conversations.

Method Signature

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


#### Parameter Description
| Parameter         | Type                        | Required | Description |
|:------------------|:----------------------------|:--------:|:------------|
| conversationTypes | [RCConversationType] []     | Yes      | Array of conversation types. Not applicable to chatrooms. |
| levels            | `RCPushNotificationLevel[]` | Yes      | Array of Do Not Disturb levels. See [Do Not Disturb Overview]. |
| successBlock      | Block                       | No       | Success callback returning the count of unread @ messages. |
| errorBlock        | Block                       | No       | Failure callback. |


#### Example Method
```objectivec
NSArray *conversationTypes = @[@(ConversationType_GROUP)];
NSArray * pushNotificationLevels = @[@(RCPushNotificationLevelMention)];
[[RCChannelClient sharedChannelManager] getUnreadMentionedCount:conversationTypes
                                           levels: pushNotificationLevels
                                         success:^(NSInteger unReadCount) {}
                                           error:^(RCErrorCode status) {}
];


## Clear Unread Count for Specified Conversation

You can clear the unread count for a specified conversation up to a given timestamp. The IMLib SDK will mark all messages before this timestamp as read.


#### Method Signature
```objectivec


- (void)clearMessagesUnreadStatus:(RCConversationType)conversationType
                         targetId:(NSString *)targetId
                             time:(long long)timestamp
                       completion:(nullable void(^)(BOOL ret))completion;


#### Parameter Description
| Parameter         | Type                 | Description |
|:------------------|:---------------------|:------------|
| conversationType | [RCConversationType] | Conversation type. Not applicable to chatrooms or ultra groups. |
| targetId         | NSString             | Target ID of the conversation |
| timestamp        | long long            | Unix timestamp - all unread messages before this time will be marked as read. |
| completion       | Block                | Result callback. |


#### Example Code
```objectivec
[[RCCoreClient sharedCoreClient] clearMessagesUnreadStatus:ConversationType_PRIVATE targetId:@"targetId" time:0 completion:^(BOOL ret) {
    if (ret) {
        // Clear successful
    } else {
        // Clear failed
    }
}];
<!-- links -->
[Message Type Overview]: /platform-chat-api/message-about/about-message-types
[Do Not Disturb Overview]: ./do-not-disturb-about.md
[Submit Ticket]: https://console.rongcloud.io/agile/formwork/ticket/create
[RCConversationType]: https://doc.rongcloud.cn/apidoc/imlibcore-ios/latest/zh_CN/documentation/rongimlibcore/rcconversationtype?language=objc
[RCConversationIdentifier]: https://doc.rongcloud.cn/apidoc/imlibcore-ios/latest/zh_CN/documentation/rongimlibcore/rcconversationidentifier?language=objc

IMLib

IMKit

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

CallLib

CallKit

RTCLib

Chat Server

Chat Server SDK

Audio & Video Server

Handling Unread Message Counts

Get Total Unread Count for All Conversations​

Get Total Unread Count for Specified Conversations​

Parameter Description​

Example Code​

Get Total Unread Count for Specified Message Types in Specified Conversations​

Interface Prototype​

Parameter Description​

Example Code​

Get Total Unread Count by Conversation Type​

Interface Prototype​

Parameter Description​

Example Code​

Get Total Unread Count by Do Not Disturb Level​

Interface Prototype​

Parameter Description​

Example Code​

Method Signature​

Get Total Unread Count for All Conversations

Get Total Unread Count for Specified Conversations

Parameter Description

Example Code

Get Total Unread Count for Specified Message Types in Specified Conversations

Interface Prototype

Parameter Description

Example Code

Get Total Unread Count by Conversation Type

Interface Prototype

Parameter Description

Example Code

Get Total Unread Count by Do Not Disturb Level

Interface Prototype

Parameter Description

Example Code

Method Signature