Setting Up and Using Conversation Tags

Before using tags to manage conversations, make sure you have created the tags. For details, see Create and Manage Conversation Tags.

The SDK supports marking conversations with one or more tags, which can be used for grouping conversations, retrieving conversation lists, and more. It also provides multiple interfaces for removing tags from conversations.

Conversation tags also support a series of advanced features, including retrieving conversation lists by tag, getting the unread message count for all conversations under a specific tag, and pinning a conversation within a specific tag.

Get Tags for a Specific Conversation

Call getTagsFromConversation to retrieve the tags for a specific conversation.

const conversation = {
    conversationType: 1,
    targetId: '<Conversation ID>',
    channelId: ''
}
RongIMLib.getTagsFromConversation(conversation).then(({code, tags}) => {
    console.log(code, tags);
});

Parameter	Type	Required	Description
conversation	IConversationOption	Yes	Conversation

Add Conversations to a Specific Tag

Call addConversationsToTag to mark one or more conversations with a single tag.

tip

• Each tag can have a maximum of 1000 conversations.
• If a tag already has 1000 conversations, adding more conversations will still succeed, but the earliest tagged conversation will be untagged.
• A single conversation can have multiple different tags.

const conversations = [{
    conversationType: 1,
    targetId: '<Conversation ID_1>',
    channelId: ''
}, {
    conversationType: 1,
    targetId: '<Conversation ID_2>',
    channelId: ''
}];

RongIMLib.addConversationsToTag('<Tag ID>', conversations).then(({ code }) => {
    console.log(code);
})

Parameter	Type	Required	Description
tagId	string	Yes	Tag ID
conversations	IConversationOption[]	Yes	Array of conversations IConversationOption.

Remove Multiple Conversations from a Specific Tag

tip

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

Call removeConversationsFromTag to remove multiple conversations from a specific tag.

const conversations = [{
    conversationType: 1,
    targetId: '<Conversation ID_1>',
    channelId: ''
}, {
    conversationType: 1,
    targetId: '<Conversation ID_2>',
    channelId: ''
}];

RongIMLib.removeConversationsFromTag('<Tag ID>', conversations).then(({ code }) => {
    console.log(code);
});

Parameter	Type	Required	Description
tagId	string	Yes	Tag ID
conversations	IConversationOption[]	Yes	Array of conversations IConversationOption.

Remove Multiple Tags from a Specific Conversation

tip

This operation only removes the relationship between the conversation and the tags; it does not delete the tag data.

Call removeTagsFromConversation to remove multiple tags from a specific conversation.

const conversation = {
    conversationType: 1,
    targetId: '<Conversation ID>',
    channelId: ''
}
RongIMLib.removeTagsFromConversation(conversation, ['tagId_1', 'tagId_2']).then(({code}) => {
    console.log(code);
});

Parameter	Type	Required	Description
conversation	IConversationOption	Yes	Conversation
tagIds	string[]	Yes	Collection of tag IDs

Remove a Specific Tag from Multiple Conversations

tip

This operation only removes the relationship between the conversations and the tag; it does not delete the tag data.

Call removeTagFromConversations to remove a specific tag from multiple conversations.

const conversations = [{
    conversationType: 1,
    targetId: '<Conversation ID_1>',
    channelId: ''
}, {
    conversationType: 1,
    targetId: '<Conversation ID_2>',
    channelId: ''
}];

RongIMLib.removeTagFromConversations('<Tag ID>', conversations).then(({code}) => {
    console.log(code);
})

Parameter	Type	Required	Description
tagId	string	Yes	Tag ID
conversations	IConversationOption[]	Yes	Array of conversations IConversationOption.

Paginate Conversations Under a Tag

tip

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

Call getConversationsFromTagByPage to paginate conversations under a tag.

RongIMLib.getConversationsFromTagByPage('<Tag ID>', 10, 1640869971655).then(({code, data}) => {
    console.log(code, data);
})

Parameter	Type	Required	Description
tagId	string	Yes	Tag ID
count	number	Yes	Number of conversations to retrieve
startTime	number	Yes	Timestamp of the message in the conversation

Get Unread Message Count by Tag

Call getUnreadCountByTag to get the unread message count by tag.

RongIMLib.getUnreadCountByTag('<Tag ID>', true).then(({code, data}) => {
    console.log(code, data);
})

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

Pin a Conversation in a Tag

Call setConversationToTopInTag to pin a conversation in a specific tag. If you retrieve conversations by tag, you can see this property in the retrieved conversations. Note that this is different from pinning a conversation in the conversation list.

const conversation = {
    conversationType: 1,
    targetId: '<Conversation ID>',
    channelId: ''
}
RongIMLib.setConversationToTopInTag('<Tag ID>', conversation, true).then(({code}) => {
    console.log(code);
})

Parameter	Type	Required	Description
tagId	string	Yes	Tag ID
conversation	IConversationOption	Yes	Conversation
isTop	boolean	Yes	Pin status