logo
当前页

标记会话


功能简介

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

说明
  • 每名用户最多可标记 1000 个会话。
  • 当用户标记了会话,ZIM SDK 只会简单记录会话的标记值,并不会改变会话的底层逻辑。

设置会话标记

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

客户端 API

1 监听 onConversationChanged

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

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

Untitled
// 注册 SDK 事件通知回调
zim.setEventHandler(this);

...

public void onConversationChanged(ZIM zim, ArrayList<ZIMConversationChangeInfo> conversationChangeInfoList) {
    super.onConversationChanged(zim, conversationChangeInfoList);
    for (ZIMConversationChangeInfo conversationChangeInfo : conversationChangeInfoList) {
        // 从 conversationChangeInfo.conversation.marks 中可以获取到该会话的全量标记
    }
}
1
Copied!

2 设置或取消标记

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

Untitled
// 以对一个群聊会话设置标签为 1 为例
Integer markType = 1;
boolean enable  = true;
ArrayList<ZIMConversationBaseInfo> convList = new ArrayList<>();
ZIMConversationBaseInfo conversation = new ZIMConversationBaseInfo();
conversation.conversationID = "GroupConv";
conversation.conversationType = ZIMConversationType.GROUP;
convList.add(conversation);

zim.setConversationMark(markType, enable, convList, new ZIMConversationMarkSetCallback() {
    @Override
    public void onConversationMarkSet(ArrayList<ZIMConversationBaseInfo> failedConversationInfos, ZIMError errorInfo) {
        if(errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 操作成功的处理。
            // 注意:即便部分操作成功,部分操作失败,errorCode 仍会为 SUCCESS,且会在 failedConversationInfos 返回操作失败的会话
        } else {
            // 对所有会话的操作都失败时的处理
        }
    }
});
1
Copied!

服务端 API

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

按标记查询会话列表

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

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

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

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

zim.queryConversationList(config, option, new ZIMConversationListQueriedCallback() {
    @Override
    public void onConversationListQueried(ArrayList<ZIMConversation> conversationList, ZIMError errorInfo) {
        if(errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 查询成功的处理
        } else {
            // 查询失败的处理
        }
    }
});
1
Copied!

按标记查询消息未读总数

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

说明
  • 此处计算消息未读总数的规则与 onConversationTotalUnreadMessageCountUpdated 事件一致,即如果有符合要求的会话已开启免打扰,那么这个会话的未读数不会被计入这里查询出来的总未读数。
  • 会话标记列表(ZIMConversationTotalUnreadMessageCountQueryConfig.marks)只支持 [1, 20] 的整数:
    • 若列表包含 -1,查询结果为所有已标记会话;
    • 若列表包含 0,查询结果为所有无标记的会话;
    • 若传入多个标记,查询结果为所有传入标记的并集;
    • 若列表为空,则查询结果为所有会话。
  • 仅查询单聊会话和群聊会话。
Untitled
// 以查询包含标记为 1 的群聊会话总未读数为例
ZIMConversationTotalUnreadMessageCountQueryConfig config = new ZIMConversationTotalUnreadMessageCountQueryConfig();
config.marks.add(1); // 这里填入需要查询的标记
config.conversationTypes.add(ZIMConversationType.GROUP); // 这里填入需要查询的会话类型。若该列表为空,则同时查询单聊和群聊会话。
zim.queryConversationTotalUnreadMessageCount(config, new ZIMConversationTotalUnreadMessageCountQueriedCallback() {
    @Override
    public void onConversationTotalUnreadMessageCountQueried(int unreadMessageCount, ZIMError errorInfo) {
        if(errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 查询成功的处理
        } else {
            // 查询失败的处理
        }
    }
});
1
Copied!

Previous

保存会话草稿

Next

缓存管理