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 count of unread messages across all conversations (excluding chatrooms) (getTotalUnreadCount)
• Get the total unread 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).

Get Total Unread Count for All Conversations

You can use getTotalUnreadCount to retrieve the total number of unread messages across all conversation types (excluding chatrooms).

Interface

RongIMClient.getInstance().getTotalUnreadCount(callback);

Upon successful retrieval, the callback will return the unread message count (unReadCount).

Parameter Description

Parameter	Type	Description
callback	ResultCallback<Integer>	Callback interface returning the unread message count (unReadCount)

Example Code

RongIMClient.getInstance().getTotalUnreadCount(new ResultCallback<Integer>() {

    @Override
    public void onSuccess(Integer unReadCount) {

    }

    @Override
    public void onError(RongIMClient.ErrorCode ErrorCode) {

    }
});

Get Total Unread Count for Specified Conversations

Retrieve the total unread message count for specified conversations.

Interface

RongIMClient.getInstance().getUnreadCount(conversationType, targetId, callback);

Parameter Description

Parameter	Type	Description
conversationType	[ConversationType]	Conversation type. Not applicable to chatrooms or ultra groups.
targetId	String	Conversation ID
callback	ResultCallback<Integer>	Callback interface

Upon successful retrieval, the callback will return the unread message count (unReadCount).

Example Code

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = "Conversation Id";

RongIMClient.getInstance().getUnreadCount(conversationType, targetId,
    new ResultCallback<Integer>() {

    @Override
    public void onSuccess(Integer unReadCount) {

    }

    @Override
    public void onError(RongIMClient.ErrorCode ErrorCode) {

    }
});

Get Unread Count for Specified Message Types in Specified Conversations

tip

This method was introduced in SDK version 5.1.5. It is only available in RongCoreClient.

Retrieve the unread count for one or more specified message types within a specified conversation.

Interface

RongCoreClient.getInstance().getUnreadCount(targetId, conversationType, objectNames, callback)

Parameter Description

Parameter	Type	Description
targetId	String	Conversation ID.
conversationType	ConversationType	Conversation type. Not applicable to chatrooms.
objectNames	String[]	Array of message type identifiers. Built-in message type identifiers can be found in [Message Type Overview].
callback	IRongCoreCallback.ResultCallback	Callback result.

Upon successful retrieval, the callback will return the unread message count (unReadCount).

Get Total Unread Count by Conversation Type

tip

• Starting from version 5.20.0, ultra group conversation types are supported. Ultra group functionality requires [submitting a ticket] to enable.

Retrieve the unread count for multiple specified conversation types.

Interface

RongIMClient.getInstance().getUnreadCount(conversationTypes, containBlocked, callback);

Parameter Description

Parameter	Type	Description
conversationTypes	[ConversationType] []	Array of conversation types. Not applicable to chatrooms or ultra groups.
containBlocked	boolean	Whether to include unread counts from muted conversations. true: include. false: exclude.
callback	ResultCallback<Integer>	Callback interface

Upon successful retrieval, the callback will return the unread message count (unReadCount).

Example Code

ConversationTypes[] conversationTypes = {ConversationTypes.PRIVATE, ConversationTypes.GROUP};
boolean containBlocked = true;

RongIMClient.getInstance().getUnreadCount(conversationTypes, containBlocked,
    new ResultCallback<Integer>() {

    @Override
    public void onSuccess(Integer unReadCount) {

    }

    @Override
    public void onError(RongIMClient.ErrorCode ErrorCode) {

    }
});

Get Total Unread Count by Do Not Disturb Level

tip

This interface is supported starting from SDK version 5.2.5. It is only available in ChannelClient.

Retrieve the total unread message count for conversations with specified Do Not Disturb levels. The SDK will search for conversations based on the provided Do Not Disturb level configurations and return the total unread count for all matching conversations.

Interface

ChannelClient.getInstance().getUnreadCount(conversationTypes, levels, callback)

Parameter Description

Parameter	Type	Required
conversationTypes	[ConversationType] []	Array of conversation types. Not applicable to chatrooms.
levels	[PushNotificationLevel] []	Array of Do Not Disturb types. See [Do Not Disturb Feature Overview].
callback	ResultCallback<Integer>	Callback interface

Upon successful retrieval, the callback will return the unread message count (unReadCount).

Sample Code

ConversationTypes[] conversationTypes = {ConversationTypes.PRIVATE, ConversationTypes.GROUP};
PushNotificationLevel[] levels = {PushNotificationLevel.PUSH_NOTIFICATION_LEVEL_MENTION}

ChannelClient.getInstance().getUnreadCount(conversationTypes, levels,

    new ResultCallback<Integer>() {

    @Override
    public void onSuccess(Integer unReadCount) {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode ErrorCode) {

    }
});

Get Total Unread Mention Count by Do Not Disturb Level

tip

This API is supported since SDK version 5.2.5. Only available in ChannelClient.

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

Interface

ChannelClient.getInstance().getUnreadMentionedCount(conversationTypes, levels, callback)

Parameters

Parameter	Type	Required
conversationTypes	[ConversationType] []	Conversation type array. Not applicable to chatrooms.
levels	[PushNotificationLevel] []	Do Not Disturb level array. See [Do Not Disturb Feature Overview].
callback	ResultCallback<Integer>	Callback interface

Upon successful retrieval, the callback will return the unread mention count (unReadCount).

Sample Code

ConversationTypes[] conversationTypes = {ConversationTypes.PRIVATE, ConversationTypes.GROUP};
PushNotificationLevel[] levels = {PushNotificationLevel.PUSH_NOTIFICATION_LEVEL_MENTION}

ChannelClient.getInstance().getUnreadMentionedCount(conversationTypes, levels,

    new ResultCallback<Integer>() {

    @Override
    public void onSuccess(Integer unReadCount) {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode ErrorCode) {

    }
});

Clear Unread Count for Specified Conversation

Clears the unread count for a specified conversation based on a timestamp. The SDK will mark all messages before this timestamp as read.

Interface

RongIMClient.getInstance().clearMessagesUnreadStatus(conversationType, targetId,  timestamp, callback);

Parameters

Parameter	Type	Description
conversationType	[ConversationType]	Conversation type. Not applicable to chatrooms or ultra groups.
targetId	String	Conversation ID
timestamp	long	Timestamp. All unread messages before this timestamp will be cleared.
callback	OperationCallback	Callback interface

Sample Code

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = "Conversation ID";
long timestamp = 1585811571;

RongIMClient.getInstance().clearMessagesUnreadStatus(conversationType, targetId, timestamp, new OperationCallback() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(RongIMClient.ErrorCode errorCode) {

    }
});