会话管理

更新时间: 2024/05/23 19:26:40

云信 IM 支持用户会话管理功能,包括创建、更新、删除会话等基础操作,以及置顶会话等进阶操作。

本文介绍如何调用 NIM SDK 的接口实现用户会话管理。

技术原理

云信 IM 支持云端(服务端)会话,在服务器进行存储和维护,支持存储和查询用户全量的会话历史消息。服务端会话及未读数请参考新版服务端 API-会话管理

当用户发送消息时,SDK 会自动创建会话并更新最近会话列表,但在特定场景下需要您手动创建会话,例如:创建一个空会话占位。

SDK 会自动同步服务端数据,如果您注册了会话相关监听,数据同步开始和同步结束均有回调通知;如果数据同步已开始,建议您在数据同步结束后再进行会话其他操作;在新设备登录 IM 后,SDK 会根据当前的漫游、离线消息自动生成最近会话列表。

前提条件

已实现登录 IM

监听会话相关事件

在进行会话相关操作前,您可以提前注册监听相关事件。注册成功后,当会话相关事件发生时,SDK 会触发对应回调通知。

Android/iOS/macOS/Windows

调用 addConversationListener 方法注册会话相关监听器,监听数据同步开始结束、会话创建、删除、变更及未读数变化等。

  • 相关回调:

    • onSyncStarted:数据同步开始回调。
    • onSyncFinished:数据同步结束回调。如果数据同步已开始,建议在数据同步结束后再进行其他会话操作。
    • onSyncFailed:数据同步失败回调。
    • onConversationCreated:会话成功创建回调。当本地端或多端同步创建会话成功时会触发该回调。
    • onConversationDeleted:主动删除会话回调。当本地端或多端同步删除会话成功时会触发该回调。
    • onConversationChanged:会话变更回调。当本地端或多端同步置顶会话、会话有新消息、主动更新会话成功时会触发该回调。
    • onTotalUnreadCountChanged:会话消息总未读数变更回调。
    • onUnreadCountChangedByFilter:过滤后的未读数变更回调。调用 subscribeUnreadCountByFilter 方法订阅监听后,当会话过滤后的未读数变化时会返回该回调。
  • 示例代码:

    调用 addConversationListener 方法:

    Android
    javaV2NIMConversationListener listener = new V2NIMConversationListener() {
        @Override
        public void onSyncStarted() {
            // TODO
        }
    
        @Override
        public void onSyncFinished() {
            // TODO
        }
    
        @Override
        public void onSyncFailed(V2NIMError error) {
            // TODO
        }
    
        @Override
        public void onConversationCreated(V2NIMConversation conversation) {
            // TODO
        }
    
        @Override
        public void onConversationDeleted(List<String> conversationIds) {
            // TODO
        }
    
        @Override
        public void onConversationChanged(List<V2NIMConversation> conversationList) {
            // TODO
        }
    
        @Override
        public void onTotalUnreadCountChanged(int unreadCount) {
            // TODO
        }
    
        @Override
        public void onUnreadCountChangedByFilter(V2NIMConversationFilter filter, int unreadCount) {
            // TODO
        }
    };
    NIMClient.getService(V2NIMConversationService.class).addConversationListener(listener);
    
    iOS
    objective-c@interface V2ConversationServiceSample : NSObject <V2NIMConversationListener>
    
    @end
    
    @implementation V2ConversationServiceSample
    
    - (void)onSyncStarted
    {
        // sync started
    }
    
    - (void)onSyncFinished
    {
        // sync finished
    }
    
    - (void)onSyncFailed:(V2NIMError *)error
    {
        // sync failed
    }
    
    - (void)onConversationCreated:(V2NIMConversation *)conversation
    {
        // conversation created
    }
    
    - (void)onConversationDeleted:(NSArray<NSString *> *)conversationIds
    {
        // conversations deleted
    }
    
    - (void)onConversationChanged:(NSArray<V2NIMConversation *> *)conversations
    {
        // conversations changed
    }
    
    - (void)onTotalUnreadCountChanged:(NSInteger)unreadCount
    {
        // total unread count changed
    }
    
    - (void)onUnreadCountChangedByFilter:(V2NIMConversationFilter *)filter
                            unreadCount:(NSInteger)unreadCount
    {
        // filter unread count changed
    }
    
    - (void)addConversationListener
    {
        [NIMSDK.sharedSDK.v2ConversationService addConversationListener:self];
    }
    
    @end
    
    macOS/Windows
    cppV2NIMConversationListener listener;
    listener.onSyncStarted = []() {
        // handle conversation sync start event
    };
    listener.onSyncFinished = []() {
        // handle conversation sync finish event
    };
    listener.onSyncFailed = [](V2NIMError error) {
        // handle conversation sync failed event
    };
    listener.onConversationCreated = [](V2NIMConversation conversation) {
        // handle conversation created event
    };
    listener.onConversationDeleted = [](nstd::vector<nstd::string> conversationIds) {
        // handle conversation deleted event
    };
    listener.onConversationChanged = [](nstd::vector<V2NIMConversation> conversationList) {
        // handle conversation changed event
    };
    listener.onTotalUnreadCountChanged = [](uint32_t unreadCount) {
        // handle total unread count changed event
    };
    listener.onUnreadCountChangedByFilter = [](V2NIMConversationFilter filter, uint32_t unreadCount) {
        // handle unread count changed by group event
    };
    conversationService.addConversationListener(listener);
    

    如需移除会话相关监听器,可调用 removeConversationListener

    Android
    javaNIMClient.getV2NIMConversationServcie().removeConversationListener(listener);
    
    iOS
    objective-cid<V2NIMConversationListener> listener;
    [NIMSDK.sharedSDK.v2ConversationService removeConversationListener:listener];
    
    macOS/Windows
    cppV2NIMConversationListener listener;
    conversationService.removeConversationListener(listener);
    

    调用 subscribeUnreadCountByFilter 方法订阅过滤后的会话未读数变化监听:

    Android
    javaV2NIMConversationFilter filter = new V2NIMConversationFilter();
    List<V2NIMConversationType> conversionTypes = new ArrayList<>();
    conversionTypes.add(V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
    filter.setConversationTypes(conversionTypes);
    filter.setConversationGroupId("会话分组id");
    filter.setIgnoreMuted(true);
    V2NIMError result = NIMClient.getService(V2NIMConversationService.class).subscribeUnreadCountByFilter(filter);
    if(result == null){
        // success
    }else{
        int code = result.getCode();
        String desc = result.getDesc();
        // handle error
    }
    
    iOS
    objective-cV2NIMConversationFilter *filter = [[V2NIMConversationFilter alloc] init];
    filter.conversationTypes = @[
        @(V2NIM_CONVERSATION_TYPE_P2P),
        @(V2NIM_CONVERSATION_TYPE_TEAM),
    ];
    filter.conversationGroupId = @"groupId";
    filter.ignoreMuted = YES;
    [NIMSDK.sharedSDK.v2ConversationService subscribeUnreadCountByFilter:filter];
    
    macOS/Windows
    cppV2NIMConversationFilter filter;
    filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
    conversationService.subscribeUnreadCountByFilter(filter);
    

    如需取消订阅可调用 unsubscribeUnreadCountByFilter 方法:

    Android
    javaV2NIMError result = NIMClient.getService(V2NIMConversationService.class).unsubscribeUnreadCountByFilter(filter);
    if(result == null){
        // success
    }else{
        int code = result.getCode();
        String desc = result.getDesc();
        // handle error
    }
    
    iOS
    objective-cV2NIMConversationFilter *filter = [[V2NIMConversationFilter alloc] init];
    filter.conversationTypes = @[
        @(V2NIM_CONVERSATION_TYPE_P2P),
        @(V2NIM_CONVERSATION_TYPE_TEAM),
    ];
    filter.conversationGroupId = @"groupId";
    filter.ignoreMuted = YES;
    [NIMSDK.sharedSDK.v2ConversationService unsubscribeUnreadCountByFilter:filter];
    
    macOS/Windows
    cppV2NIMConversationFilter filter;
    filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
    conversationService.unsubscribeUnreadCountByFilter(filter);
    

Web/uni-app/小程序/Harmony

调用 on("EventName") 方法注册会话相关监听,监听数据同步开始结束、会话创建、删除、变更及未读数变化等。

  • 相关回调:

    • onSyncStarted:数据同步开始回调。
    • onSyncFinished:数据同步结束回调。如果数据同步已开始,建议在数据同步结束后进行会话其他操作。
    • onSyncFailed:数据同步失败回调。
    • onConversationCreated:会话成功创建回调。当本地端或多端同步创建会话成功时会触发该回调。
    • onConversationDeleted:主动删除会话回调。当本地端或多端同步删除会话成功时会触发该回调。
    • onConversationChanged:会话变更回调。当本地端或多端同步置顶会话、会话有新消息、主动更新会话成功时会触发该回调。
    • onTotalUnreadCountChanged:会话消息总未读数变更回调。
    • onUnreadCountChangedByFilter:会话过滤后的未读数变更回调。调用 subscribeUnreadCountByFilter 方法订阅监听后,当会话过滤后的未读数变化时会返回该回调。
  • 示例代码:

    Web/uni-app/小程序
    typescriptnim.V2NIMConversationService.on("onSyncStarted", function () {})
    nim.V2NIMConversationService.on("onSyncFinished", function () {})
    nim.V2NIMConversationService.on("onSyncFailed", function (err) {})
    nim.V2NIMConversationService.on("onConversationCreated", function (conversation: V2NIMConversation) {})
    nim.V2NIMConversationService.on("onConversationDeleted", function (conversationIds: string[]) {})
    nim.V2NIMConversationService.on("onConversationChanged", function (conversationList: V2NIMConversation[]) {})
    nim.V2NIMConversationService.on("onTotalUnreadCountChanged", function (unreadCount: number) {})
    nim.V2NIMConversationService.on("onUnreadCountChangedByFilter", function (filter: V2NIMConversationFilter & { equals: (filter: V2NIMConversationFilter) => boolean }, unreadCount: number) {
    // todo success
    // if filter.equals(TARGET_FILTER)
    })
    

    如需移除会话相关监听,可调用 off("EventName")

    typescriptnim.V2NIMConversationService.off("onSyncStarted")
    nim.V2NIMConversationService.off("onSyncFinished")
    nim.V2NIMConversationService.off("onSyncFailed")
    nim.V2NIMConversationService.off("onConversationCreated")
    nim.V2NIMConversationService.off("onConversationDeleted")
    nim.V2NIMConversationService.off("onConversationChanged")
    nim.V2NIMConversationService.off("onTotalUnreadCountChanged")
    nim.V2NIMConversationService.off("onUnreadCountChangedByFilter")
    

    调用 subscribeUnreadCountByFilter 方法订阅过滤后的会话未读数变化监听:

    typescriptconst filter = {
        conversationTypes: [1]  
    }
    nim.V2NIMConversationService.subscribeUnreadCountByFilter(filter)
    

    如需取消订阅可调用 unsubscribeUnreadCountByFilter 方法:

    typescriptconst filter = {
        conversationTypes: [1]  
    }
    nim.V2NIMConversationService.unsubscribeUnreadCountByFilter(filter)
    
    Harmony
    typescriptnim.conversationService.on("onSyncStarted", () => {})
    nim.conversationService.on("onSyncFinished", () => {})
    nim.conversationService.on("onSyncFailed", (err) => {})
    nim.conversationService.on("onConversationCreated", (conversation: V2NIMConversation) => {})
    nim.conversationService.on("onConversationDeleted", (conversationIds: string[]) => {})
    nim.conversationService.on("onConversationChanged", (conversationList: V2NIMConversation[]) => {})
    nim.conversationService.on("onTotalUnreadCountChanged", (unreadCount: number) => {})
    nim.conversationService.on("onUnreadCountChangedByFilter", (filter: V2NIMConversationFilter, unreadCount: number) => {
    // todo success
    // if filter.equals(TARGET_FILTER)
    })
    

    如需移除会话相关监听,可调用 off("EventName")

    typescriptnim.conversationService.off("onSyncStarted", theListner)
    nim.conversationService.off("onSyncFinished", theListner)
    nim.conversationService.off("onSyncFailed", theListner)
    nim.conversationService.off("onConversationCreated", theListner)
    nim.conversationService.off("onConversationDeleted", theListner)
    nim.conversationService.off("onConversationChanged", theListner)
    nim.conversationService.off("onTotalUnreadCountChanged", theListner)
    nim.conversationService.off("onUnreadCountChangedByFilter", theListner)
    // remove all listeners
    nim.conversationService.removeAllListeners()
    

    调用 subscribeUnreadCountByFilter 方法订阅过滤后的会话未读数变化监听:

    typescriptconst filter: V2NIMConversationFilter = {
    conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
    }
    try {
    this.conversationService.subscribeUnreadCountByFilter(filter)
    // success
    } catch (e) {
    // fail
    }
    

    如需取消订阅可调用 unsubscribeUnreadCountByFilter 方法:

    typescriptconst filter: V2NIMConversationFilter = {
    conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
    }
    try {
    this.conversationService.unsubscribeUnreadCountByFilter(filter)
    // success
    } catch (e) {
    // fail
    }
    

创建会话

一般场景下,当本地端收发消息,SDK 会自动创建一条会话。特殊场景下,例如需要本地会话占位,您可以调用 createConversation 方法创建一条空会话。

本地端或多端同步创建成功后,SDK 会返回创建成功回调 onConversationCreated,并同步缓存和数据库。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID
  • 组成方式: 用户账号 (accid)|会话类型(V2NIMConversationType)|聊天对象账号(accid)或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法,则返回 191004 参数错误。
  • 不可设置为空,否则也返回 191004 参数错误。
  • success V2NIMSuccessCallback - 创建会话成功回调,返回 V2NIMConversation
    failure V2NIMFailureCallback - 创建会话失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID
  • 组成方式: 用户账号 (accid)|会话类型(V2NIMConversationType)|聊天对象账号(accid)或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法,则返回 191004 参数错误。
  • 不可设置为空,否则也返回 191004 参数错误。
  • success V2NIMConversationCallback - 创建会话成功回调,可自定义。
    failure V2NIMFailureCallback - 创建会话失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID
  • 组成方式: 用户账号 (accid)|会话类型(V2NIMConversationType)|聊天对象账号(accid)或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法,则返回 191004 参数错误。
  • 不可设置为空,否则也返回 191004 参数错误。
  • success V2NIMSuccessCallback - 创建会话成功回调,返回 V2NIMConversation
    failure V2NIMFailureCallback - 创建会话失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID
  • 组成方式: 用户账号 (accid)|会话类型(V2NIMConversationType)|聊天对象账号(accid)或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法,则返回 191004 参数错误。
  • 不可设置为空,否则也返回 191004 参数错误。
  • Harmony
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID
  • 组成方式: 用户账号 (accid)|会话类型(V2NIMConversationType)|聊天对象账号(accid)或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法,则返回 191004 参数错误。
  • 不可设置为空,否则也返回 191004 参数错误。
  • 示例代码:

    Android
    javaString conversationId = V2NIMConversationIdUtil.p2pConversationId("accountId");
    NIMClient.getService(V2NIMConversationService.class).createConversation (conversationId, new V2NIMSuccessCallback<V2NIMConversation>(){
        @Override
        public void onSuccess(V2NIMConversation conversation){
            // conversation created
        }
    }, new V2NIMFailureCallback(){
        @Override
        public void onFailure(V2NIMError error){
            int code = error.getCode();
            String desc = error.getDesc();
            // create failed, handle error
        }
    });
    
    iOS
    objective-cNSString *conversationId = [V2NIMConversationIdUtil p2pConversationId:@"accountId"];
    [NIMSDK.sharedSDK.v2ConversationService createConversation:conversationId success:^(V2NIMConversation *conversation) {
        // conversation created
    } failure:^(V2NIMError *error) {
        // create failed, handle error
    }];
    
    macOS/Windows
    cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
    conversationService.createConversation(
        conversationId,
        [](V2NIMConversation conversation) {
            // create succeeded
        },
        [](V2NIMError error) {
            // create failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
      const data = await nim.V2NIMConversationService.createConversation("CONVERSATION_ID");
      // conversation created
    } catch (err) {
      // create failed, handle error
    }
    
    Harmony
    typescripttypescript
    let conversationId: string = "cjl|1|cjl1";
    try {
    let conv: V2NIMConversation = await this.conversationService.createConversation(conversationId)
    // success
    } catch (e) {
    // fail
    }
    

获取会话

云信 IM 提供多种方式获取会话列表,用于在应用首页显示用户会话。

分页获取所有会话列表

调用 getConversationList 方法从客户端本地分页获取会话数据,直到获取全量会话。

获取的会话列表结果中,置顶会话排首位。如有多个置顶会话,则按照时间顺序倒序展示。

如果数据同步已开始(收到 onSyncStarted 回调),建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作,否则可能无法获取到全量完整会话列表。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    offset Long - 分页偏移。首次调用传 0,后续调用时传入一次调 用返回的 offset
    limit Int - 单次查询会话数量上限,建议不超过 100设置为 小于或等于 0 则默认为 100。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversationResult
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    offset Long - 分页偏移。首次调用传 0,后续调用时传入一次调用返回的 offset
    limit NSInteger - 单次查询会话数量上限,建议不超过100。设置为小于或等于 0 则默认为 10。
    success V2NIMConversationResultCallback - 查询话列表成功回调,可自定 义。
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    offset uint64_t - 分页偏移。首次调用传 0,后续调用传入上一次调用返回的 offset
    limit uint32_t - 单次查询会话数量上限,建议不超过100。设置为小于或等于 0 则默认为 10。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversationResult
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    offset Number - 分页偏移。首次调用传 0,后续调用时传上一次调用返回的 offset
    limit Number - 单次查询会话数量上限,建议不超过 10。设置为小于或等于 0 则默认为 10。
    Harmony
    参数名称 类型 是否必填 默认值 描述
    offset Number - 分页偏移。首次调用传 0,后续调用时传上一次调用返回的 offset
    limit Number - 单次查询会话数量上限,建议不超过 10。设置为小于或等于 0 则默认为 10。
  • 示例代码:

    Android
    javaNIMClient.getV2NIMConversationServcie().getConversionList(0, 100, new V2NIMSuccessCallback<V2NIMConversationResult>() {
        @Override
        public void onSuccess(V2NIMConversationResult result) {
            // success     
        }    
    }, new V2NIMFailueCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            int code = error.code;
            String desc = error.desc;
            // handle error
        }   
    });
    
    iOS
    objective-c[NIMSDK.sharedSDK.v2ConversationService getConversationList:0 limit:10 success:^(V2NIMConversationResult *result) {
        // receive result
    } failure:^(V2NIMError *error) {
        // handle error
    }];
    
    macOS/Windows
    cppconversationService.getConversationList(
        lastCursor,
        10,
        [](V2NIMConversationResult result) {
            // get conversation list succeeded
        },
        [](V2NIMError error) {
            // get conversation list failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    const result = await nim.V2NIMConversationService.getConversationList(0, 100)
    // receive result
    } catch (err) {
    // handle error
    }
    
    Harmony
    typescripttry {
    const result = await nim.conversationService.getConversationList(0, 100)
    // success
    } catch (err) {
    // fail
    }
    

获取指定单条会话

调用 getConversation 按照会话 ID 获取指定会话。

如果数据同步已开始(收到 onSyncStarted 回调),建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作,否则可能无法获取到完整会话数据。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversation
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    conversationId NSString - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMConversationCallback - 查询会话成功回调,可自定义。
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversation
    failure V2NIMFailureCallback - 查询失败回调,返回错误码 查询失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    Harmony
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
  • 示例代码:

    Android
    javaNIMClient.getV2NIMConversationServcie().getConversation("会话id", new V2NIMSuccessCallback<V2NIMConversation>(){
        @Override
        public void onSuccess(V2NIMConversation conversation){
            // success    
        }    
    }, new V2NIMFailueCallback(){
        @Override
        public void onFailure(V2NIMError error){
            int code = error.getCode();
            String desc = error.getDesc();
            // handle error
        }   
    });
    
    iOS
    objective-c[NIMSDK.sharedSDK.v2ConversationService getConversation:@"conversationId" success:^(V2NIMConversation *conversation) {
        // success
    } failure:^(V2NIMError *error) {
        // handle error
    }];
    
    macOS/Windows
    cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
    conversationService.getConversation(
        conversationId,
        [](V2NIMConversation conversation) {
            // get conversation succeeded
        },
        [](V2NIMError error) {
            // get conversation failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    const data = await nim.V2NIMConversationService.getConversation("TARGET_CONVERSATION_ID")
    // success
    } catch (err) {
    // handle error
    }
    
    Harmony
    typescriptlet conversationId: string = "cjl|1|cjl1";
    try {
    let conv: V2NIMConversation = await this.conversationService.getConversation(conversationId)
    // success
    } catch (e) {
    // fail
    }
    

根据查询选项分页获取会话列表

调用 getConversationListByOption 按照设定的查询选项分页获取会话列表,直到获取全量会话。

获取的会话列表结果中,置顶会话排首位。如有多个置顶会话,则按照时间顺序倒序展示。

如果数据同步已开始(收到 onSyncStarted 回调),建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作,否则可能无法获取到完整的会话列表。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    offset Long - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit Int - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 10
    option V2NIMConversationOption - 查询条件,设置为空则查询所有会话列表。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversationResult
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    offset Long - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit NSInteger - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 10
    option V2NIMConversationOption - 查询条件,设置为空则查询所有会话列表。
    success V2NIMConversationResultCallback - 查询会话列表成功回调,可自定义。
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    offset uint64_t - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit uint32_t - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 10
    option V2NIMConversationOption - 查询条件,设置为空则查询所有会话列表。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversationResult
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    offset Number - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit Number - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 10
    option V2NIMConversationOption - 查询条件,设置为空则查询所有会话列表。
    Harmony
    参数名称 类型 是否必填 默认值 描述
    offset Number - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit Number - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 10
    option V2NIMConversationOption - 查询条件,设置为空则查询所有会话列表。
  • 示例代码:

    Android
    javaV2NIMConversationOption option = new V2NIMConversationOption();
    List<Integer> conversionTypes = new ArrayList<Integer>();
    conversionTypes.add(1);
    options.setConversionTypes =conversionTypes;
    option.onlyUnread = true; 
    NIMClient.getV2NIMConversationServcie().getConversionListByOption(0, 100,option, new      V2NIMSuccessCallback<V2NIMConversationResult>>(){
        @Override
        public void onSuccess<V2NIMConversationResult>(V2NIMConversationResult result){
            // receive result     
        }    
    }, new V2NIMFailueCallback(){
        @Override
        public void onFailure(V2NIMError error){
            int code = error.code;
            String desc = error.desc;
            // handle error
        }   
    });
    
    iOS
    objective-cV2NIMConversationOption *option = [[V2NIMConversationOption alloc] init];
    option.conversationTypes = @[
        @(V2NIM_CONVERSATION_TYPE_P2P),
        @(V2NIM_CONVERSATION_TYPE_TEAM),
    ];
    option.conversationGroupIds = @[
        @"groupIdA",
        @"groupIdB",
    ];
    option.onlyUnread = YES;
    [NIMSDK.sharedSDK.v2ConversationService getConversationListByOption:0 limit:10 option:option success:^(V2NIMConversationResult *  result) {
        // receive result
    } failure:^(V2NIMError * error) {
        // handle error
    }];
    
    macOS/Windows
    cppV2NIMConversationOption option;
    option.onlyUnread = true;
    option.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
    conversationService.getConversationListByOption(
        lastCursor,
        10,
        option,
        [](V2NIMConversationResult result) {
            // get conversation list succeeded
        },
        [](V2NIMError error) {
            // get conversation list failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    const list = await nim.V2NIMConversationService.getConversationListByOption(0, 100, {
        conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
        onlyUnread: true,
    })
    // Success
    } catch (err) {
    // handle error
    }
    
    Harmony
    typescriptlet offset: number = 0;
    let limit: number = 100;
    let option: V2NIMConversationOption = {
    conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
    }
    
    try {
    let result: V2NIMConversationResult = await this.conversationService.getConversationListByOption(offset, limit, option)
    // success
    } catch (e) {
    // fail
    }
    

批量获取指定的会话列表

调用 getConversationListByIds 按照会话 ID 批量获取会话列表。

获取的会话列表结果中,置顶会话排首位。如有多个置顶会话,则按照时间顺序倒序展示。

如果数据同步已开始(收到 onSyncStarted 回调),建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作,否则可能无法获取到完整的会话列表。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    conversationIds List - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询成功回调,返回 List<V2NIMConversation>。
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    conversationIds NSString - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMConversationListCallback - 查询成功回调,可自定义。
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    conversationIds String - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询会话列表成功回调,返回 List<V2NIMConversation>。
    failure V2NIMFailureCallback - 查询失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    conversationIds string[] - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    Harmony
    参数名称 类型 是否必填 默认值 描述
    conversationIds string[] - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
  • 示例代码:

    Android
    javaNIMClient.getService(V2NIMConversationService.class).getConversationListByIds(ids, new    V2NIMSuccessCallback<List<V2NIMConversation>>() {
        @Override
        public void onSuccess(List<V2NIMConversation> conversations) {
            // receive conversation list
        }
    }, new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            int code = error.getCode();
            String desc = error.getDesc();
            // handle error
        }
    });
    
    iOS
    objective-c[NIMSDK.sharedSDK.v2ConversationService getConversationListByIds:@[@"conversationIdA", @"conversationIdB"] success:^    (NSArray<V2NIMConversation *> *conversationList) {
        // receive conversation list
    } failure:^(V2NIMError *error) {
        // handle error
    }];
    
    macOS/Windows
    cppauto conversationIds = nstd::vector<nstd::string>();
    conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account1"));
    conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account2"));
    conversationService.getConversationListByIds(
        conversationIds,
        [](V2NIMConversationList list) {
            // get conversation list succeeded
        },
        [](V2NIMError error) {
            // get conversation list failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    const ids = ["ID1", "ID2"]
    const list = await nim.V2NIMConversationService.getConversationListByIds(ids)
    // receive conversation list
    } catch (err) {
    // handle error
    }
    
    Harmony
    typescriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
    try {
    let result: V2NIMConversation[] = await this.conversationService.getConversationListByIds(conversationIds)
    // success
    } catch (e) {
    // fail
    }
    

更新会话扩展字段

调用 updateConversation 更新会话扩展字段。

本地端或多端同步更新成功后,SDK 会返回会话变更回调 onConversationChanged,并同步数据库、缓存及 Local Extension。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,包括本地扩展字段以及服务端扩展字段:
  • 本地扩展字段,不会多端同步
  • 服务器扩展字段,会多端同步
  • success V2NIMSuccessCallback - 更新会话成功回调
    failure V2NIMFailureCallback - 更新会话失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,包括本地扩展字段以及服务端扩展字段:
  • 本地扩展字段,不会多端同步
  • 服务器扩展字段,会多端同步
  • success V2NIMSuccessCallback - 更新会话成功回调
    failure V2NIMFailureCallback - 更新会话失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,包括本地扩展字段以及服务端扩展字段:
  • 本地扩展字段,不会多端同步
  • 服务器扩展字段,会多端同步
  • success V2NIMSuccessCallback - 更新会话成功回调
    failure V2NIMFailureCallback - 更新会话失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,包括本地扩展字段以及服务端扩展字段:
  • 本地扩展字段,不会多端同步
  • 服务器扩展字段,会多端同步
  • Harmony
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,包括本地扩展字段以及服务端扩展字段:
  • 本地扩展字段,不会多端同步
  • 服务器扩展字段,会多端同步
  • 示例代码:

    Android
    javaV2NIMConversationUpdate updateInfo = new V2NIMConversationUpdate();
    updateInfo.setServerExtension("serverextension");
    updateInfo.setLocalExtension("localextension");
    NIMClient.getService(V2NIMConversationService.class).updateConversation ("conversationId", updateInfo, new     V2NIMSuccessCallback<Void>() {
        @Override
        public void onSuccess(Void unused) {
            // success
        }
    }, new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            int code = error.getCode();
            String desc = error.getDesc();
            // handle error
        }
    });
    
    iOS
    objective-cV2NIMConversationUpdate *info = [[V2NIMConversationUpdate alloc] init];
    info.localExtension = @"localExtension";
    info.serverExtension = @"serverExtension";
    [NIMSDK.sharedSDK.v2ConversationService updateConversation:@"conversationId"    updateInfo:info success:^{
        // success
    } failure:^(V2NIMError *error) {
        // handle error
    }];
    
    macOS/Windows
    cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
    V2NIMConversationUpdate param;
    param.extension = "extension";
    conversationService.updateConversation(
        conversationId,
        param,
        []() {
            // update succeeded
        },
        [](V2NIMError error) {
            // update failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    const params = { serverExtention: "This is a new text" }
    await nim.V2NIMConversationService.updateConversation("CONVERSATION_ID", params)
    // Success
    } catch (err) {
    // handle error
    }
    
    Harmony
    typescriptlet conversationId: string = "cjl|1|cjl1"
    let userInfo: V2NIMConversationUpdate = {
    serverExtension: "serverExtension"
    }
    try {
    await this.conversationService.updateConversation(conversationId, userInfo)
    // success
    } catch (e) {
    // fail
    }
    

删除会话

删除指定单条会话

调用 deleteConversation 根据会话 ID 删除指定会话(包括本地和服务端会话),且支持指定是否删除会话内的历史消息(包括本地和漫游消息)。

删除指定会话后,应用总消息未读数会减去该会话的未读数。

本地端或多端同步删除成功后,SDK 会返回删除成功回调 onConversationDeleted,并同步数据库和缓存。

如果被删除会话中有消息未读,SDK 还会返回 onTotalUnreadCountChangedonUnreadCountChangedByFilter 回调。

建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    clearMessage Boolean false 是否同步删除会话中本地和服务端的历史消息
  • 删除本地和服务端的历史消 / li>
  • 只删除会话,保留历史消息。
  • success V2NIMSuccessCallback - 删除会话成功回调
    failure V2NIMFailureCallback - 删除会话失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空或不存在则返回 191004 参数错误。
    clearMessage Bool false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保 消息。
  • success V2NIMSuccessCallback - 删除会话成功回调
    failure V2NIMFailureCallback - 删除会话失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空或不存在则返回 191004 参数错误。
    clearMessage Bool false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保 史 消息。
  • success V2NIMSuccessCallback - 删除会话成功回调
    failure V2NIMFailureCallback - 删除会话失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空或不存在则返回 191004 参数错误。
    clearMessage Boolean false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保历 史消息。
  • Harmony
    参数名称 类型 是否必填 默认值 描述
    conversationId String - 会话 ID,如果为空或不存在则返回 191004 参数错误。
    clearMessage Boolean false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保历 史消息。
  • 示例代码:

    Android
    javaNIMClient.getService(V2NIMConversationService.class).deleteConversation("会话id", false, new V2NIMSuccessCallback<Void>() {
        @Override
        public void onSuccess(Void unused) {
            // delete succeeded
        }
    }, new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            int code = error.getCode();
            String desc = error.getDesc();
            // delete failed, handle error
        }
    });
    
    iOS
    objective-c[NIMSDK.sharedSDK.v2ConversationService deleteConversation:@"conversationId" clearMessage:NO success:^{
        // delete succeeded
    } failure:^(V2NIMError *error) {
        // delete failed, handle error
    }];
    
    macOS/Windows
    cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
    conversationService.deleteConversation(
        conversationId,
        true,
        []() {
            // delete succeeded
        },
        [](V2NIMError error) {
            // delete failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    await nim.V2NIMConversationService.deleteConversation("CONVERSATION_ID", true);
    // delete succeeded
    } catch (err) {
    // delete failed, handle error
    }
    
    Harmony
    typescriptlet conversationId: string = "cjl|1|cjl1";
    let clearMessage: boolean = true;
    try {
    await this.conversationService.deleteConversation(conversationId, clearMessage)
    // success
    } catch (e) {
    // fail
    }
    

批量删除指定会话列表

调用 deleteConversationListByIds 根据会话 ID 批量删除指定会话列表(包括本地和服务端会话),且支持指定是否删除会话内的历史消息(包括本地和漫游消息)。

批量删除成功后会返回删除失败的会话列表及错误信息,应用总消息未读数会减去已删除会话的未读数。

本地端或多端同步的每一条最近会话删除成功后,SDK 均会返回删除成功回调 onConversationDeleted 回调,并同步数据库和缓存。

如果被删除会话中有消息未读,SDK 还会返回 onTotalUnreadCountChangedonUnreadCountChangedByFilter 回调。

建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    conversationIds List - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次删除上限为 100 条。
  • clearMessage Boolean false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保历史消息。
  • success V2NIMSuccessCallback - 删除会话成功回调,返回 V2NIMConversationOperationResult,仅包含删除失败的会话 ID 及相关错误码。
    failure V2NIMFailureCallback - 删除会话失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    conversationIds NSArray - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用 上限为 100 条。
  • clearMessage Bool false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保留历史消 息。
  • success V2NIMConversationOperationResultListCallback - 删除会话成功回调,可自定义设 置。
    failure V2NIMFailureCallback - 删除会话失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    conversationIds String - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次删除上限为 100 条。
  • clearMessage Bool false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保史消息。
  • success V2NIMSuccessCallback - 删除会话成功回调,返回 V2NIMConversationOperationResult,仅包含删除失败的会话 ID 及相关错误码
    failure V2NIMFailureCallback - 删除会话失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    conversationIds String[] - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次删除上限为 100 条。
  • clearMessage Boolean false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保历史消息。
  • Harmony
    参数名称 类型 是否必填 默认值 描述
    conversationIds String[] - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次删除上限为 100 条。
  • clearMessage Boolean false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保历史消息。
  • 示例代码:

    Android
    javaNIMClient.getService(V2NIMConversationService.class).deleteConversationListByIds(ids, new      V2NIMSuccessCallback<List<V2NIMConversationOperationResult>>() {
        @Override
        public void onSuccess(List<V2NIMConversationOperationResult> results) {
            // delete succeeded, check failed conversation
        }
    }, new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            int code = error.getCode();
            String desc = error.getDesc();
            // delete failed, handle error
        }
    });
    
    iOS
    objective-c[NIMSDK.sharedSDK.v2ConversationService deleteConversationListByIds:@[@"conversationIdA", @"conversationIdB"] clearMessage:NO     success:^(NSArray<V2NIMConversationOperationResult *> *resultList) {
        if (resultList.count > 0) {
            // delete succeeded, check failed conversation
        }
    } failure:^(V2NIMError *error) {
        // handle error
    }];
    
    macOS/Windows
    cppauto conversationIds = nstd::vector<nstd::string>();
    conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account1"));
    conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account2"));
    conversationService.deleteConversationListByIds(
        conversationIds,
        true,
        [](nstd::vector<V2NIMConversationOperationResult> failedList) {
            // delete succeeded, check failed conversation
        },
        [](V2NIMError error) {
            // delete failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    const ids = ["CONVERSATION_ID1", "CONVERSATION_ID2"]
    await nim.V2NIMConversationService.deleteConversationListByIds(ids, true)
    // delete succeeded, check failed conversation
    } catch (err) {
    // delete failed, handle error
    }
    
    Harmony
    typescriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
    let clearMessage: boolean = true;
    try {
    let deleteFailedConversationList: V2NIMConversationOperationResult[] = await this.conversationService.deleteConversationListByIds(conversationIds, clearMessage)
    if (deleteFailedConversationList && deleteFailedConversationList.length > 0) {
        // partial success
    } else {
        // all success
    }
    } catch (e) {
    // fail
    }
    

消息未读数

获取消息未读数

获取全部会话消息总未读数

调用 getTotalUnreadCount 方法获取全部会话的消息总未读数。

如果数据同步已开始(收到 onSyncStarted 回调),建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作,否则可能无法获取到完整会话数据。

示例代码:

Android
javaint totalUnreadCount = NIMClient.getService(V2NIMConversationService.class).getTotalUnreadCount();
iOS
objective-cNSInteger count = [NIMSDK.sharedSDK.v2ConversationService getTotalUnreadCount];
macOS/Windows
cppauto totalUnreadCount = conversationService.getTotalUnreadCount();
Web/uni-app/小程序
typescriptconst count = nim.V2NIMConversationService.getTotalUnreadCount()
Harmony
typescriptconst unreadCount: number = this.conversationService.getTotalUnreadCount()

获取指定会话列表的消息总未读数

调用 getUnreadCountByIds 方法按照会话 ID 列表获取指定会话列表的消息总未读数。

如果数据同步已开始(收到 onSyncStarted 回调),建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作,否则可能无法获取到完整的会话数据。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    conversationIds List - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 获取成功回调,返回指定会话列表的总未读数。
    failure V2NIMFailureCallback - 获取失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    conversationIds NSArray - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMConversationUnreadCountCallback - 获取会话未读数成功回调,可自定 义。
    failure V2NIMFailureCallback - 获取失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    conversationIds String - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 获取成功回调,返回指定会话列表的总未读数。
    failure V2NIMFailureCallback - 获取失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    conversationIds String - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    Harmony
    参数名称 类型 是否必填 默认值 描述
    conversationIds String - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
  • 示例代码:

    Android
    javaNIMClient.getService(V2NIMConversationService.class).getUnreadCountByIds(ids, new V2NIMSuccessCallback<Integer>(){
        @Override
        public void onSuccess(Integer count){
            // receive unread count
        }
    },new V2NIMFailureCallback(){
        @Override
        public void onFailure(V2NIMError error){
            int code = error.getCode();
            String desc = error.getDesc();
            // handle error
        }
    });
    
    iOS
    objective-c[NIMSDK.sharedSDK.v2ConversationService getUnreadCountByIds:@[@"conversationIdA", @"conversationIdB"] success:^(NSInteger    unreadCount) {
        // receive unread count
    } failure:^(V2NIMError * _Nonnull error) {
        // handle error
    }];
    
    macOS/Windows
    cppauto conversationIds = nstd::vector<nstd::string>();
    conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account1"));
    conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account2"));
    conversationService.getUnreadCountByIds(
        conversationIds,
        [](uint32_t count) {
            // get unread count succeeded
        },
        [](V2NIMError error) {
            // get unread count failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    const counts = await nim.V2NIMConversationService.getUnreadCountByIds(["CONVERSATION_ID1", "CONVERSATION_ID2"]);    
    } catch (err) {
        // Handle error
    }
    
    Harmony
    typescriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
    try {
    const unreadCount: number = await this.conversationService.getUnreadCountByIds(conversationIds)
    // success
    } catch (e) {
    // fail
    }
    

获取过滤后的会话消息总未读数

调用 getUnreadCountByFilter 方法按照会话 ID 列表获取指定会话列表的消息总未读数。

如果数据同步已开始(收到 onSyncStarted 回调),建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作,否则可能无法获取到完整的会话数据。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    filter V2NIMConversationFilter - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。
    success V2NIMSuccessCallback - 获取成功回调,返回过滤后的会话列表的总未读数。
    failure V2NIMFailureCallback - 获取失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    filter V2NIMConversationFilter - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。
    success V2NIMConversationUnreadCountCallback - 获取会话未读数成功回调,可自定 义。
    failure V2NIMFailureCallback - 获取失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    filter V2NIMConversationFilter - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。
    success V2NIMSuccessCallback - 获取成功回调,返回过滤后的会话列表的总未读数。
    failure V2NIMFailureCallback - 获取失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    filter V2NIMConversationFilter - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。
    Harmony
    参数名称 类型 是否必填 默认值 描述
    filter V2NIMConversationFilter - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。
  • 示例代码:

    Android
    javaV2NIMConversationFilter filter = new V2NIMConversationFilter();
    List<V2NIMConversationType> conversionTypes = new ArrayList<>();
    conversionTypes.add(V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
    filter.setConversationTypes(conversionTypes);
    filter.setConversationGroupId("会话分组id");
    NIMClient.getService(V2NIMConversationService.class).getUnreadCountByFilter(filter, new V2NIMSuccessCallback<Integer>(){
        @Override
        public void onSuccess(Integer count){
            // receive unread count
        }
    },new V2NIMFailureCallback(){
        @Override
        public void onFailure(V2NIMError error){
            int code = error.getCode();
            String desc = error.getDesc();
            // handle error
        }
    });
    
    iOS
    objective-cV2NIMConversationFilter *filter = [[V2NIMConversationFilter alloc] init];
    filter.conversationTypes = @[
        @(V2NIM_CONVERSATION_TYPE_P2P),
        @(V2NIM_CONVERSATION_TYPE_TEAM)
    ];
    filter.conversationGroupId = @"groupId";
    filter.ignoreMuted = YES;
    
    [NIMSDK.sharedSDK.v2ConversationService getUnreadCountByFilter:filter
        success:^(NSInteger unreadCount) {
            // receive unread count
        }
        failure:^(V2NIMError * _Nonnull error) {
            // handle error
        }];
    
    macOS/Windows
    cppV2NIMConversationFilter filter;
    filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
    conversationService.getUnreadCountByFilter(
        filter,
        [](uint32_t count) {
            // get unread count succeeded
        },
        [](V2NIMError error) {
            // get unread count failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    // P2P type
    const filter = { conversationTypes: [1] }
    const counts = await nim.V2NIMConversationService.getUnreadCountByFilter(filter)
    // receive unread count
    } catch (err) {
    // handle error
    }
    
    Harmony
    typescriptlet filter: V2NIMConversationFilter = {
    conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
    }
    try {
    let unreadCount: number = await this.conversationService.getUnreadCountByFilter(filter)
    // success
    } catch (e) {
    // fail
    }
    

未读数清零

云信 IM 支持将会话内的消息未读数清零,即标记为已读。

将全部会话消息总未读数清零

调用 clearTotalUnreadCount 将应用内全部会话的消息总未读数清零。

清零成功后,SDK 返回 onTotalUnreadCountChangedonConversationChangedonUnreadCountChangedByFilter 回调,并同步数据库和缓存。

建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作。

  • 参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回错误码
    Web/uni-app/小程序

    无参数

    Harmony

    无参数

  • 示例代码:

    Android
    javaNIMClient.getService(V2NIMConversationService.class).clearTotalUnreadCount(new V2NIMSuccessCallback<Void>(){
        @Override
        public void onSuccess(Void unused) {
            // success
        }
    }, new V2NIMFailureCallback(){
        @Override
        public void onFailure(V2NIMError error){
            int code = error.getCode();
            String desc = error.getDesc();
            // handle error
        }
    });
    
    iOS
    objective-c[NIMSDK.sharedSDK.v2ConversationService clearTotalUnreadCount:^{
    
    } failure:^(V2NIMError * _Nonnull error) {
        // handle error
    }];
    
    macOS/Windows
    cppconversationService.clearTotalUnreadCount(
        []() {
            // clear total unread count succeeded
        },
        [](V2NIMError error) {
            // clear total unread count failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
    await nim.V2NIMConversationService.clearTotalUnreadCount()
    // Success
    } catch (err) {
    // handle error
    }
    
    Harmony
    typescripttry {
    await nim.V2NIMConversationService.clearTotalUnreadCount()
    // Success
    } catch (err) {
    // handle error
    }
    

将指定会话列表的消息未读数清零

调用 clearUnreadCountByIds 按照会话 ID 批量将指定会话列表的消息未读数清零。

清零成功后,SDK 返回清零失败的会话 ID 列表,并触发 onTotalUnreadCountChangedonConversationChangedonUnreadCountChangedByFilter 回调,同步数据库和缓存。

建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作。

  • 参数说明:
Android
参数名称 类型 是否必填 默认值 描述
conversationIds List - 会话 ID 列表。
  • 会话 ID 列表。不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
  • success V2NIMSuccessCallback - 清零成功回调,返回 List<V2NIMConversationOperationResult>,仅包含清零失败的会话 ID 及相关错误码。
    failure V2NIMFailureCallback - 清零失败回调,返回错误码
    iOS
    参数名称 类型 是否必填 默认值 描述
    conversationIds NSArray - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
  • success V2NIMConversationOperationResultListCallback - 清零成功回调,可自定义设置。
    failure V2NIMFailureCallback - 清零失败回调,返回错误码
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    conversationIds String - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
  • success V2NIMSuccessCallback - 清零成功回调,返回 V2NIMConversationOperationResult 列表,仅包含清零失败的会话 ID 及相关错误码。
    failure V2NIMFailureCallback - 清零失败回调,返回错误码
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    conversationIds String[] - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
  • Harmony
    参数名称 类型 是否必填 默认值 描述
    conversationIds String[] - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
    • 示例代码:
    Android
    javaNIMClient.getService(V2NIMConversationService.class).clearUnreadCountByIds(ids, new V2NIMSuccessCallback<List<V2NIMConversationOperationResult>>(){
        @Override
        public void onSuccess(List<V2NIMConversationOperationResult> results){
            // check failed conversation
        }
    }, new V2NIMFailureCallback(){
        @Override
        public void onFailure(V2NIMError error){
            int code = error.getCode();
            String desc = error.getDesc();
            // handle error
        }
    });
    
    iOS
    objective-c[NIMSDK.sharedSDK.v2ConversationService clearUnreadCountByIds:@[@"conversationIdA", @"conversationIdB"] success:^(NSArray<V2NIMConversationOperationResult *> *resultList) {
        if (resultList.count > 0) {
            // check failed conversation
        }
    } failure:^(V2NIMError * _Nonnull error) {
        // handle error
    }];
    
    macOS/Windows
    cppauto conversationIds = nstd::vector<nstd::string>();
    conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account1"));
    conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account2"));
    conversationService.clearUnreadCountByIds(
        conversationIds,
        [](nstd::vector<V2NIMConversationOperationResult> failedList) {
            // clear unread count succeeded
        },
        [](V2NIMError error) {
            // clear unread count failed, handle error
        });
    
    Web/uni-app/小程序
    typescripttry {
      await nim.V2NIMConversationService.clearUnreadCountByIds(["CONVERSATION_ID1", "CONVERSATION_ID2"])
      // Success
    } catch (err) {
      // handle error
    }
    
    Harmony
    typescriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
    try {
      const deleteFailedConversationList: V2NIMConversationOperationResult[] = await this.conversationService.clearUnreadCountByIds(conversationIds)
      if (deleteFailedConversationList && deleteFailedConversationList.length > 0) {
        // partial success
      } else {
        // all success
      }
    } catch (e) {
      // fail
    }
    

    将指定分组的会话消息未读数清零

    调用 clearUnreadCountByGroupId 按照会话分组 ID 将指定分组的会话消息未读数清零。

    清零成功后,SDK 返回 onTotalUnreadCountChangedonConversationChangedonUnreadCountChangedByFilter 回调,并同步数据库和缓存。

    建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作。

    • 参数说明:

      Android
      参数名称 类型 是否必填 默认值 描述
      groupId String - 会话分组 ID。通过调用 createConversationGroup 获得。不可为空,否则返回 191004 错误码。
      success V2NIMSuccessCallback - 清零成功回调
      failure V2NIMFailureCallback - 清零失败回调,返回错误码
      iOS
      参数名称 类型 是否必填 默认值 描述
      groupId String - 会话分组 ID。通过调用 createConversationGroup 获得。不可为空,否则返回 191004 错误码。
      success V2NIMSuccessCallback - 清零成功回调
      failure V2NIMFailureCallback - 清零失败回调,返回错误码
      macOS/Windows
      参数名称 类型 是否必填 默认值 描述
      groupId String - 会话分组 ID。通过调用 createConversationGroup 获得。不可为空,否则返回 191004 错误码。
      success V2NIMSuccessCallback - 清零成功回调
      failure V2NIMFailureCallback - 清零失败回调,返回错误码
      Web/uni-app/小程序
      参数名称 类型 是否必填 默认值 描述
      groupId String - 会话分组 ID。通过调用 createConversationGroup 获得。不可为空,否则返回 191004 错误码。
      Harmony
      参数名称 类型 是否必填 默认值 描述
      groupId String - 会话分组 ID。通过调用 createConversationGroup 获得。不可为空,否则返回 191004 错误码。
    • 示例代码:

      Android
      javaNIMClient.getService(V2NIMConversationService.class).clearUnreadCountByGroupId("会话分组id",new V2NIMSuccessCallback<Void>(){
          @Override
          public void onSuccess(Void unused) {
              // success
          }
      }, new V2NIMFailureCallback(){
          @Override
          public void onFailure(V2NIMError error){
              int code = error.getCode();
              String desc = error.getDesc();
              // handle error
          }
      });
      
      iOS
      objective-c[NIMSDK.sharedSDK.v2ConversationService clearUnreadCountByGroupId:@"groupId" success:^{
      
              } failure:^(V2NIMError * _Nonnull error) {
                  // handle error
              }];
      
      macOS/Windows
      cppconversationService.clearUnreadCountByGroupId(
          "groupId",
          []() {
              // clear unread count succeeded
          },
          [](V2NIMError error) {
              // clear unread count failed, handle error
          });
      
      Web/uni-app/小程序
      typescripttry {
      await nim.V2NIMConversationService.clearUnreadCountByGroupId('GROUP_ID')
      // Success
      } catch (err) {
      // handle error
      }
      
      Harmony
      typescriptlet groupId: string = "0123456789"
      try {
      await this.conversationService.clearUnreadCountByGroupId(groupId)
      // success
      } catch (e) {
      // fail
      }
      

    将指定类型的会话消息未读数清零

    调用 clearUnreadCountByTypes 方法按照会话类型批量将指定类型的会话消息未读数清零。

    清零成功后,SDK 返回 onTotalUnreadCountChangedonConversationChangedonUnreadCountChangedByFilter 回调,并同步数据库和缓存。

    建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作。

    • 参数说明:

      Android
      参数名称 类型 是否必填 默认值 描述
      conversationTypes List<V2NIMConversationType> - 会话类型
      success V2NIMSuccessCallback - 清零成功回调
      failure V2NIMFailureCallback - 清零失败回调,返回错误码
      iOS
      参数名称 类型 是否必填 默认值 描述
      conversationTypes NSArray<NSNumber *> * - 会话类型
      success V2NIMSuccessCallback - 清零成功回调
      failure V2NIMFailureCallback - 清零失败回调,返回错误码
      macOS/Windows
      参数名称 类型 是否必填 默认值 描述
      conversationTypes List<V2NIMConversationType> - 会话类型
      success V2NIMSuccessCallback - 清零成功回调
      failure V2NIMFailureCallback - 清零失败回调,返回错误码
      Web/uni-app/小程序
      参数名称 类型 是否必填 默认值 描述
      types V2NIMConversationType[] - 会话类型
      Harmony
      参数名称 类型 是否必填 默认值 描述
      types V2NIMConversationType[] - 会话类型
    • 示例代码:

      Android
      javaList<V2NIMConversationType> conversionTypes = new ArrayList<>();
      conversionTypes.add(V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
      NIMClient.getService(V2NIMConversationService.class).clearUnreadCountByTypes(conversionTypes,new V2NIMSuccessCallback<Void>(){
          @Override
          public void onSuccess(Void unused) {
              // success
          }
      }, new V2NIMFailureCallback(){
          @Override
          public void onFailure(V2NIMError error){
              int code = error.getCode();
              String desc = error.getDesc();
              // handle error
          }
      });
      
      iOS
      objective-c[NIMSDK.sharedSDK.v2ConversationService clearUnreadCountByTypes:@[
              @(V2NIM_CONVERSATION_TYPE_P2P),
              @(V2NIM_CONVERSATION_TYPE_TEAM),
          ] success:^{
              // success
          } failure:^(V2NIMError * _Nonnull error) {
              // handle error
          }];
      
      macOS/Windows
      cppconversationService.clearUnreadCountByTypes(
          {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM},
          []() {
              // clear unread count succeeded
          },
          [](V2NIMError error) {
              // clear unread count failed, handle error
          });
      
      Web/uni-app/小程序
      typescripttry {
      await nim.V2NIMConversationService.clearUnreadCountByTypes([1])
      // Success
      } catch (err) {
      // handle error
      }
      
      Harmony
      typescriptlet conversationTypes:V2NIMConversationType[] = [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
      try {
      await this.conversationService.clearUnreadCountByTypes(conversationTypes)
      // success
      } catch (e) {
      // fail
      }
      

    进阶功能

    会话置顶

    调用 stickTopConversation 方法按照会话 ID 将指定会话添加为置顶状态。最多支持置顶 100 条会话。

    置顶成功后,SDK 会返回会话变更回调 onConversationChanged,并同步数据库和缓存。

    • 使用会话置顶功能前,您需要已开通 IM 套餐包并在控制台应用管理 > 产品功能 > IM 即时通讯 > 全局功能开通会话指定功能。
    • 建议您在数据同步完成(收到 onSyncFinished 回调)后再进行该操作。
    • 参数说明:

      Android
      参数名称 类型 是否必填 默认值 描述
      conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
      stickTop Boolean - 是否置顶会话。
      success V2NIMSuccessCallback - 置顶会话成功回调
      failure V2NIMFailureCallback - 置顶会话失败回调,返回错误码
      iOS
      参数名称 类型 是否必填 默认值 描述
      conversationId NSString - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
      stickTop BOOL - 是否置顶会话。
      success V2NIMSuccessCallback - 置顶会话成功回调
      failure V2NIMFailureCallback - 置顶会话失败回调,返回错误码
      macOS/Windows
      参数名称 类型 是否必填 默认值 描述
      conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
      stickTop BOOL - 是否置顶会话。
      success V2NIMSuccessCallback - 置顶会话成功回调
      failure V2NIMFailureCallback - 置顶会话失败回调,返回错误码
      Web/uni-app/小程序
      参数名称 类型 是否必填 默认值 描述
      conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
      stickTop Boolean - 是否置顶会话。
      Harmony
      参数名称 类型 是否必填 默认值 描述
      conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
      stickTop Boolean - 是否置顶会话。
    • 示例代码:

      Android
      javaNIMClient.getService(V2NIMConversationService.class).stickTopConversation("会话id", true, new V2NIMSuccessCallback<Void>() {
              @Override
              public void onSuccess(Void unused) {
                  // success
              }
          }, new V2NIMFailureCallback() {
              @Override
              public void onFailure(V2NIMError error) {
                  int code = error.getCode();
                  String desc = error.getDesc();
                  // handle error
              }
          });
      
      iOS
      objective-c[NIMSDK.sharedSDK.v2ConversationService stickTopConversation:@"conversationId" stickTop:YES success:^{
          // success
      } failure:^(V2NIMError *error) {
          // handle error
      }];
      
      macOS/Windows
      cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
      conversationService.stickTopConversation(
          conversationId,
          true,
          []() {
              // stick top succeeded
          },
          [](V2NIMError error) {
              // stick top failed, handle error
          });
      
      Web/uni-app/小程序
      typescripttry {
      await nim.V2NIMConversationService.stickTopConversation("CONVERSATION_ID", true)
      // Success
      } catch (err) {
      // handle error
      }
      
      Harmony
      typescriptlet conversationId: string = "cjl|1|cjl1"
      let stickTop: boolean = true;
      try {
      await this.conversationService.stickTopConversation(conversationId, stickTop)
      // success
      } catch (e) {
      // fail
      }
      

    相关信息

    此文档是否对你有帮助?
    有帮助
    去反馈
    • 技术原理
    • 前提条件
    • 监听会话相关事件
    • 创建会话
    • 获取会话
    • 分页获取所有会话列表
    • 获取指定单条会话
    • 根据查询选项分页获取会话列表
    • 批量获取指定的会话列表
    • 更新会话扩展字段
    • 删除会话
    • 删除指定单条会话
    • 批量删除指定会话列表
    • 消息未读数
    • 获取消息未读数
    • 获取全部会话消息总未读数
    • 获取指定会话列表的消息总未读数
    • 获取过滤后的会话消息总未读数
    • 未读数清零
    • 将全部会话消息总未读数清零
    • 将指定会话列表的消息未读数清零
    • 将指定分组的会话消息未读数清零
    • 将指定类型的会话消息未读数清零
    • 进阶功能
    • 会话置顶
    • 相关信息