会话管理

---

功能简介

会话，指当用户发送“单聊/群聊”消息时，SDK 自动建立的逻辑关系。ZIM SDK 提供了会话管理功能，支持用户登录后拉取会话列表、创建/更新/删除会话、置顶会话等。

通常可以应用在社交聊天、游戏社区、在线咨询等业务场景中，获取展示单聊、群聊会话列表。

前提条件

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

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

使用方法

拉取会话列表

用户登录后，如果想要查询自己参与过的会话记录，可以调用 queryConversationList 接口，拉取会话数据列表。

由于本地会话可能数量较多，拉取会话时，开发者可以通过 ZIMConversationQueryConfig 对象，设置自定义分页拉取会话的数量，避免引起一次性拉取过多的会话导致耗时较久、会话界面加载较慢等问题。

调用接口示例

public abstract void queryConversationList(ZIMConversationQueryConfig config, ZIMConversationListQueriedCallback callback);

参数说明

示例代码

ZIMConversationQueryConfig config = new ZIMConversationQueryConfig();
// 会话锚点，传空则代表从最新开始查询
config.nextConversation = null;
// 会话一次分页查询数
config.count = 20;

// 拉取会话列表
zim.queryConversationList(config, new ZIMConversationListQueriedCallback() {
    @Override
    public void onConversationListQueried(ArrayList<ZIMConversation> conversationList, ZIMError errorInfo) {
        // 获取会话列表查询结果
        if(errorInfo.code == ZIMErrorCode.SUCCESS) {
          // 开发者需要保存和维护数组内的会话对象
        } else {
          // ......
        }      
    }
});

ZIMConversation 属性

拉取到会话信息后，开发者可以自定义会话列表的 UI 展示。获取到的会话列表信息 ZIMConversation，包含如下属性：

更新会话列表

用户登录后，当出现以下情况时，如果开发者已经注册了 setEventHandler 监听的 onConversationChanged 回调接口，将会收到相关的消息通知：

• 有新增会话。
• 某些会话的最后一条消息更新。
• 会话消息未读数量发生变化。
• 会话被置顶或被取消置顶。

此时开发者需要根据情况，通过 queryConversationList 接口更新会话列表。

调用接口示例

public void onConversationChanged(ZIM zim, ArrayList<ZIMConversationChangeInfo> conversationChangeInfoList){

}

参数说明

示例代码

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

...

public void onConversationChanged(ZIM zim, ArrayList<ZIMConversationChangeInfo> conversationChangeInfoList) {
    super.onConversationChanged(zim, conversationChangeInfoList);

}

清除单个会话消息未读数

用户登录并成功拉取到会话列表后，可以通过调用 clearConversationUnreadMessageCount 接口，清除某个会话的未读消息数。

由于 SDK 并不知道用户何时应该清除会话未读数，因此开发者需要在用户与某些页面交互时触发调用该接口，以下为常见的调用时机：

• 点击会话，进入了该会话的聊天界面内，需要调用该接口。
• 用户一直处于聊天界面，每次收到消息后，都需要调用该接口。
• 在会话列表界面中，标记某条未读的会话为已读时，需要调用该接口。

调用接口示例

public abstract void clearConversationUnreadMessageCount(String conversationID, ZIMConversationType conversationType, ZIMConversationUnreadMessageCountClearedCallback callback);

参数说明

示例代码

zim.clearConversationUnreadMessageCount("CONV_ID", ZIMConversationType.PEER, new ZIMConversationUnreadMessageCountClearedCallback() {
    @Override
    public void onConversationUnreadMessageCountCleared(ZIMError errorInfo) {
        // 获取清除未读数的结果
        if(errorInfo.code == ZIMErrorCodeSuccess) {
          // ......
        } else {
          // ......
        }   
    }
});

清除全部会话消息未读数

用户登录并成功拉取到会话列表后，可以通过调用 clearConversationTotalUnreadMessageCount 接口，清除全部会话的未读消息数。

当开发者想实现清除全部会话消息未读数和消息未读总数时，可使用该接口。

调用接口示例

public abstract void clearConversationTotalUnreadMessageCount(
        ZIMConversationTotalUnreadMessageCountClearedCallback callback);

参数说明

示例代码

// 清除全部会话的未读消息数量
zim.clearConversationTotalUnreadMessageCount(new ZIMConversationTotalUnreadMessageCountClearedCallback() {
    @Override
    public void onConversationTotalUnreadMessageCountCleared(ZIMError errorInfo) {
        // 获取清除未读数的结果
        if(errorInfo.code == ZIMErrorCodeSuccess) {
          // ......
        } else {
          // ......
        }   
    }
});

获取消息未读总数

用户登录后，可以查询自己当前有多少未读消息。开发者可以通过 setEventHandler 监听的 onConversationTotalUnreadMessageCountUpdated 回调接口，获取消息的未读总数。

用户登录成功后，以下情况出现时，均会通过该接口，获取消息未读总数更新的通知：

• 用户接收到新消息、且当前会话没有开启消息免打扰。
• 用户主动清理了会话未读数量，具体请参考 清除会话消息未读数。

开发者可以通过此回调通知，调整自己应用的 UI 展示，用于提醒用户当前有多少条消息未读。

调用接口示例

public void onConversationTotalUnreadMessageCountUpdated(ZIM zim, int totalUnreadMessageCount);

参数说明

示例代码

// 注册 SDK 事件通知监听
zim.setEventHandler(this);

...

// 接收消息未读总数的回调通知
public void onConversationTotalUnreadMessageCountUpdated(ZIM zim, int totalUnreadMessageCount) {
    // 获取会话总未读数用于 UI 展示
    // ......
}

设置消息免打扰

会话消息免打扰，指设置之后，SDK 在接收到当前会话的消息时，将不会进行推送通知，同时“消息未读总数”也不会增加。

开发者可以调用 setConversationNotificationStatus 接口，传入 conversationID 指定某个会话，设置消息免打扰功能。

调用接口示例

public abstract void setConversationNotificationStatus(ZIMConversationNotificationStatus status, String conversationID, ZIMConversationType type, ZIMConversationNotificationStatusSetCallback callback);

参数说明

示例代码

// 将某个会话设置为消息免打扰状态
// 以单聊会话为例

// 设置会话类型为单聊
ZIMConversationType conversationType = ZIMConversationType.PEER;

// 设置会话为免打扰
zim.setConversationNotificationStatus(ZIMConversationNotificationStatus.DO_NOT_DISTURB, "CONV_ID", conversationType, new ZIMConversationNotificationStatusSetCallback() {
    @Override
    public void onConversationNotificationStatusSet(ZIMError errorInfo) {
        // 设置消息免打扰的结果
        if(errorInfo.code == ZIMErrorCodeSuccess) {
          // ......
        } else {
          // ......
        }  
    }
});

删除单个会话

用户登录后，可以删除自己的会话列表中的某个会话。开发者通过调用 deleteConversation 接口，传入 conversationID 指定会话，删除某个会话。

调用接口示例

public abstract void deleteConversation(String conversationID, ZIMConversationType type, ZIMConversationDeleteConfig config, ZIMConversationDeletedCallback callback);

参数说明

示例代码

// 删除某个会话，以下为 删除单聊会话
ZIMConversationDeleteConfig config = new ZIMConversationDeleteConfig();
config.isAlsoDeleteServerConversation = true;

zim.deleteConversation("CONV_ID", ZIMConversationType.GROUP, config, new ZIMConversationDeletedCallback() {
    @Override
    public void onConversationDeleted(ZIMError errorInfo) {
        // 获取删除会话的结果
        if(errorInfo.code == ZIMErrorCodeSuccess) {
          // ......
        } else {
          // ......
        }            
    }
});

置顶会话

会话置顶指的是将单聊或者群聊会话固定于会话列表的顶部，不会被其他非置顶会话挤到底部，方便用户查找。用户通过客户端将会话置顶后，置顶状态会存储在服务器，因此，当用户切换终端设备后，置顶状态会同步到当前设备。

置顶顺序说明

• 置顶会话始终排在未置顶会话之前。

  对于通过调用 queryConversationList 接口拉取的会话列表，此规则同样适用。开发者可以通过拉取结果中 ZIMConversation 的 isPinned 字段，确认会话是否被置顶。

• 用户置顶多个会话后，相关会话之间的相对顺序仍然会保持。
  假设有 5 个会话，在会话列表中的现有排序为：a、b、c、d、e。
  用户将会话 b 和 d 置顶（不论先置顶哪个），顺序变更为 b、d、a、c、e，即 b 和 d 排在最前面，并且会话 b 仍然排在 d 之前。

  上述场景成立的前提为会话的 orderKey 没有被其他事件改变（如收到新消息后，会话的 order key 会变大）。当 orderKey 变化后，置顶会话列表中的顺序会改变。

实现流程

用户登录后，可调用 updateConversationPinnedState 接口置顶或取消置顶自己会话列表中的某个会话。

调用接口示例

// 修改会话置顶状态
public abstract void updateConversationPinnedState(boolean isPinned, String conversationID, 
                                                   ZIMConversationType conversationType,
                                                   ZIMConversationPinnedStateUpdatedCallback callback);

参数说明

示例代码

// 置顶某单聊会话
boolean isPinned = true;
zim.updateConversationPinnedState(isPinned, conversation.conversationID, conversation.type, new ZIMConversationPinnedStateUpdatedCallback() {
        @Override
        public void onConversationPinnedStateUpdated(String conversationID, ZIMConversationType conversationType, ZIMError errorInfo) {
             // 更新会话置顶状态后的回调。
        }
    });

查询置顶会话列表

实现流程

用户登录后，可以通过 queryConversationPinnedList 接口，获取全量的置顶会话列表。

调用接口示例

// 查询置顶会话列表
public abstract void queryConversationPinnedList(ZIMConversationQueryConfig config,
                                                 ZIMConversationPinnedListQueriedCallback callback);

参数说明

示例代码

ZIMConversationQueryConfig config = new ZIMConversationQueryConfig();
config.nextConversation = null;// 第一次传null，后续传列表最后一个会话作为锚点。
config.count = count; // 每次获取置顶会话的数量

// 拉取置顶会话列表
zim.queryConversationPinnedList(config, new ZIMConversationPinnedListQueriedCallback() {
    @Override
    public void onConversationPinnedListQueried(ArrayList<ZIMConversation> conversationList, ZIMError errorInfo) {
        // 获取到置顶列表数据。
    }
});

查询会话信息

实现流程

用户登录后，可以调用 queryConversation 接口，指定会话 ID 及会话类型，获取对应会话的详细信息（包括会话名称、会话未读数、会话通知状态等）。

示例代码

String conversationID = "convId";
ZIMConversationType type = ZIMConversationType.PEER;

// 查询会话信息
zim.queryConversation(conversationID,type, new ZIMConversationQueriedCallback() {
    @Override
    public void onConversationQueried(ZIMConversation conversation, ZIMError errorInfo) {
        // 查询会话的信息。
    }
});

删除全部会话

用户登录后，可以删除会话列表中的所有会话。开发者通过调用 deleteAllConversations 接口删除全部会话。

调用接口示例

public abstract void deleteAllConversations(ZIMConversationDeleteConfig config,
                                            ZIMConversationsAllDeletedCallback callback);

参数说明

示例代码

// 删除全部会话
ZIMConversationDeleteConfig config = new ZIMConversationDeleteConfig();
config.isAlsoDeleteServerConversation = true;

zim.deleteAllConversations(config, new ZIMConversationsAllDeletedCallback() {
    @Override
    public void onConversationsAllDeleted(ZIMError errorInfo) {
             // 删除全部会话后的回调。
        }
});

保存会话草稿

会话草稿，指用户正在编辑但尚未发送的文本消息。ZIM 支持用户退出会话后仍在本地保存会话草稿，以便继续编辑。

调用 setConversationDraft 接口，传入 conversationID 与conversationType 指定某个会话，即可将草稿保存到会话。

保存草稿成功后，可以通过onConversationChanged 回调接口获取草稿变更后的会话信息。

调用接口示例

public abstract void setConversationDraft(String draft, String conversationID,
                                              ZIMConversationType conversationType,
                                              ZIMConversationDraftSetCallback callback);

参数说明

示例代码

// 为某个会话设置草稿
// 以群聊会话为例
zim.setConversationDraft("draft", "Group_ID", ZIMConversationType.GROUP, new ZIMConversationDraftSetCallback() {
    @Override
    public void onConversationDraftSet(ZIMError errorInfo) {
             // 设置草稿后的回调。
        }
});