设置与使用会话标签

SDK 从 5.12.1 版本开始支持会话标签功能。

在为会话设置标签前，请确保已创建标签信息。详见管理标签信息数据。

本功能不适用于聊天室、超级群。

每个用户最多可以创建 20 个标签，每个标签下最多可以添加 1000 个会话。如果标签下已添加 1000 个会话，继续在该标签下添加会话仍会成功，但会导致最早添加标签的会话被移除标签。

场景描述

会话标签常实现 App 用户对会话进行分组的需求。创建标签信息（RCIMIWTagInfo）后，App 用户可以为会话设置一个或多个标签。

设置标签后，可以利用会话的标签数据实现会话的分组获取、展示、删除等特性。还可以获取指定标签下所有会话的消息未读数，或在特定标签下设置某个会话置顶。

场景 1：对会话列表中的每个会话打 tag，类似企业微信会话列表中的外部群，部门群，个人群等 tag。
场景 2：通讯录根据 tag 来分组，类似 QQ 好友列表中的家人，朋友，同事分组等。
场景 3：前两个场景的结合，按照 tag 来进行会话列表分组，类似 Telegram 的会话列表分组。

使用标签标记会话

在创建标签信息（RCIMIWTagInfo）后，App 用户可以使用标签标记会话。SDK 将用标签标记会话的操作视为将会话添加到标签中。

支持以下操作：

标记会话，即将一个或多个会话添加到指定标签。
从标签中移除一个或多个会话。
为指定会话移除一个或多个标签。

将一个或多个会话添加到指定标签

SDK 将用标签标记会话的操作视为将会话添加到标签中。您可以将多个会话添加到一个标签。指定标签时只需要传入 RCIMIWTagInfo 中的 tagId。

方法

typescript
addConversationToTag(tagId: string, type: RCIMIWConversationType, targetId: string, callback?: IRCIMIWAddConversationToTagCallback): Promise<number>

参数说明

参数名	参数类型	描述
tagId	string	标签唯一标识，字符型，长度不超过 10 个字。
type	RCIMIWConversationType	会话类型
targetId	string	会话 ID
callback	IRCIMIWAddConversationToTagCallback	事件回调。

返回值

返回值	描述
Promise<number>	当次接口操作的状态码。0 代表调用成功，具体结果需要实现接口回调；非 0 代表当前接口调用操作失败，不会触发接口回调。详细错误参考错误码。

代码示例

typescript
const callback: IRCIMIWAddConversationToTagCallback = {
  onConversationToTagAdded: (code?: number) => {
    // 处理添加会话到标签结果
    console.log('添加会话到标签结果:', code);
  }
};

const ret = await engine?.addConversationToTag(tagId, type, targetId, callback);
console.log('添加会话到标签调用状态:', ret);

从指定标签下移除会话

App 用户可能需要携带指定标签的会话中移除一个或多个会话。例如，在所有添加了「培训班」标签的会话中移除与「Tom」的私聊会话。SDK 将该操作视为从指定标签中移除会话。移除成功后，会话仍然存在，但不再携带该标签。

方法

typescript
removeConversationFromTag(tagId: string, type: RCIMIWConversationType, targetId: string, callback?: IRCIMIWRemoveConversationFromTagCallback): Promise<number>

参数说明

参数名	参数类型	描述
tagId	string	标签唯一标识，字符型，长度不超过 10 个字。
type	RCIMIWConversationType	会话类型
targetId	string	会话 ID
callback	IRCIMIWRemoveConversationFromTagCallback	事件回调。

返回值

返回值	描述
Promise<number>	当次接口操作的状态码。0 代表调用成功，具体结果需要实现接口回调；非 0 代表当前接口调用操作失败，不会触发接口回调。详细错误参考错误码。

代码示例

typescript
const callback: IRCIMIWRemoveConversationFromTagCallback = {
  onConversationFromTagRemoved: (code?: number) => {
    // 处理从标签移除会话结果
    console.log('从标签移除会话结果:', code);
  }
};

const ret = await engine?.removeConversationFromTag(tagId, type, targetId, callback);
console.log('从标签移除会话调用状态:', ret);

为指定会话中移除标签

App 用户可能为指定会话中添加了多个标签。SDK 支持一次移除单个或多个标签。移除时需要传入所有待移除 RCIMIWTagInfo 的 tagId 列表。

方法

typescript
removeTagsFromConversation(type: RCIMIWConversationType, targetId: string, tagIds: Array<string>, callback?: IRCIMIWRemoveTagsFromConversationCallback): Promise<number>

参数说明

参数名	参数类型	描述
type	RCIMIWConversationType	会话类型
targetId	string	会话 ID
tagIds	Array<string>	标签集合
callback	IRCIMIWRemoveTagsFromConversationCallback	事件回调。

返回值

返回值	描述
Promise<number>	当次接口操作的状态码。0 代表调用成功，具体结果需要实现接口回调；非 0 代表当前接口调用操作失败，不会触发接口回调。详细错误参考错误码。

代码示例

typescript
const callback: IRCIMIWRemoveTagsFromConversationCallback = {
  onTagsFromConversationRemoved: (code?: number) => {
    // 处理从会话移除标签结果
    console.log('从会话移除标签结果:', code);
  }
};

const ret = await engine?.removeTagsFromConversation(type, targetId, tagIds, callback);
console.log('从会话移除标签调用状态:', ret);

获取指定会话的所有标签

获取指定会话携带的所有标签。获取成功后，回调中返回 RCIMIWConversationTagInfo 的列表。每个 RCIMIWConversationTagInfo 中包含对应的标签信息 RCIMIWTagInfo 和置顶状态信息（会话是否在携带该标签信息的所有会话中置顶）。

方法

typescript
getTagsFromConversation(type: RCIMIWConversationType, targetId: string, callback?: IRCIMIWGetTagsFromConversationCallback): Promise<number>

参数说明

参数名	参数类型	描述
type	RCIMIWConversationType	会话类型
targetId	string	会话 ID
callback	IRCIMIWGetTagsFromConversationCallback	事件回调。

返回值

返回值	描述
Promise<number>	当次接口操作的状态码。0 代表调用成功，具体结果需要实现接口回调；非 0 代表当前接口调用操作失败，不会触发接口回调。详细错误参考错误码。

代码示例

typescript
const callback: IRCIMIWGetTagsFromConversationCallback = {
  onSuccess: (tags?: Array<RCIMIWConversationTagInfo>) => {
    // 处理获取会话标签成功
    console.log('获取会话标签成功:', tags);
  },
  onError: (code?: number) => {
    // 处理获取会话标签失败
    console.log('获取会话标签失败:', code);
  }
};

const ret = await engine?.getTagsFromConversation(type, targetId, callback);
console.log('获取会话标签调用状态:', ret);

按标签操作会话数据

SDK 支持对携带指定标签的会话进行操作。App 用户为会话添加标签后，可以实现以下操作：

配合使用会话置顶功能，可以实现在携带指定标签的会话中置顶会话。
按标签获取会话列表，即获取携带指定标签的所有会话。
按标签获取未读消息数。
清除标签对应会话的未读消息数。
删除标签对应的会话。

在携带指定标签的会话中置顶

App 可以使用会话标签按照业务需求对会话进行分类和展示。如果需要在同一类会话（携带同一标签的所有会话）中置顶显示会话，可以使用会话置顶功能。

方法

typescript
changeConversationTopStatusInTag(tagId: string, type: RCIMIWConversationType, targetId: string, top: boolean, callback?: IRCIMIWChangeConversationTopStatusInTagCallback): Promise<number>

参数说明

参数名	参数类型	描述
tagId	string	标签唯一标识，字符型，长度不超过 10 个字。
type	RCIMIWConversationType	会话类型
targetId	string	会话 ID
top	boolean	是否置顶
callback	IRCIMIWChangeConversationTopStatusInTagCallback	事件回调。

返回值

返回值	描述
Promise<number>	当次接口操作的状态码。0 代表调用成功具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例

typescript
const callback: IRCIMIWChangeConversationTopStatusInTagCallback = {
  onConversationTopStatusInTagChanged: (code?: number) => {
    // 处理会话标签置顶状态变更结果
    console.log('会话标签置顶状态变更结果:', code);
  }
};

const ret = await engine?.changeConversationTopStatusInTag(tagId, type, targetId, top, callback);
console.log('会话标签置顶状态变更调用状态:', ret);

分页获取本地指定标签下会话列表

以会话中最后一条消息时间戳为界，分页获取本地指定标签下会话列表。

方法

typescript
getConversationsFromTagByPage(tagId: string, timestamp: number, count: number, callback?: IRCIMIWGetConversationsCallback): Promise<number>

参数说明

参数名	参数类型	描述
tagId	string	标签唯一标识，字符型，长度不超过 10 个字。
timestamp	number	会话的时间戳。获取这个时间戳之前的会话列表。首次可传 0，后续可以使用返回的 RCIMIWConversation 对象的 operationTime 字段，作为下一次查询的 startTime。
count	number	获取的数量。当实际取回的会话数量小于 count 值时，表明已取完数据。
callback	IRCIMIWGetConversationsCallback	事件回调。

返回值

返回值	描述
Promise<number>	当次接口操作的状态码。0 代表调用成功具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例

typescript
const callback: IRCIMIWGetConversationsCallback = {
  onSuccess: (conversations?: Array<RCIMIWConversation>) => {
    // 处理获取标签下会话列表成功
    console.log('获取标签下会话列表成功:', conversations);
  },
  onError: (code?: number) => {
    // 处理获取标签下会话列表失败
    console.log('获取标签下会话列表失败:', code);
  }
};

const ret = await engine?.getConversationsFromTagByPage(tagId, timestamp, count, callback);
console.log('获取标签下会话列表调用状态:', ret);

按标签获取未读消息数

获取指定标签下所有会话的未读消息总数。

方法

typescript
getUnreadCountByTag(tagId: string, contain: boolean, callback?: IRCIMIWGetUnreadCountCallback): Promise<number>

参数说明

参数名	参数类型	描述
tagId	string	标签唯一标识，字符型，长度不超过 10 个字。
contain	boolean	是否包含免打扰会话。
callback	IRCIMIWGetUnreadCountCallback	事件回调。

返回值

返回值	描述
Promise<number>	当次接口操作的状态码。0 代表调用成功具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例

typescript
const callback: IRCIMIWGetUnreadCountCallback = {
  onSuccess: (count?: number) => {
    // 处理获取标签未读数成功
    console.log('获取标签未读数成功:', count);
  },
  onError: (code?: number) => {
    // 处理获取标签未读数失败
    console.log('获取标签未读数失败:', code);
  }
};

const ret = await engine?.getUnreadCountByTag(tagId, contain, callback);
console.log('获取标签未读数调用状态:', ret);

清除标签对应会话的未读消息数

清除携带指定标签的所有会话的未读消息数。

方法

typescript
clearMessagesUnreadStatusByTag(tagId: string, callback?: IRCIMIWClearMessagesUnreadStatusByTagCallback): Promise<number>

参数说明

参数名	参数类型	描述
tagId	string	标签唯一标识，字符型，长度不超过 10 个字。
callback	IRCIMIWClearMessagesUnreadStatusByTagCallback	事件回调。

返回值

返回值	描述
Promise<number>	当次接口操作的状态码。0 代表调用成功具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例

typescript
const callback: IRCIMIWClearMessagesUnreadStatusByTagCallback = {
  onSuccess: (result?: boolean) => {
    // 处理清除标签未读状态成功
    console.log('清除标签未读状态成功:', result);
  },
  onError: (code?: number) => {
    // 处理清除标签未读状态失败
    console.log('清除标签未读状态失败:', code);
  }
};

const ret = await engine?.clearMessagesUnreadStatusByTag(tagId, callback);
console.log('清除标签未读状态调用状态:', ret);

删除标签对应的会话

删除指定标签下的全部会话，同时解除这些会话和标签的绑定关系。删除成功后，会话不再携带指定的标签。这些会话收到新消息时，会产生新的会话。

方法

typescript
clearConversationsByTag(tagId: string, deleteMessage: boolean, callback?: IRCIMIWClearConversationsByTagCallback): Promise<number>

参数说明

参数名	参数类型	描述
tagId	string	标签唯一标识，字符型，长度不超过 10 个字。
deleteMessage	boolean	是否删除消息
callback	IRCIMIWClearConversationsByTagCallback	事件回调。

返回值

返回值	描述
Promise<number>	当次接口操作的状态码。0 代表调用成功具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码

代码示例

typescript
const callback: IRCIMIWClearConversationsByTagCallback = {
  onSuccess: (result?: boolean) => {
    // 处理删除标签会话成功
    console.log('删除标签会话成功:', result);
  },
  onError: (code?: number) => {
    // 处理删除标签会话失败
    console.log('删除标签会话失败:', code);
  }
};

const ret = await engine?.clearConversationsByTag(tagId, deleteMessage, callback);
console.log('删除标签会话调用状态:', ret);

您可以通过 deleteMessages 参数配置是否同时清除这些会话对应的本地消息。

如果不删除会话对应的本地消息，再接收到新消息时，可以看到历史聊天记录。
如果删除会话对应的本地消息，再接收到新消息时，无法看到历史聊天记录。如果开通了单群聊消息云存储服务，服务端仍保存有消息历史。如需删除，请使用删除服务端历史消息接口。

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

Global IM UIKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

验证码短信

设置与使用会话标签

场景描述​

使用标签标记会话​

将一个或多个会话添加到指定标签​

方法​

参数说明​

返回值​

代码示例​

从指定标签下移除会话​

方法​

参数说明​

返回值​

代码示例​

为指定会话中移除标签​

方法​

参数说明​

返回值​

代码示例​

获取指定会话的所有标签​

方法​

参数说明​

返回值​

代码示例​

按标签操作会话数据​

在携带指定标签的会话中置顶​

方法​

参数说明​

返回值​

代码示例​

分页获取本地指定标签下会话列表​

方法​

参数说明​

返回值​

代码示例​

按标签获取未读消息数​

方法​

参数说明​

返回值​

代码示例​

清除标签对应会话的未读消息数​

方法​

参数说明​

返回值​

代码示例​

删除标签对应的会话​

方法​

参数说明​

返回值​

代码示例​

场景描述

使用标签标记会话

将一个或多个会话添加到指定标签

方法

参数说明

返回值

代码示例

从指定标签下移除会话

方法

参数说明

返回值

代码示例

为指定会话中移除标签

方法

参数说明

返回值

代码示例

获取指定会话的所有标签

方法

参数说明

返回值

代码示例

按标签操作会话数据

在携带指定标签的会话中置顶

方法

参数说明

返回值

代码示例

分页获取本地指定标签下会话列表

方法

参数说明

返回值

代码示例

按标签获取未读消息数

方法

参数说明

返回值

代码示例

清除标签对应会话的未读消息数

方法

参数说明

返回值

代码示例

删除标签对应的会话

方法

参数说明

返回值

代码示例