跳到主要内容

设置与使用会话标签

  • 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>

参数说明

参数名参数类型描述
tagIdstring标签唯一标识,字符型,长度不超过 10 个字。
typeRCIMIWConversationType会话类型
targetIdstring会话 ID
callbackIRCIMIWAddConversationToTagCallback事件回调。

返回值

返回值描述
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>

参数说明

参数名参数类型描述
tagIdstring标签唯一标识,字符型,长度不超过 10 个字。
typeRCIMIWConversationType会话类型
targetIdstring会话 ID
callbackIRCIMIWRemoveConversationFromTagCallback事件回调。

返回值

返回值描述
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 支持一次移除单个或多个标签。移除时需要传入所有待移除 RCIMIWTagInfotagId 列表。

方法

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

参数说明

参数名参数类型描述
typeRCIMIWConversationType会话类型
targetIdstring会话 ID
tagIdsArray<string>标签集合
callbackIRCIMIWRemoveTagsFromConversationCallback事件回调。

返回值

返回值描述
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>

参数说明

参数名参数类型描述
typeRCIMIWConversationType会话类型
targetIdstring会话 ID
callbackIRCIMIWGetTagsFromConversationCallback事件回调。

返回值

返回值描述
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>

参数说明

参数名参数类型描述
tagIdstring标签唯一标识,字符型,长度不超过 10 个字。
typeRCIMIWConversationType会话类型
targetIdstring会话 ID
topboolean是否置顶
callbackIRCIMIWChangeConversationTopStatusInTagCallback事件回调。

返回值

返回值描述
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>

参数说明

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

返回值

返回值描述
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>

参数说明

参数名参数类型描述
tagIdstring标签唯一标识,字符型,长度不超过 10 个字。
containboolean是否包含免打扰会话。
callbackIRCIMIWGetUnreadCountCallback事件回调。

返回值

返回值描述
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>

参数说明

参数名参数类型描述
tagIdstring标签唯一标识,字符型,长度不超过 10 个字。
callbackIRCIMIWClearMessagesUnreadStatusByTagCallback事件回调。

返回值

返回值描述
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>

参数说明

参数名参数类型描述
tagIdstring标签唯一标识,字符型,长度不超过 10 个字。
deleteMessageboolean是否删除消息
callbackIRCIMIWClearConversationsByTagCallback事件回调。

返回值

返回值描述
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 参数配置是否同时清除这些会话对应的本地消息。

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