标记会话

---

功能简介

当您遇到需要关注某会话或暂时无法处理某条会话等场景时，您可以标记会话并稍后处理，例如 "会话标星"、"会话折叠"、"会话隐藏"、“会话标记未读”等。为会话设置标记后，即可以标记为过滤项获取会话列表和未读消息总数。

前提条件

在实现“标记会话”功能之前，请确保：

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考控制台的 服务配置 - 即时通讯 - 开通服务），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。
• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息 的 “2 集成 SDK”。

设置会话标记

ZIM 支持开发者使用客户端 API 或 服务端 API 实现对会话的标记操作。

客户端 API

1 监听 onConversationChanged

可以通过 onConversationChanged 回调监听会话变更的相关通知。

当会话标记变更后，用户的所有在线设备会收到 onConversationChanged 事件通知，从其中 conversation.marks 字段可以获取到该会话当前的所有标记。

// 注册 SDK 事件通知回调
ZIMEventHandler.onConversationChanged = (ZIM zim, List<ZIMConversationChangeInfo> conversationChangeInfoList){
    for (ZIMConversationChangeInfo conversationChangeInfo in conversationChangeInfoList) {
        // 从 conversationChangeInfo.conversation.marks 中可以获取到该会话的全量标记
    }
};

2 设置或取消标记

您只需调用 setConversationMark 接口，即可对至多 100 个会话（仅支持单聊或群聊）设置或取消标记。每个会话至多可以拥有 20 个标记。

// 以对一个群聊会话设置标签为 1 为例
int markType = 1;
bool enable = true;
List<ZIMConversationBaseInfo> convList = [];
ZIMConversationBaseInfo conversationBaseInfo = ZIMConversationBaseInfo();
conversationBaseInfo.conversationID = "GroupConv";
conversationBaseInfo.conversationType = ZIMConversationType.group;
convList.add(conversationBaseInfo);
ZIM.getInstance()?.setConversationMark(markType, enable, convList).then((value) {
        // 操作成功的处理。
        // 注意：即便部分操作成功，部分操作失败，errorCode 仍会为 SUCCESS，且会在 failedConversationInfos 返回操作失败的会话
    }).catchError((onError){
        if(onError is PlatformException){
            // 对所有会话的操作都失败时的处理
        }
});

服务端 API

开发者可以通过调用服务端 API 批量对多名用户设置或取消会话标记，详情请参考服务端 API 文档 设置会话标记。

按标记查询会话列表

调用 queryConversationList 接口，通过 ZIMConversationFilterOption.marks 传入会话标记列表，即可将标记作为过滤项查询会话列表。

此外，如果查询时需要考虑会话是否存在未读数，在调用 queryConversationList 接口时，传入 isOnlyUnreadConversation 为 true 即可。

// 以查询拥有标记为 1 且包含存在未读数的群聊会话列表为例
ZIMConversationQueryConfig config = ZIMConversationQueryConfig();
config.count = 100;
config.nextConversation = null; // 首次查询填 null，多次分页查询则传入返回结果中的会话列表中的最后一个
ZIMConversationFilterOption option = ZIMConversationFilterOption();
option.marks.add(1); // 这里填入需要查询的标记
option.conversationTypes.add(ZIMConversationType.group); // 这里填入需要查询的会话类型，若该列表为空，则同时查询单聊和群聊会话。
option.isOnlyUnreadConversation = true; // 这里填入是否仅查询存在未读数的会话，默认为 false，查询时不考虑会话是否存在未读数

ZIM.getInstance()?.queryConversationList(config,option).then((value) {
// 查询成功的处理
}).catchError((onError){
if(onError is PlatformException){
    // 查询失败的处理
    onError.code;
    onError.message;
}
});

按标记查询消息未读总数

调用 queryConversationTotalUnreadMessageCount 接口，通过 ZIMConversationTotalUnreadMessageCountQueryConfig.marks 传入会话标记列表，即可按标记查询相关会话的消息未读总数。

// 以查询包含标记为 1 的群聊会话总未读数为例
ZIMConversationTotalUnreadMessageCountQueryConfig config =  ZIMConversationTotalUnreadMessageCountQueryConfig();
config.marks.add(1); // 这里填入需要查询的标记
config.conversationTypes.add(ZIMConversationType.group); // 这里填入需要查询的会话类型。若该列表为空，则同时查询单聊和群聊会话。
ZIM.getInstance()?.queryConversationTotalUnreadMessageCount(config).then((value) {
    // 查询成功的处理
}).catchError((onError){
    if(onError is PlatformException){
        // 查询失败的处理
    }
});