Skip to main content

Setting Up and Using Conversation Tags

warning

Before using conversation management tags, ensure that you have created the tags. For details, see: Create and Manage Conversation Tags.

The SDK supports assigning one or multiple tags to conversations, suitable for scenarios such as conversation grouping and filtering conversation lists. This document introduces the interface invocation methods and parameter descriptions related to tag management.

Get Tags for a Specified Conversation​

Call the [getTagsFromConversation] method to retrieve the list of tags associated with a specified conversation.

Interface​

RongIMLib.getTagsFromConversation(conversation)


#### Parameter Description

| Parameter | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| conversation | [IConversationOption] | Yes | Target conversation |


#### Example Code

```js
const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
};
const res = await RongIMLib.getTagsFromConversation(conversation);
console.log('Result of getting tags for the conversation:', res);


## Add Conversations to a Specified Tag \{#addConversationsToTag}

Call the [addConversationsToTag] method to add one or more conversations to a specified tag.

:::tip
 - Each tag can associate with up to 1000 conversations.
 - When the limit is exceeded, new conversations can still be added, but the earliest conversations added to the tag will be automatically removed.
 - A single conversation can be associated with multiple tags.
:::


#### Interface

```js
RongIMLib.addConversationsToTag(tagId, conversations)


#### Parameter Description

| Parameter | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| tagId | string | Yes | Tag ID |
| conversations | [IConversationOption]`[]` | Yes | Array of conversation objects |


#### Example Code

```js
const tagId = 'tagId';
const conversations = [{
    conversationType: 1,
    targetId: '<conversationId_1>',
    channelId: ''
}, {
    conversationType: 1,
    targetId: '<conversationId_2>',
    channelId: ''
}];

const res = await RongIMLib.addConversationsToTag(tagId, conversations);
console.log('Result of adding conversations to the specified tag:', res);


## Remove Multiple Conversations from a Specified Tag \{#removeConversationsFromTag}

:::tip
This operation only removes the association between the conversations and the tag; it does not delete the conversation data.
:::

Call the [removeConversationsFromTag] method to remove multiple conversations from a specified tag.


#### Interface

```js
RongIMLib.removeConversationsFromTag(tagId, conversations)


#### Parameter Description

| Parameter | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| tagId | string | Yes | Tag ID |
| conversations | [IConversationOption]`[]` | Yes | Array of conversation objects |


#### Example Code

```js
const tagId = 'tagId';
const conversations = [{
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}];
const res = await RongIMLib.removeConversationsFromTag(tagId, conversations);
console.log('Result of removing multiple conversations from the specified tag:', res);


## Remove Multiple Tags from a Specified Conversation \{#removeTagsFromConversation}

:::tip
This operation only removes the association between the conversation and the tags; it does not delete the tags themselves.
:::

Call the [removeTagsFromConversation] method to remove multiple tags from a specified conversation.


#### Interface

```js
RongIMLib.removeTagsFromConversation(conversation, tagIds)


#### Parameter Description

| Parameter | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| conversation | [IConversationOption] | Yes | Target conversation |
| tagIds | string[] | Yes | Array of tag IDs to be removed |


#### Example Code

```js
const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
};
const tagIds = ['tagId1', 'tagId2'];
const res = await RongIMLib.removeTagsFromConversation(conversation, tagIds);
console.log('Result of removing multiple tags from the specified conversation:', res);


## Remove a Specified Tag from Multiple Conversations \{#removeTagFromConversations}

:::tip
This operation only removes the association between the conversations and the tag; it does not delete the tag itself.
:::

Call the [removeTagFromConversations] method to remove a specified tag from multiple conversations.


#### Interface

```js
RongIMLib.removeTagFromConversations(tagId, conversations)


#### Parameter Description

| Parameter | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| tagId | string | Yes | Tag ID |
| conversations | [IConversationOption]`[]` | Yes | Array of conversation objects |


#### Example Code

```js
const tagId = 'tagId';
const conversations = [{
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
}];
const res = await RongIMLib.removeTagFromConversations(tagId, conversations);
console.log('Result of removing the specified tag from multiple conversations:', res);


## Get Conversation List Under a Tag by Page \{#getConversationsFromTagByPage}

:::tip
Starting from SDK version 5.7.0, the return data type of this interface has changed from [IReceivedConversationByTag] to [IAReceivedConversationByTag].
:::

Call the [getConversationsFromTagByPage] method to retrieve the conversation list under a specified tag in pages.


#### Interface

```js
RongIMLib.getConversationsFromTagByPage(tagId, count, timestamp)


#### Parameter Description

| Parameter | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| tagId | string | Yes | Tag ID |
| count | number | Yes | Number of items to retrieve. The Web version supports a maximum of 1000 conversations per request. |
| timestamp | number | No | Timestamp of the lastMessage in the conversation |

:::tip[**Notes on Pagination for Conversation Lists**]

Since the Web version cannot verify whether a conversation actually exists when adding it to a tag, non-existent conversations will always have an internal sorting time of 0. This may cause errors when paginating the conversation list.

If this issue occurs in your business scenario, it is recommended to directly retrieve the full conversation data:
<ul><li>The Web version supports retrieving a maximum of 1000 conversations</li><li>Set the request parameters as: `timestamp: 0`, `count: 1000`</li></ul>
:::


#### Example Code

```js
const tagId = 'tagId';
const count = 10;
const timestamp = 0;
const res = await RongIMLib.getConversationsFromTagByPage(tagId, count, timestamp);
console.log('Result of getting conversation list under the tag by page:', res);


## Get Unread Message Count by Tag \{#getUnreadCountByTag}

Call the [getUnreadCountByTag] method to retrieve the total number of unread messages across all conversations under a specified tag.


#### Interface

```js
RongIMLib.getUnreadCountByTag(tagId, containMuted)


#### Parameter Description

| Parameter | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| tagId | string | Yes | Tag ID |
| containMuted | boolean | Yes | Whether to include muted conversations |


#### Example Code

```js
const tagId = 'tagId';
const containMuted = false;
const res = await RongIMLib.getUnreadCountByTag(tagId, containMuted);
console.log('Result of getting unread message count by tag:', res);


## Pin a Conversation in a Tag \{#setConversationToTopInTag}

Call the [setConversationToTopInTag] method to set the pin status of a conversation under a specified tag.

:::tip
 - If you retrieve conversations by tag, you can see this property in the retrieved conversations.
 - The pin status within a tag is independent of the pin status in the conversation list.
:::


#### Interface

```js
RongIMLib.setConversationToTopInTag(tagId, conversation, isTop)


#### Parameter Description

| Parameter | Type | Required | Description |
|:--- |:--- |:--- |:--- |
| tagId | string | Yes | Tag ID |
| conversation | [IConversationOption] | Yes | Target conversation |
| isTop | boolean | Yes | Whether to pin the conversation |


#### Example Code


```js
const tagId = 'tagId';
const conversation = {
 conversationType: RongIMLib.ConversationType.PRIVATE,
 targetId: 'targetId',
};
const isTop = true;
const res = await RongIMLib.setConversationToTopInTag(tagId, conversation, isTop);
console.log('Result of pinning conversation in tag:', res);
<!-- Link section -->
[setConversationToTopInTag]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#setConversationToTopInTag
[getUnreadCountByTag]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getUnreadCountByTag
[getConversationsFromTagByPage]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getConversationsFromTagByPage
[removeTagFromConversations]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#removeTagFromConversations
[removeTagsFromConversation]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#removeTagsFromConversation
[removeConversationsFromTag]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#removeConversationsFromTag
[addConversationsToTag]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#addConversationsToTag
[getTagsFromConversation]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#getTagsFromConversation
[IConversationOption]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#IConversationOption
[IReceivedConversationByTag]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IReceivedConversationByTag.html
[IAReceivedConversationByTag]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IAReceivedConversationByTag.html
Last updated on