标记会话

功能简介

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

说明

当用户标记了会话，ZIM SDK 只会简单记录会话的标记值，并不会改变会话的底层逻辑。

设置会话标记

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

客户端 API

1 监听 onConversationChanged

用户登录 ZIM SDK 后，需监听注册 on 监听的 conversationChanged 回调接口，接收会话标记变化通知。

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

Untitled

// 注册 SDK 事件通知回调
zim.on('conversationChanged', function (zim, { infoList }) {
    infoList.forEach((info) => {
        console.log(info.conversation.marks);
    });
});

Copied!

2 设置或取消标记

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

说明

每名用户最多可标记 1000 个会话。针对标记数量达到上限的情况，不同 ZIM SDK 版本的处理逻辑如下：
- SDK 版本 ≥ 2.19.0：用户可继续标记新会话，ZIM 会自动取消最早标记的会话。
- SDK 版本 < 2.19.0：标记会话时会触发报错，用户需手动取消之前的标记后才能添加新标记。
针对单个会话可拥有的标记上限，不同 ZIM SDK 版本规定如下：
- SDK 版本 ≥ 2.19.0：最多 30 个标记。
- SDK 版本 < 2.19.0：最多 20 个标记。

Untitled

// 以对一个单聊会话和一个群聊会话设置标签为 1 为例
var markType = 1;
var enable = true;
var convList = [
    { conversationID: '单聊', conversationType: 0 },
    { conversationID: '群聊', conversationType: 2 },
];

zim.setConversationMark(markType, enable, convList)
    .then((res) => {
        // 操作成功，部分失败的会话通过 res.failedConversationInfos 返回
    })
    .catch((err) => {
        // 操作失败
    });

Copied!

服务端 API

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

按标记查询会话列表

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

说明

会话标记列表（ZIMConversationFilterOption.marks）只支持 [1, 20] 的整数：
- 若列表包含 -1，查询结果为所有已标记会话；
- 若列表包含 0，查询结果为所有无标记的会话；
- 若传入多个标记，查询结果为所有传入标记的并集；
- 若列表为空，则查询结果为所有会话。
仅查询单聊会话和群聊会话。

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

Untitled

// 以查询拥有标记为 1 且包含存在未读数的会话列表（包含单聊和群聊）为例
var config = { count: 10 };
var option = {
    marks: [1],
    conversationTypes: [],
    isOnlyUnreadConversation: true,
};

zim.queryConversationList(config, option)
    .then((res) => {
        // 操作成功
    })
    .catch((err) => {
        // 操作失败
    });

Copied!

按标记查询消息未读总数

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

说明

此处计算消息未读总数的规则与 conversationTotalUnreadMessageCountUpdated 事件一致，即如果有符合要求的会话已开启免打扰，那么这个会话的未读数不会被计入这里查询出来的总未读数。
会话标记列表（ZIMConversationTotalUnreadMessageCountQueryConfig.marks）只支持 [1, 20] 的整数：
- 若列表包含 -1，查询结果为所有已标记会话；
- 若列表包含 0，查询结果为所有无标记的会话；
- 若传入多个标记，查询结果为所有传入标记的并集；
- 若列表为空，则查询结果为所有会话。
仅查询单聊会话和群聊会话。

Untitled

// 以查询包含标记为 1 的会话总未读数（包含单聊和群聊）为例
var config = {
    marks: [1],
    conversationTypes: [],
};

zim.queryConversationTotalUnreadMessageCount(config)
    .then((res) => {
        // 操作成功
    })
    .catch((err) => {
        // 操作失败
    });

Copied!