会话管理

---

功能简介

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

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

前提条件

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

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID 和 ServerSecret。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考 项目管理 - 即时通讯），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。

• 已获取登录 SDK 所需的 Token，详情请参考 使用 Token 鉴权。

• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息 的 “3 集成 SDK”。

使用方法

拉取会话列表

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

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

调用接口示例

queryConversationList(config: ZIMConversationQueryConfig): Promise<ZIMConversationListQueriedResult>

参数说明

示例代码

var config = {
    // 会话锚点，传空则代表从最新开始查询
    nextConversation: null,
    // 会话一次分页查询数
    count: 20
};

// 拉取会话列表
zim.queryConversationList(config)
    .then(function({ conversationList }){
        // 查询成功，开发者需要保存和维护数组内的会话对象
    })
    .catch(function(err){
        // 查询失败
    })

ZIMConversation 属性

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

更新会话列表

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

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

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

调用接口示例

zim.on('conversationChanged', function(zim, { infoList }){})

参数说明

示例代码

zim.on('conversationChanged', function(zim, { infoList }){
    console.log('conversationChanged', infoList)
})

清除单个会话消息未读数

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

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

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

调用接口示例

clearConversationUnreadMessageCount(
    conversationID: string,
    conversationType: ZIMConversationType,
): Promise<ZIMConversationUnreadMessageCountClearedResult> 

参数说明

示例代码

var conversationID = '';
var conversationType = 0;
zim.clearConversationUnreadMessageCount(conversationID, conversationType)
    .then(function(res){
        // 操作成功
    })
    .catch(function(err){
        // 操作失败
    })

清除全部会话消息未读数

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

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

调用接口示例

clearConversationTotalUnreadMessageCount(): Promise<void>;

参数说明

示例代码

// 清除全部会话的未读消息数量
zim.clearConversationTotalUnreadMessageCount()
    .then(function(){
        // 操作成功
    })
    .catch(function(err){
        // 操作失败
    })

获取消息未读总数

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

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

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

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

调用接口示例

zim.on('conversationTotalUnreadMessageCountUpdated', function(zim, { totalUnreadMessageCount }){})

参数说明

示例代码

zim.on('conversationTotalUnreadMessageCountUpdated', function(zim, { totalUnreadMessageCount }){
    // 获取会话总未读数用于 UI 展示
})

设置消息免打扰

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

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

调用接口示例

setConversationNotificationStatus(
    status: ZIMConversationNotificationStatus,
    conversationID: string,
    conversationType: ZIMConversationType,
): Promise<ZIMConversationNotificationStatusSetResult>

参数说明

示例代码

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

var status = 2;  // 将会话状态设置为免打扰 
var conversationID = '';
var conversationType = 2;  // 会话类型为群聊
zim.setConversationNotificationStatus(status, conversationID, conversationType)
    .then(function(res){
        // 操作成功
    })
    .catch(function(err){
        // 操作失败
    })

删除单个会话

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

调用接口示例

deleteConversation(
    conversationID: string,
    conversationType: ZIMConversationType,
    config: ZIMConversationDeleteConfig,
): Promise<ZIMConversationDeletedResult>

参数说明

示例代码

// 删除某个会话，以下为 删除单聊会话
var conversationID = '';
var conversationType = 0;
var config = { isAlsoDeleteServerConversation: true };
zim.deleteConversation(conversationID, conversationType, config)
    .then(function(res){
        // 操作成功
    })
    .catch(function(err){
        // 操作失败
    })

删除全部会话

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

调用接口示例

deleteAllConversations(config: ZIMConversationDeleteConfig): Promise<void>;

参数说明

示例代码

// 删除全部会话
var config = { isAlsoDeleteServerConversation: true };
zim.deleteAllConversations(config)
    .then(function(){
        // 操作成功
    })
    .catch(function(err){
        // 操作失败
    })

置顶会话

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

置顶顺序说明

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

  对于通过调用 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 接口置顶或取消置顶自己会话列表中的某个会话。

调用接口示例

// 修改会话置顶状态
updateConversationPinnedState(
    isPinned: boolean,
    conversationID: string,
    conversationType: ZIMConversationType,
): Promise<ZIMConversationPinnedStateUpdatedResult>

参数说明

示例代码

// 置顶某单聊会话
var isPinned = true;
var conversationID = "";
var conversationType = 0;
zim.updateConversationPinnedState(isPinned, conversationID, conversationType)
    .then(function(res){
        // 操作成功
    })
    .catch(function(err){
        // 操作失败
    })

查询置顶会话列表

实现流程

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

调用接口示例

// 查询置顶会话列表
queryConversationPinnedList(config: ZIMConversationQueryConfig): Promise<ZIMConversationPinnedListQueriedResult>

参数说明

示例代码

var config = {
    // 会话锚点，传空则代表从最新开始查询
    nextConversation: null,
    // 会话一次分页查询数
    count: 20
};

// 拉取会话列表
zim.queryConversationPinnedList(config)
    .then(function({ conversationList }){
        // 查询成功，开发者需要保存和维护数组内的会话对象
    })
    .catch(function(err){
        // 查询失败
    })

查询会话信息

实现流程

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

示例代码

// 查询会话信息
var conversationID = "xxx";
var conversationType = 0;

// 拉取会话列表
zim.queryConversation(conversationID, conversationType)
    .then(function({ conversation }){
        // 查询成功，开发者需要保存和维护数组内的会话对象
    })
    .catch(function(err){
        // 查询失败
    })

保存会话草稿

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

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

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

调用接口示例

setConversationDraft(
        draft: string,
        conversationID: string,
        conversationType: ZIMConversationType,
    ): Promise<ZIMConversationDraftSetResult>

参数说明

示例代码

// 为某个会话设置草稿
// 以群聊消息为例
zim.setConversationDraft("draft", "Group_ID", 2).then(function({ conversationID, conversationType }){
        // 保存成功后的业务逻辑
    })
    .catch(function(err){
        // 请查看错误码文档获取解决建议
    });