Set Up and Use Conversation Tags

• The conversation tag feature is supported starting from SDK version 5.1.1. The related interfaces are only available in RongCoreClient.
• Before setting tags for conversations, ensure that tag information has been created. For details, refer to Manage Tag Information Data.
• This feature is not applicable to chatrooms and ultra groups.

Each user can create up to 20 tags, and each tag can contain up to 1000 conversations. If a tag already contains 1000 conversations, adding more conversations to it will still succeed, but the earliest tagged conversation will be untagged.

Scenario Description

Conversation tags are often used to meet the need for grouping conversations in an app. After creating tag information (TagInfo), app users can set one or more tags for a conversation.

Once tags are set, the tag data of conversations can be used to implement features like grouping, displaying, and deleting conversations. Additionally, you can get the unread message count for all conversations under a specific tag or pin a conversation within a specific tag.

• Scenario 1: Tagging each conversation in the conversation list, similar to the external group, department group, and personal group tags in the WeChat Work conversation list.
• Scenario 2: Grouping contacts by tags, similar to the family, friends, and colleagues groups in the QQ friends list.
• Scenario 3: A combination of the first two scenarios, grouping the conversation list by tags, similar to the Telegram conversation list grouping.

Tagging Conversations

After creating tag information (TagInfo), app users can tag conversations. The SDK treats the act of tagging a conversation as adding the conversation to a tag.

The following operations are supported:

• Tagging conversations, i.e., adding one or more conversations to a specified tag
• Removing one or more conversations from a tag
• Removing one or more tags from a specified conversation

Adding One or More Conversations to a Specified Tag

The SDK treats the act of tagging a conversation as adding the conversation to a tag. You can add multiple conversations to a single tag. When specifying a tag, only the tagId from TagInfo needs to be passed.

RongCoreClient.getInstance().addConversationsToTag(tagId, conversationIdentifierList,
    new IRongCoreCallback.OperationCallback() {
            /**
             * Success callback
             */
            @Override
            public void onSuccess() {

            }

            /**
             * Failure callback
             * @param errorCode Error code
             */
            @Override
            public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

            }
        });

Parameter	Type	Description
tagId	String	Tag ID
conversationIdentifierList	List<ConversationIdentifier>	Conversation identifier list. Each ConversationIdentifier must specify the conversation type (ConversationType) and Target ID.
callback	OperationCallback	Callback

Removing Conversations from a Specified Tag

App users may need to remove one or more conversations from all conversations tagged with a specific tag. For example, removing a private chat with "Tom" from all conversations tagged with "Training Class". The SDK treats this operation as removing conversations from a specified tag. After successful removal, the conversation still exists but no longer carries the tag.

RongCoreClient.getInstance().removeConversationsFromTag(tagId, conversationIdentifierList, callback);

Parameter	Type	Description
tagId	String	Tag ID
conversationIdentifierList	List<ConversationIdentifier>	Conversation identifier list. Each ConversationIdentifier must specify the conversation type (ConversationType) and Target ID.
callback	OperationCallback	Callback

Removing Tags from a Specified Conversation

App users may have added multiple tags to a specified conversation. The SDK supports removing one or more tags at a time. When removing tags, a list of tagId from all TagInfo to be removed must be passed.

RongCoreClient.getInstance(). removeTagsFromConversation(conversationIdentifier, tagIds,
    new IRongCoreCallback.OperationCallback() {
            /**
             * Success callback
             */
            @Override
            public void onSuccess() {

            }

            /**
             * Failure callback
             * @param errorCode Error code
             */
            @Override
            public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

            }
        });

Getting All Tags for a Specified Conversation

Get all tags carried by a specified conversation. Upon success, the callback returns a list of ConversationTagInfo. Each ConversationTagInfo contains the corresponding tag information (TagInfo) and pin status information (whether the conversation is pinned among all conversations carrying this tag).

RongCoreClient.getInstance().getTagsFromConversation(conversationIdentifier,
    new IRongCoreCallback.ResultCallback<List<ConversationTagInfo>>() {
            /**
             * Success callback
             */
            @Override
            public void onSuccess(List<ConversationTagInfo> conversationTagInfos) {

            }

            /**
             * Failure callback
             * @param errorCode Error code
             */
            @Override
            public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

            }
        });

Parameter	Type	Description
conversationIdentifier	ConversationIdentifier	Conversation identifier, which must specify the conversation type (ConversationType) and Target ID.
callback	ResultCallback<List<ConversationTagInfo>>	Result callback, returning all tags carried by the conversation.

Multi-End Synchronization of Conversation Tag Modifications

Instant Messaging supports multi-end login for the same user account. If your app user modifies conversation tags on the current device, the SDK will notify the user's other devices. Upon receiving the notification, other devices can call getTagsFromConversation to fetch the latest tag data for the specified conversation from the RC server.

After setting the conversation tag change listener IRongCoreListener.ConversationTagListener, the current device can receive conversation tag modification notifications from other devices.

tip

• Call this method after initialization but before connection.
• Modifying tag information on the current device will not trigger this callback. The server will only notify the SDK to trigger the callback on other devices logged in with the same user account.

RongCoreClient.getInstance().setConversationTagListener(new IRongCoreListener.ConversationTagListener{
    @Override
    public void onConversationTagChanged() {
    }
});

When app users add, remove, or edit tags on conversations from other ends, the ConversationTagListener will trigger the onConversationTagChanged callback. Upon receiving the notification, call getTagsFromConversation to fetch the latest tag data for the specified conversation from the RC server.

Operating on Conversation Data by Tags

The SDK supports operations on conversations carrying specified tags. After app users add tags to conversations, the following operations can be implemented:

• In combination with the Conversation Pinning feature, you can pin conversations within conversations carrying a specified tag
• Get the conversation list by tag, i.e., get all conversations carrying a specified tag
• Get the unread message count by tag
• Clear the unread message count for conversations corresponding to a tag
• Delete conversations corresponding to a tag

Pinning Conversations Within Conversations Carrying a Specified Tag

Apps can use conversation tags to classify and display conversations according to business needs. If you need to pin a conversation within a group of conversations (all conversations carrying the same tag), you can use the conversation pinning feature.

For detailed implementation, refer to Conversation Pinning's Pinning Conversations Within a Tag.

Paginated Retrieval of Local Conversation List Under a Specified Tag

Paginated retrieval of the local conversation list under a specified tag, bounded by the timestamp of the last message in the conversation. This method only retrieves data from the local database. Starting from version 5.6.4, the Conversation object returned by this interface adds the isTopForTag property. If true, it indicates that the conversation is pinned under the current tagId.

RongCoreClient.getInstance().getConversationsFromTagByPage(tagId, ts, count, callback);

Parameter	Type	Description
tagId	String	Tag ID
ts	long	Conversation timestamp. Retrieve the conversation list before this timestamp. The first time, you can pass 0. Subsequent times, you can use the sentTime or operationTime property value of the returned Conversation object as the startTime for the next query. It is recommended to use operationTime (this property is only available starting from version 5.6.8).
count	int	Retrieval count (20 ≦ count ≦ 100)
callback	ResultCallback<List<Conversation>>	Returns the conversation list carrying the specified tagId.

Getting Unread Message Count by Tag

Get the unread message count for all conversations carrying a specified tag.

RongCoreClient.getInstance().getUnreadCountByTag(tagId, containBlocked, callback);

Parameter	Type	Description
tagId	String	Tag ID
containBlocked	boolean	Whether to include muted messages
callback	ResultCallback<Integer>	Callback for getting unread message count by tag

Clearing Unread Message Count for Conversations Corresponding to a Tag

tip

This interface is available starting from SDK version 5.1.5.

Clear the unread message count for all conversations carrying a specified tag.

RongCoreClient.getInstance().clearMessagesUnreadStatusByTag(tagId, callback)

Parameter	Type	Description
tagId	String	Tag ID
callback	IRongCoreCallback.ResultCallback	Operation result callback

Deleting Conversations Corresponding to a Tag

tip

This interface is available starting from SDK version 5.1.5.

Delete all conversations under a specified tag, while unbinding these conversations from the tag. After successful deletion, the conversations no longer carry the specified tag. When these conversations receive new messages, new conversations will be created.

RongCoreClient.getInstance().clearConversationsByTag(tagId, deleteMessage, callback)

Parameter	Type	Description
tagId	String	Tag ID.
deleteMessage	boolean	Whether to clear local historical messages for all conversations under this tag.
callback	IRongCoreCallback.ResultCallback	Operation result callback.

You can configure whether to simultaneously clear the local messages corresponding to these conversations via the deleteMessage parameter.

• If you do not delete the local messages corresponding to the conversations, you can see the historical chat records when new messages are received.
• If you delete the local messages corresponding to the conversations, you cannot see the historical chat records when new messages are received. If the Cloud Storage for One-to-One and Group Messages service is enabled, the server still retains the message history. If you need to delete it, use the Delete Server-Side Historical Messages Interface.