设置与使用会话标签

• SDK 从 5.6.11 版本开始支持会话标签功能。
• 在为会话设置标签前，请确保已创建标签信息。详见管理标签信息数据。
• 本功能不适用于聊天室、超级群。

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

场景描述

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

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

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

使用标签标记会话

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

支持以下操作：

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

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

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

方法

Dart

Future<int> addConversationToTag(String tagId, RCIMIWConversationType type, String targetId, {IRCIMIWAddConversationToTagCallback? callback});

参数说明

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

返回值

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

代码示例

Dart

IRCIMIWAddConversationToTagCallback? callback = IRCIMIWAddConversationToTagCallback(
onConversationToTagAdded: (int? code) {
//...
});

int? ret = await engine?.addConversationToTag(tagId, type, targetId, callback:callback);

从指定标签下移除会话

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

方法

Dart

Future<int> removeConversationFromTag(String tagId, RCIMIWConversationType type, String targetId, {IRCIMIWRemoveConversationFromTagCallback? callback});

参数说明

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

返回值

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

代码示例

Dart

IRCIMIWRemoveConversationFromTagCallback? callback = IRCIMIWRemoveConversationFromTagCallback(
onConversationFromTagRemoved: (int? code) {
//...
});

int? ret = await engine?.removeConversationFromTag(tagId, type, targetId, callback:callback);

为指定会话中移除标签

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

方法

Dart

Future<int> removeTagsFromConversation(RCIMIWConversationType type, String targetId, List<String> tagIds, {IRCIMIWRemoveTagsFromConversationCallback? callback});

参数说明

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

返回值

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

代码示例

Dart

IRCIMIWRemoveTagsFromConversationCallback? callback = IRCIMIWRemoveTagsFromConversationCallback(
onTagsFromConversationRemoved: (int? code) {
//...
});

int? ret = await engine?.removeTagsFromConversation(type, targetId, tagIds, callback:callback);

获取指定会话的所有标签

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

方法

Dart

Future<int> getTagsFromConversation(RCIMIWConversationType type, String targetId, {IRCIMIWGetTagsFromConversationCallback? callback});

参数说明

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

返回值

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

代码示例

Dart

IRCIMIWGetTagsFromConversationCallback? callback = IRCIMIWGetTagsFromConversationCallback(
onSuccess: (List<RCIMIWConversationTagInfo>? t) {
//...
}, 
onError: (int? code) {
//...
});

int? ret = await engine?.getTagsFromConversation(type, targetId, callback:callback);

按标签操作会话数据

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

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

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

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

方法

Dart

Future<int> changeConversationTopStatusInTag(String tagId, RCIMIWConversationType type, String targetId, bool top, {IRCIMIWChangeConversationTopStatusInTagCallback? callback});

参数说明

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

返回值

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

代码示例

Dart

IRCIMIWChangeConversationTopStatusInTagCallback? callback = IRCIMIWChangeConversationTopStatusInTagCallback(onConversationTopStatusInTagChanged: (int? code) {
//...
});

int? ret = await engine?.changeConversationTopStatusInTag(tagId, type, targetId, top, callback:callback);

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

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

方法

Dart

Future<int> getConversationsFromTagByPage(String tagId, int timestamp, int count, {IRCIMIWGetConversationsCallback? callback});

参数说明

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

返回值

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

代码示例

Dart

IRCIMIWGetConversationsCallback? callback = IRCIMIWGetConversationsCallback(
onSuccess: (List<RCIMIWConversation>? t) {
//...
},
 onError: (int? code) {
//...
});

int? ret = await engine?.getConversationsFromTagByPage(tagId, timestamp, count, callback:callback);

按标签获取未读消息数

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

方法

Dart

Future<int> getUnreadCountByTag(String tagId, bool contain, {IRCIMIWGetUnreadCountCallback? callback});

参数说明

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

返回值

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

代码示例

Dart

IRCIMIWGetUnreadCountCallback? callback = IRCIMIWGetUnreadCountCallback(
onSuccess: (int? t) {
//...
}, 
onError: (int? code) {
//...
});

int? ret = await engine?.getUnreadCountByTag(tagId, contain, callback:callback);

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

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

方法

Dart

Future<int> clearMessagesUnreadStatusByTag(String tagId, {IRCIMIWClearMessagesUnreadStatusByTagCallback? callback});

参数说明

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

返回值

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

代码示例

Dart

IRCIMIWClearMessagesUnreadStatusByTagCallback? callback = IRCIMIWClearMessagesUnreadStatusByTagCallback(
onSuccess: (bool? t) {
//...
},
 onError: (int? code) {
//...
});

int? ret = await engine?.clearMessagesUnreadStatusByTag(tagId, callback:callback);

删除标签对应的会话

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

方法

Dart

Future<int> clearConversationsByTag(String tagId, bool deleteMessage, {IRCIMIWClearConversationsByTagCallback? callback});

参数说明

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

返回值

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

代码示例

Dart

IRCIMIWClearConversationsByTagCallback? callback = IRCIMIWClearConversationsByTagCallback(
onSuccess: (bool? t) {
//...
}, 
onError: (int? code) {
//...
});

int? ret = await engine?.clearConversationsByTag(tagId, deleteMessage, callback:callback);

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

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