Setting and Using Conversation Tags

The conversation tag feature is supported starting from SDK version 5.1.1. Related interfaces are only available in RongCoreClient.

Before setting tags for conversations, ensure that tag information has been created. See [Managing Tag Information Data].

This feature is not applicable to chatrooms and ultra groups.

Each user can create up to 20 tags, with each tag containing a maximum of 1,000 conversations. If a tag already contains 1,000 conversations, adding more conversations to it will still succeed but will result in the earliest tagged conversations being removed from the tag.

Use Case Description

Conversation tags typically fulfill the need for App users to group conversations. After creating tag information (TagInfo), App users can assign one or more tags to conversations.

Once tags are set, the tag data of conversations can be used to implement features such as grouped retrieval, display, and deletion of conversations. Additionally, users can obtain the unread message count for all conversations under a specific tag or pin a conversation within a particular tag.

Use Case 1: Tagging each conversation in the conversation list, similar to the external groups, department groups, and personal groups tags in the WeCom conversation list.
Use Case 2: Grouping contacts by tags, similar to the family, friends, and colleagues groups in the QQ contacts list.
Use Case 3: A combination of the first two use cases, grouping the conversation list by tags, similar to the Telegram conversation list grouping.

Using Tags to Mark Conversations

After creating tag information (TagInfo), App users can use tags to mark conversations. The SDK treats the action 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

Interface

RongCoreClient.getInstance().addConversationsToTag(tagId, conversationIdentifierList,callback)

Parameter Description

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

Example Code

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) {

            }
        });

Removing Conversations from a Specified Tag

App users may need to remove one or more conversations from all conversations tagged with a specific label. For example, removing the 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 conversations still exist but no longer carry the tag.

Interface

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

Parameter Description

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

Example Code

RongCoreClient.getInstance().removeConversationsFromTag(
                        tagId,
                        conversationIdentifierList,
                        new IRongCoreCallback.OperationCallback() {
                            @Override
                            public void onSuccess() {
                            }

                            @Override
                            public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {
                                
                            }
                        });

Removing Tags from a Specified Conversation

App users may have added multiple tags to a specified conversation. The SDK supports removing one or multiple tags at once. When removing tags, a list of tagIds for all TagInfo to be removed must be provided.

Interface

RongCoreClient.getInstance(). removeTagsFromConversation(conversationIdentifier, tagIds, callback);

Parameter Description

Parameter	Type	Description
conversationIdentifier	ConversationIdentifier	Conversation identifier, which must specify the conversation type (ConversationType) and Target ID.
tagIds	List<String> tagIds	List of tag IDs.
callback	IRongCoreCallback.OperationCallback()	Result callback.

Example Code

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) {

            }
        });

Retrieving All Tags for a Specified Conversation

Retrieve all tags associated with a specified conversation. Upon successful retrieval, 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).

Parameter Description

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 associated with the conversation.

Example Code

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) {

            }
        });

Multi-Device Synchronization of Conversation Tag Modifications

RC supports multi-device login for the same user account. After setting up the conversation tag change listener IRongCoreListener.ConversationTagListener, when a user adds, removes, or edits tags on conversations from another device, the onConversationTagChanged callback will be triggered, allowing the current device to receive conversation tag modification notifications from other devices. Upon receiving the notification, call the getTagsFromConversation method to retrieve the latest tag data for the specified conversation from the RC server.

tip

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

Sample Code

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

## Operating on Conversation Data by Tags

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

- Combined with the [Conversation Pinning] feature, it enables pinning conversations among those with specified tags

- Retrieving conversation lists by tag, i.e., getting all conversations with specified tags

- Getting unread message counts by tag

- Clearing unread message counts for conversations with specified tags

- Deleting conversations with specified tags

### Pinning Conversations Among Those with Specified Tags

You can use conversation tags to categorize and display conversations according to business needs. If you need to pin conversations within the same category (all conversations with the same tag), you can use the conversation pinning feature.

For detailed implementation, refer to the **Pinning Conversations Under Tags** section in [Conversation Pinning].

### Paginated Retrieval of Local Conversation Lists with Specified Tags

Retrieve paginated local conversation lists with specified tags, using the `operationTime` in conversations as the boundary. This method only fetches data from the local database. Starting from version 5.6.4, the `Conversation` object returned by this interface includes a new `isTopForTag` property. If `true`, it indicates that the conversation is pinned under the current `tagId`.

#### Interface

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

#### Parameter Description

|Parameter | Type | Description|
|:-----|:-----|:----|
|tagId | String | Tag ID |
|ts | long | Conversation timestamp. Retrieves conversation lists before this timestamp. For the first call, pass `0`. Subsequent calls can use the `sentTime` or `operationTime` property values from the returned [Conversation] object as the `startTime` for the next query. `operationTime` is recommended (this property is only available in version 5.6.8 and later).|
|count | int | Number of items to retrieve (20 ≦ count ≦ 100) |
|callback | ResultCallback\<List\<Conversation\>\> | Returns a list of conversations with the specified tagId. |

#### Sample Code
```java
String tagId = "peixunban";
long ts = 0;
int count = 20;

RongCoreClient.getInstance().getConversationsFromTagByPage(tagId, ts, count, new IRongCoreCallback.ResultCallback<List<Conversation>>() {
    @Override
    public void onSuccess(List<Conversation> conversations) {

    }

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

    }
});

### Paginated Retrieval of Local Untagged Conversation Lists

:::tip

 Supported starting from version 5.24.0.

:::

You can use the `getUntaggedConversationListByPage` interface to retrieve untagged conversation lists.

#### Interface

```java
RongCoreClient.getInstance().getUntaggedConversationListByPage(timestamp, count， topPriority，callback);

#### Parameter Description

| Parameter        | Type                                                 | Description                                                         |
| :---------- | :--------------------------------------------------- | :----------------------------------------------------------- |
| `timestamp`   |`Long`                                                 | Conversation timestamp (retrieves conversation lists before this timestamp, 0 means starting from the latest, unit: milliseconds). |
| `count`       | `Int`                                                  | Number of items to retrieve, valid range [1, 100]. (When the actual number of retrieved conversations is less than count, it indicates all data has been fetched). If count is less than 1, it defaults to 20; if greater than 100, it defaults to 100. |
| `topPriority` | `Boolean`                                              | Sorting method for query results. If true, pinned conversations are prioritized; otherwise, results are sorted only by conversation time. |
| `callback`    | `IRongCoreCallback.ResultCallback<List<Conversation>>` | Result callback.                                                   |

#### Sample Code

long timestamp = 0;
int count = 20;
boolean topPriority = true;

RongCoreClient.getInstance().getUntaggedConversationListByPage(timestamp, count,topPriority,new IRongCoreCallback.ResultCallback<List<Conversation>>() {

	@Override
	public void onSuccess(List<Conversation> conversations) {
		// do nothing
	}

	@Override
	public void onError(IRongCoreEnum.CoreErrorCode e) {
		// do nothing
	}
});

### Getting Unread Message Counts by Tag

Retrieves the total unread message count for all conversations with the specified tag.

#### Interface

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

#### Parameter Description
|Parameter | Type | Description |
|:-----|:-----|:----|
|tagId | String | Tag ID |
|containBlocked | boolean | Whether to include muted messages |
|callback | ResultCallback\<Integer\> | Callback for getting unread message counts by tag|

#### Sample Code
```java
String tagId = "peixunban";
boolean containBlocked = true;

RongCoreClient.getInstance().getUnreadCountByTag(tagId, containBlocked, new IRongCoreCallback.ResultCallback<Integer>() {
    @Override
    public void onSuccess(Integer integer) {

    }

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

    }
});

### Clearing Unread Message Counts for Conversations with Specified Tags

:::tip

 This interface is available starting from SDK version 5.1.5.
:::

Clears the unread message count for all conversations with the specified tag.

#### Interface

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

#### Parameter Description

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

### Deleting Conversations with Specified Tags

:::tip

 This interface is available starting from SDK version 5.1.5.
:::

Deletes all conversations under the specified tag and removes their binding with the tag. After successful deletion, the conversations will no longer carry the specified tag. When these conversations receive new messages, new conversations will be created.

#### Interface

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

#### Parameter Description

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

#### Sample Code
```java
String tagId = "peixunban";
boolean deleteMessage = true;

RongCoreClient.getInstance().clearConversationsByTag(tagId, deleteMessage, new IRongCoreCallback.ResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean aBoolean) {

    }

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

    }
});

You can configure whether to simultaneously clear local messages for these conversations using the deleteMessage parameter.

If local messages are not deleted, you can view historical chat records when receiving new messages.
If local messages are deleted, historical chat records won't be visible when receiving new messages. If Cloud Storage for One-to-One and Group Messages is enabled, the server still retains message history, and you can retrieve historical messages using the getMessages method. To delete them, please use the Delete Server History Messages API.

IMLib

IMKit

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

CallLib

CallKit

RTCLib

Chat Server

Chat Server SDK

Audio & Video Server

Setting and Using Conversation Tags

Use Case Description​

Using Tags to Mark Conversations​

Adding One or More Conversations to a Specified Tag​

Interface​

Parameter Description​

Example Code​

Removing Conversations from a Specified Tag​

Interface​

Parameter Description​

Example Code​

Removing Tags from a Specified Conversation​

Interface​

Parameter Description​

Example Code​

Retrieving All Tags for a Specified Conversation​

Parameter Description​

Example Code​

Multi-Device Synchronization of Conversation Tag Modifications​

Sample Code​

Use Case Description

Using Tags to Mark Conversations

Adding One or More Conversations to a Specified Tag

Interface

Parameter Description

Example Code

Removing Conversations from a Specified Tag

Interface

Parameter Description

Example Code

Removing Tags from a Specified Conversation

Interface

Parameter Description

Example Code

Retrieving All Tags for a Specified Conversation

Parameter Description

Example Code

Multi-Device Synchronization of Conversation Tag Modifications

Sample Code