Handling Unread Message Count in Conversations

Instant messaging clients often need to count unread messages in conversations.

You can use the interfaces provided by the IMLib SDK to directly obtain the unread message count in conversations. The specific capabilities are as follows:

• Get the total unread message count across all conversations (excluding chatrooms) (getTotalUnreadCountWith)
• Get the total unread message count for a specified conversation, or the total unread message count for specified message types in a specified conversation, or get the total unread message count by conversation type (getUnreadCount)

When users are using your App, the unread count on the UI may need to change. In this case, you can clear the unread count in the conversation (clearMessagesUnreadStatus).

Get Total Unread Message Count Across All Conversations

tip

Starting from version 5.3.0 of RCCoreClient, it is recommended to use the interface with asynchronous results below. The original synchronous interface is deprecated.

You can use getTotalUnreadCountWith to get the total unread message count across all types of conversations (excluding chatrooms). Upon success, it returns the unread message count (unreadcount).

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

}];

Get Total Unread Message Count for a Specified Conversation

tip

Starting from version 5.3.0 of RCCoreClient, it is recommended to use the interface with asynchronous results below. The original synchronous interface is deprecated.

Get the total unread message count for a specified conversation. Upon success, it returns the unread message count (count). Not applicable to chatrooms or ultra groups.

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

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. Not applicable to chatrooms or ultra groups.
targetId	NSString	Conversation ID.
completion	Block	Asynchronous callback.

Get Total Unread Message Count for Specified Message Types in a Specified Conversation

tip

• This feature is available starting from version 5.1.5; only available in RCCoreClient.
• Starting from version 5.3.0 of RCCoreClient, it is recommended to use the interface with asynchronous results below. The original synchronous interface is deprecated.

Get the unread message count for specified message types in a specified conversation.

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

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

Get Total Unread Message Count by Conversation Type

tip

Starting from version 5.3.0 of RCCoreClient, it is recommended to use the interface with asynchronous results below. The original synchronous interface is deprecated.

Get the unread message count for multiple specified conversation types. Upon success, it returns the unread message count (count).

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

Parameter	Type	Description
conversationTypes	NSArray	Array of conversation types, requiring RCConversationType to be converted to NSNumber to build the Array. Not applicable to chatrooms or ultra groups.
isContain	BOOL	Whether to include the unread count of muted messages.
completion	Block	Asynchronous callback.

Get Total Unread Message Count by Conversation Do Not Disturb Level

tip

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

Get the total unread message count for conversations with specified Do Not Disturb levels. The SDK will search for conversations based on the Do Not Disturb level configuration passed in, and then return the total unread message count for all these conversations.

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

Upon success, the successBlock returns the unread message count.

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

Get Total Unread @ Message Count by Conversation Do Not Disturb Level

tip

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

Get the total unread @ message count for conversations with specified Do Not Disturb levels. The SDK will search for conversations based on the Do Not Disturb level configuration passed in, and then return the total unread @ message count for all these conversations.

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

Upon success, the successBlock returns the unread @ message count.

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

Clear Unread Count for a Specified Conversation

Clear the unread count for a specified conversation by timestamp. The SDK will clear the unread status for all messages before this timestamp.

[[RCCoreClient sharedCoreClient] clearMessagesUnreadStatus:ConversationType_PRIVATE targetId:@"targetId" time:0 completion:^(BOOL ret) {
    if (ret) {
        // Clear successful
    } else {
        // Clear failed
    }
}];

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. Not applicable to chatrooms or ultra groups.
targetId	NSString	Conversation ID
timestamp	long long	Timestamp, unread status before this timestamp will be cleared.