设置与使用会话标签
注意
在使用会话管理标签前，请确保已创建标签。详见： 创建与管理会话标签。
SDK 支持为会话打上一个或多个标签，适用于会话分组、筛选会话列表等场景。本文档介绍与标签管理相关的接口调用方式及参数说明。
获取指定会话的标签
调用 getTagsFromConversation 方法，获取指定会话已关联的标签列表。
接口
JavaScript
RongIMLib.getTagsFromConversation(conversation)
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| conversation | IConversationOption | 是 | 目标会话 |
示例代码
JavaScript
const conversation = {
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId',
};
const res = await RongIMLib.getTagsFromConversation(conversation);
console.log('获取会话下的标签结果：', res);
添加会话到指定标签
调用 addConversationsToTag 方法，可将一个或多个会话加入到指定标签下。
提示
- 每个标签最多可关联 1000 个会话。
- 超出数量限制时，新增的会话仍可加入，但将自动移除最早加入该标签的会话。
- 同一个会话可关联多个标签。
接口
JavaScript
RongIMLib.addConversationsToTag(tagId, conversations)
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tagId | string | 是 | 标签 ID |
| conversations | IConversationOption[] | 是 | 会话对象数组 |
示例代码
JavaScript
const tagId = 'tagId';
const conversations = [{
conversationType: 1,
targetId: '<会话Id_1>',
channelId: ''
}, {
conversationType: 1,
targetId: '<会话Id_2>',
channelId: ''
}];
const res = await RongIMLib.addConversationsToTag(tagId, conversations);
console.log('添加会话到指定标签结果：', res);
从指定标签中删除多个会话
提示
此操作仅解除会话与标签的关系，并不会删除会话数据。
调用 removeConversationsFromTag 方法，可将多个会话从指定标签中移除。
接口
JavaScript
RongIMLib.removeConversationsFromTag(tagId, conversations)
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tagId | string | 是 | 标签 ID |
| conversations | IConversationOption[] | 是 | 会话对象数组 |
示例代码
JavaScript
const tagId = 'tagId';
const conversations = [{
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId',
}];
const res = await RongIMLib.removeConversationsFromTag(tagId, conversations);
console.log('从指定标签中删除多个会话果：', res);
从指定会话中删除多个标签
提示
此操作仅解除会话与标签的关联，不会删除标签本身。
调用 removeTagsFromConversation 方法，可将多个标签从指定会话中移除。
接口
JavaScript
RongIMLib.removeTagsFromConversation(conversation, tagIds)
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| conversation | IConversationOption | 是 | 目标会话 |
| tagIds | string[] | 是 | 待移除的标签 ID 数组 |
示例代码
JavaScript
const conversation = {
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId',
};
const tagIds = ['tagId1', 'tagId2'];
const res = await RongIMLib.removeTagsFromConversation(conversation, tagIds);
console.log('从指定会话中删除多个标签结果：', res);
从多个会话中删除指定标签
提示
此操作仅解除会话与标签的关联，不会删除标签本身。
调用 removeTagFromConversations 方法，可将指定标签从多个会话中移除。
接口
JavaScript
RongIMLib.removeTagFromConversations(tagId, conversations)
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tagId | string | 是 | 标签 ID |
| conversations | IConversationOption[] | 是 | 会话对象数组 |
示例代码
JavaScript
const tagId = 'tagId';
const conversations = [{
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId',
}];
const res = await RongIMLib.removeTagFromConversations(tagId, conversations);
console.log('从多个会话中删除指定的标签结果：', res);
分页获取标签下会话列表
提示
从 SDK 版本 5.7.0 开始，该接口的返回数据类型由 IReceivedConversationByTag 变更为 IAReceivedConversationByTag。
调用 getConversationsFromTagByPage 方法，分页获取指定标签下的会话列表。
接口
JavaScript
RongIMLib.getConversationsFromTagByPage(tagId, count, timestamp)
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tagId | string | 是 | 标签 ID |
| count | number | 是 | 获取数量，Web 端最大可每次获取 1000 条会话 |
| timestamp | number | 否 | 会话中 lasterMessage 的时间戳 |
分页获取会话列表时的注意事项
由于 Web 端在为标签添加会话时无法检查会话是否真实存在，对于不存在的会话，其内部排序时间始终为 0，这可能导致分页获取会话列表时出现错误。
若业务上存在此问题，建议直接获取全量会话数据：
- Web 端最多支持获取 1000 条会话
- 请求参数设置为：
timestamp: 0，count: 1000
示例代码
JavaScript
const tagId = 'tagId';
const count = 10;
const timestamp = 0;
const res = await RongIMLib.getConversationsFromTagByPage(tagId, count, timestamp);
console.log('分页获取标签下会话列表结果：', res);
根据标签获取未读消息数
调用 getUnreadCountByTag 方法，获取指定标签下所有会话的未读消息总数。
接口
JavaScript
RongIMLib.getUnreadCountByTag(tagId, containMuted)
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tagId | string | 是 | 标签 ID |
| containMuted | boolean | 是 | 是否包含免打扰 |
示例代码
JavaScript
const tagId = 'tagId';
const containMuted = false;
const res = await RongIMLib.getUnreadCountByTag(tagId, containMuted);
console.log('根据标签获取未读消息数结果：', res);
设置标签中会话置顶
调用 setConversationToTopInTag 方法，可在指定标签下设置会话置顶状态。
提示
- 如果根据标签获取会话，可在获取的会话中可以看到该属性。
- 标签内的置顶状态与会话列表中的置顶状态相互独立。
接口
JavaScript
RongIMLib.setConversationToTopInTag(tagId, conversation, isTop)
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tagId | string | 是 | 标签 ID |
| conversation | IConversationOption | 是 | 目标会话 |
| isTop | boolean | 是 | 是否置顶 |
示例代码
JavaScript
const tagId = 'tagId';
const conversation = {
conversationType: RongIMLib.ConversationType.PRIVATE,
targetId: 'targetId',
};
const isTop = true;
const res = await RongIMLib.setConversationToTopInTag(tagId, conversation, isTop);
console.log('设置标签中会话置顶结果：', res);