会话

更新时间: 2024/07/09 10:08:39

网易云信即时通讯 SDK(简称 NIM SDK)支持用户会话管理功能,包括创建、更新、删除会话等基础操作,以及置顶会话等进阶操作。

如何实现会话相关功能请参考 会话管理。本文介绍 NIM SDK 会话相关 API。

支持平台

Android iOS macOS/Windows Web/uni-app/小程序 HarmonyOS
✔️ ✔️ ✔️ ✔️ ✔️

API 概览

会话监听

Android/iOS/macOS/Windows
API 说明 起始版本
addConversationListener 注册会话相关监听器 v10.2.0
removeConversationListener 移除会话相关监听器 v10.2.0
Web/uni-app/小程序/HarmonyOS
API 说明 起始版本
on("EventName") 注册会话相关监听 v10.2.0(对应 HarmonyOS v0.5.0)
off("EventName") 取消注册会话相关监听 v10.2.0(对应 HarmonyOS v0.5.0)

会话操作

API 说明 起始版本
createConversation 创建一条空会话 v10.2.0(对应 HarmonyOS v0.5.0)
deleteConversation 删除一条会话 v10.2.0(对应 HarmonyOS v0.5.0)
deleteConversationListByIds 批量删除会话列表 v10.2.0(对应 HarmonyOS v0.5.0)
getConversation 获取单条会话 v10.2.0(对应 HarmonyOS v0.5.0)
getConversationList 获取会话列表 v10.2.0(对应 HarmonyOS v0.5.0)
getConversationListByOption 获取指定会话列表 v10.2.0(对应 HarmonyOS v0.5.0)
getConversationListByIds 根据会话 ID 批量获取会话列表 v10.2.0(对应 HarmonyOS v0.5.0)
updateConversation 更新会话服务端扩展字段 v10.2.0(对应 HarmonyOS v0.5.0)
updateConversationLocalExtension 更新会话本地扩展字段 v10.2.0(对应 HarmonyOS v0.5.0)
stickTopConversation 置顶会话 v10.2.0(对应 HarmonyOS v0.5.0)

会话未读数

API 说明 起始版本
getTotalUnreadCount 获取全部会话的消息总未读数 v10.2.0(对应 HarmonyOS v0.5.0)
getUnreadCountByIds 获取指定会话列表的消息总未读数 v10.2.0(对应 HarmonyOS v0.5.0)
getUnreadCountByFilter 根据过滤参数获取相应的消息未读数 v10.2.0(对应 HarmonyOS v0.5.0)
clearTotalUnreadCount 清空所有会话总的未读数 v10.2.0(对应 HarmonyOS v0.5.0)
clearUnreadCountByIds 清空指定会话列表的消息总未读数 v10.2.0(对应 HarmonyOS v0.5.0)
clearUnreadCountByFilter 清除过滤后的会话消息未读 v10.2.0(对应 HarmonyOS v0.5.0)
subscribeUnreadCountByFilter 订阅过滤后的会话未读数变化 v10.2.0(对应 HarmonyOS v0.5.0)
unsubscribeUnreadCountByFilter 取消订阅过滤后的会话未读数变化 v10.2.0(对应 HarmonyOS v0.5.0)
markConversationRead 标记会话已读时间戳 v10.3.0
getConversationReadTime 获取会话已读时间戳 v10.3.0

接口类

V2NIMConversationService 类提供创建、删除、更新、获取会话,会话未读数、置顶会话、注册会话监听等接口。

addConversationListener

接口描述

注册会话监听器。

注册成功后,当事件发生时,SDK 会返回对应的回调。

  • 建议在初始化后调用该方法。

  • 全局只需注册一次。

参数说明

Android
Javavoid addConversationListener(@NonNull V2NIMConversationListener listener);
参数名称 类型 是否必填 默认值 说明
listener V2NIMConversationListener - 会话相关监听器
iOS
Objective-C- (void)addConversationListener:(id<V2NIMConversationListener>)listener;
参数名称 类型 是否必填 默认值 说明
listener V2NIMConversationListener - 会话相关监听器
macOS/Windows
C++virtual void addConversationListener(V2NIMConversationListener listener) = 0;
参数名称 类型 是否必填 默认值 说明
listener V2NIMConversationListener - 会话相关监听器

示例代码

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
    }

    @Override
    public void onConversationReadTimeUpdated(String conversationId, long readTime){
        // 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)onConversationReadTimeUpdated:(NSString *)conversationId
                             readTime:(NSTimeInterval)readTime
{
    // ReadTime changed
}                            
    
- (void)addConversationListener
{
    [NIMSDK.sharedSDK.v2ConversationService addConversationListener:self];
}

@end
macOS/Windows
C++V2NIMConversationListener 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
};
listener.onConversationReadTimeUpdated = [](nstd::string& conversationId, time_t readTime) {
    // handle ReadTime changed by group event
};
conversationService.addConversationListener(listener);

返回值

removeConversationListener

接口描述

移除会话监听器。

参数说明

Android
Javavoid removeConversationListener(@NonNull V2NIMConversationListener listener);
参数名称 类型 是否必填 默认值 说明
listener V2NIMConversationListener - 会话相关监听器
iOS
Objective-C- (void)removeConversationListener:(id<V2NIMConversationListener>)listener;
参数名称 类型 是否必填 默认值 说明
listener V2NIMConversationListener - 会话相关监听器
macOS/Windows
C++virtual void removeConversationListener(V2NIMConversationListener listener) = 0;
参数名称 类型 是否必填 默认值 说明
listener V2NIMConversationListener - 会话相关监听器

示例代码

Android
JavaNIMClient.getV2NIMConversationServcie().removeConversationListener(listener);
iOS
Objective-Cid<V2NIMConversationListener> listener;
[NIMSDK.sharedSDK.v2ConversationService removeConversationListener:listener];
macOS/Windows
C++V2NIMConversationListener listener;
conversationService.removeConversationListener(listener);

返回值

on("EventName")

接口描述

注册会话相关监听。

注册成功后,当事件发生时,SDK 会触发相关回调通知。

  • 建议在初始化后调用该方法。
  • 全局只需注册一次。
  • 该接口为同步。

参数说明

Web/uni-app/小程序
TypeScriptexport interface NIMEBaseServiceInterface<I extends NIMEBaseListener> {
  /**
   * 继承自 EventEmitter3 的监听事件方法。
   */
  on<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void;
  /**
   * 继承自 EventEmitter3 的监听事件方法。
   */
  once<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void;
}
参数名称 类型 是否必填 默认值 说明
eventName T - 事件名称:
  • onSyncStarted:数据同步开始回调
  • onSyncFinished:数据同步结束回调
  • onSyncFailed:数据同步失败回调,返回 相关错误码
  • onConversationCreated:会话创建回调,返回创建的会话对象。
  • onConversationDeleted:会话删除回调,返回被删除的会话 ID 列表。
  • onConversationChanged:会话变更回调,返回变更后的会话列表。
  • onTotalUnreadCountChanged:会话消息总未读数变更,返回变更后的总未读数。
  • onUnreadCountChangedByFilter:指定过滤条件的会话消息未读数变更,根据过滤条件返回变更后的未读数。
  • onConversationReadTimeUpdated:同一账号多端登录后的会话已读时间戳标记的回调。
  • fn function - 监听事件的回调函数。当事件触发时,会调用该函数进行处理。
    HarmonyOS
    TypeScriptexport interface NIMEBaseServiceInterface<I extends NIMEBaseListener> {
      /**
       * 继承自 eventEmitter3 的监听事件方法
       */
      on<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void
      /**
       * 继承自 eventEmitter3 的监听事件方法
       */
      once<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void
    }
    
    参数名称 类型 是否必填 默认值 说明
    eventName T - 事件名称:
  • onSyncStarted:数据同步开始回调
  • onSyncFinished:数据同步结束回调
  • onSyncFailed:数据同步失败回调,返回 相关错误码
  • onConversationCreated:会话创建回调,返回创建的会话对象。
  • onConversationDeleted:会话删除回调,返回被删除的会话 ID 列表。
  • onConversationChanged:会话变更回调,返回变更后的会话列表。
  • onTotalUnreadCountChanged:会话消息总未读数变更,返回变更后的总未读数。
  • onUnreadCountChangedByFilter:指定过滤条件的会话消息未读数变更,根据过滤条件返回变更后的未读数。
  • fn function - 监听事件的回调函数。当事件触发时,会调用该函数进行处理。

    示例代码

    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)
    })
    
    HarmonyOS
    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")

    接口描述

    取消注册会话相关监听。

    该接口为同步。

    参数说明

    Web/uni-app/小程序
    TypeScriptexport interface NIMEBaseServiceInterface<I extends NIMEBaseListener> {
      /**
       * 继承自 EventEmitter3 的取消监听方法。
       */
      off<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void;
      /**
       * 继承自 EventEmitter3 的移除事件方法。
       */
      removeAllListeners<T extends keyof I>(eventName?: T): void;
    }
    
    参数名称 类型 是否必填 默认值 说明
    eventName T - 事件名称:
  • onSyncStarted:数据同步开始回调
  • onSyncFinished:数据同步结束回调。如果数据同步已开始,建议在数据同步完成后再进行会话相关操作。
  • onSyncFailed:数据同步失败回调,返回相关错误码
  • onConversationCreated:会话创建回调,返回创建的会话对象。当本地端或多端同步创建会话成功时会触发该回调。
  • onConversationDeleted:会话删除回调,返回被删除的会话 ID 列表。当本地端或多端同步删除会话成功时会触发该回调。
  • onConversationChanged:会话变更回调,返回变更后的会话列表。当本地端或多端同步更新会话成功时会触发该回调。
  • onTotalUnreadCountChanged:会话消息总未读数变更,返回变更后的总未读数。
  • onUnreadCountChangedByFilter:指定过滤条件的会话消息未读数变更,根据过滤条件返回变更后的未读数。
  • fn function - 监听事件的回调函数。当事件触发时,会调用该函数进行处理。
    HarmonyOS
    TypeScriptexport interface NIMEBaseServiceInterface<I extends NIMEBaseListener> {
      /**
       * 继承自 EventEmitter3 的取消监听方法。
       */
      off<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void
      /**
       * 继承自 eventEmitter3 的移除事件方法
       */
      removeAllListeners<T extends keyof I>(eventName?: T): void
    }
    
    参数名称 类型 是否必填 默认值 说明
    eventName T - 事件名称:
  • onSyncStarted:数据同步开始回调
  • onSyncFinished:数据同步结束回调。如果数据同步已开始,建议在数据同步完成后再进行会话相关操作。
  • onSyncFailed:数据同步失败回调,返回相关错误码
  • onConversationCreated:会话创建回调,返回创建的会话对象。当本地端或多端同步创建会话成功时会触发该回调。
  • onConversationDeleted:会话删除回调,返回被删除的会话 ID 列表。当本地端或多端同步删除会话成功时会触发该回调。
  • onConversationChanged:会话变更回调,返回变更后的会话列表。当本地端或多端同步更新会话成功时会触发该回调。
  • onTotalUnreadCountChanged:会话消息总未读数变更,返回变更后的总未读数。
  • onUnreadCountChangedByFilter:指定过滤条件的会话消息未读数变更,根据过滤条件返回变更后的未读数。
  • fn function - 监听事件的回调函数。当事件触发时,会调用该函数进行处理。

    示例代码

    Web/uni-app/小程序
    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")
    
    HarmonyOS
    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()
    

    返回值

    createConversation

    接口描述

    创建一条空会话。

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

    如果没有消息收发,该会话仅创建人可见。

    使用场景

    当需要本地占位空会话时可以调用该方法,一般情况下无需主动调用,收发消息时 SDK 会自动创建会话。

    参数说明

    Android
    Javavoid createConversation(@NonNull String conversationId, V2NIMSuccessCallback<V2NIMConversation> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
  • 组成方式:用户账号(accountId)| 会话类型(V2NIMConversationType)| 聊天对象账号(accountId)或群组 ID。
  • 不可设置为空,否则返回 191004 参数错误。
  • success V2NIMSuccessCallback - 创建会话成功回调,返回 V2NIMConversation
    failure V2NIMFailureCallback - 创建会话失败回调,返回 错误码
    iOS
    Objective-C- (void)createConversation:(NSString *)conversationId
                       success:(nullable V2NIMConversationCallback)success
                       failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
  • 组成方式:用户账号(account)| 会话类型(V2NIMConversationType)| 聊天对象账号(account)或群组 ID。
  • 不可设置为空,否则返回 191004 参数错误。
  • success V2NIMConversationCallback - 创建会话成功回调,可自定义。
    failure V2NIMFailureCallback - 创建会话失败回调,返回 错误码
    macOS/Windows
    C++virtual void createConversation(nstd::string conversationId, V2NIMSuccessCallback<V2NIMConversation> success, V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
  • 组成方式:用户账号(accountId)| 会话类型(V2NIMConversationType)| 聊天对象账号(accountId)或群组 ID。
  • 不可设置为空,否则返回 191004 参数错误。
  • success V2NIMSuccessCallback - 创建会话成功回调,返回 [V2NIMConversation]((https://doc.yunxin.163.com/messaging2/client-apis/DAxNjk0Mzc?platform=client#V2NIMConversation)。
    failure V2NIMFailureCallback - 创建会话失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptcreateConversation(conversationId: string): Promise<V2NIMConversation>
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
  • 组成方式:用户账号(accountId)| 会话类型(V2NIMConversationType)| 聊天对象账号(accountId)或群组 ID。
  • 不可设置为空,否则返回 191004 参数错误。
  • HarmonyOS
    TypeScriptcreateConversation(conversationId: string): Promise<V2NIMConversation>
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
  • 组成方式:用户账号(accountId)| 会话类型(V2NIMConversationType)| 聊天对象账号(accountId)或群组 ID。
  • 不可设置为空,否则返回 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
    C++auto 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
    }
    
    HarmonyOS
    TypeScriptlet conversationId: string = "cjl|1|cjl1";
    try {
      let conv: V2NIMConversation = await this.conversationService.createConversation(conversationId)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<V2NIMConversation> 会话相关信息

    相关回调

    Android/iOS/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调。创建成功,返回 onConversationCreated 回调。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    iOS
    • 请求成功,返回 V2NIMConversationCallback 回调,可自定义设置。创建成功,返回 onConversationCreated 回调。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    创建成功,返回 onConversationCreated 回调。

    deleteConversation

    接口描述

    删除指定会话。

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

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

    参数说明

    Android
    Javavoid deleteConversation(@NonNull String conversationId, boolean clearMessage, V2NIMSuccessCallback<Void> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    clearMessage Boolean false 是否同步删除会话中本地和服务端的历史消息
  • 删除本地和服务端的历史消息。
  • 只删除会话,保留历史消息。
  • success V2NIMSuccessCallback - 删除会话成功回调
    failure V2NIMFailureCallback - 删除会话失败回调,返回 错误码
    iOS
    Objective-C- (void)deleteConversation:(NSString *)conversationId
                  clearMessage:(BOOL)clearMessage
                       success:(nullable V2NIMSuccessCallback)success
                       failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    clearMessage Bool false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保留历史消息。
  • success V2NIMSuccessCallback - 删除会话成功回调
    failure V2NIMFailureCallback - 删除会话失败回调,返回 错误码
    macOS/Windows
    C++virtual void deleteConversation(nstd::string conversationId,
        bool clearMessage,
        V2NIMSuccessCallback<void> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    clearMessage Bool false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保留历史消息。
  • success V2NIMSuccessCallback - 删除会话成功回调
    failure V2NIMFailureCallback - 删除会话失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptdeleteConversation(conversationId: string, clearMessage?: boolean): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    clearMessage Boolean false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保留历史消息。
  • HarmonyOS
    TypeScriptdeleteConversation(conversationId: string, clearMessage?: boolean): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++auto 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
    }
    
    HarmonyOS
    TypeScriptlet conversationId: string = "cjl|1|cjl1";
    let clearMessage: boolean = true;
    try {
      await this.conversationService.deleteConversation(conversationId, clearMessage)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<void>

    相关回调

    Android/iOS/macOS/Windows
    Web/uni-app/小程序/HarmonyOS

    删除成功,返回 onConversationDeleted 回调。可能返回 onTotalUnreadCountChangedonUnreadCountChangedByFilter 回调。

    deleteConversationListByIds

    接口描述

    批量删除指定的会话列表。

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

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

    参数说明

    Android
    Javavoid deleteConversationListByIds(@NonNull List<String> conversationIds, boolean clearMessage, V2NIMSuccessCallback<List<V2NIMConversationOperationResult>> success,
            V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds List - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 100 条。
  • clearMessage Boolean false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保留历史消息。
  • success V2NIMSuccessCallback - 删除会话成功回调,返回 V2NIMConversationOperationResult,仅包含删除失败的会话 ID 及相关错误
    failure V2NIMFailureCallback - 删除会话失败回调,返回 错误码
    iOS
    Objective-C- (void)deleteConversationListByIds:(NSArray<NSString *> *)conversationIds
                           clearMessage:(BOOL)clearMessage
                                success:(nullable V2NIMConversationOperationResultListCallback)success
                                failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds NSArray - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 100 条。
  • clearMessage Bool false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保留历史消息。
  • success V2NIMConversationOperationResultListCallback - 删除会话成功回调,可自定义设置。
    failure V2NIMFailureCallback - 删除会话失败回调,返回 错误码
    macOS/Windows
    C++virtual void deleteConversationListByIds(nstd::vector<nstd::string> conversationIds,
        bool clearMessage,
        V2NIMSuccessCallback<nstd::vector<V2NIMConversationOperationResult>> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds String - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 100 条。
  • clearMessage Bool false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保留历史消息。
  • success V2NIMSuccessCallback - 删除会话成功回调,返回 V2NIMConversationOperationResult,仅包含删除失败的会话 ID 及相关错误码。
    failure V2NIMFailureCallback - 删除会话失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptdeleteConversationListByIds(conversationIds: string[], clearMessage?: boolean): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds String[] - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 100 条。
  • clearMessage Boolean false 是否同步删除会话对应的历史消息
  • 删除历史消息。
  • 只删除会话,保留历史消息。
  • HarmonyOS
    TypeScriptdeleteConversationListByIds(conversationIds: string[], clearMessage?: boolean): Promise<V2NIMConversationOperationResult[]>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++auto 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
    }
    
    HarmonyOS
    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
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<void>

    相关回调

    Android/macOS/Windows
    iOS
    Web/uni-app/小程序/HarmonyOS

    每一条会话删除成功,均返回 onConversationDeleted 回调。可能返回 onTotalUnreadCountChangedonUnreadCountChangedByFilter 回调。

    getConversation

    接口描述

    查询单条指定会话。

    • 查询前请确保指定的会话存在。
    • 数据同步完成前,可能查询不到完整数据。

    参数说明

    Android
    Javavoid getConversation(@NonNull String conversationId, V2NIMSuccessCallback<V2NIMConversation> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversation
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    iOS
    Objective-C- (void)getConversation:(NSString *)conversationId
                    success:(nullable V2NIMConversationCallback)success
                    failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId NSString - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMConversationCallback - 查询会话成功回调,可自定义。
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    macOS/Windows
    C++virtual void getConversation(nstd::string conversationId, V2NIMSuccessCallback<V2NIMConversation> success, V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversation
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码 查询失败回调,返回错误码
    Web/uni-app/小程序
    TypeScriptgetConversation(conversationId: string): Promise<V2NIMConversation>
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    HarmonyOS
    TypeScriptgetConversation(conversationId: string): Promise<V2NIMConversation>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++auto 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
    }
    
    HarmonyOS
    TypeScriptlet conversationId: string = "cjl|1|cjl1";
    try {
      let conv: V2NIMConversation = await this.conversationService.getConversation(conversationId)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<V2NIMConversation> 会话相关信息

    相关回调

    Android/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调,包含 V2NIMConversation
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    iOS
    • 请求成功,返回 V2NIMConversationCallback 回调,可自定义设置。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    getConversationList

    接口描述

    分页查询所有会话列表。

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

    • 查询的会话列表结果中,置顶会话排首位。
    • 数据同步完成前,可能查询不到完整数据。

    参数说明

    Android
    Javavoid getConversationList(long offset, int limit, V2NIMSuccessCallback<V2NIMConversationResult> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    offset Long - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit Int - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversationResult
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    iOS
    Objective-C- (void)getConversationList:(long long)offset
                        limit:(NSInteger)limit
                        success:(nullable V2NIMConversationResultCallback)success
                        failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    offset Long - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit NSInteger - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。
    success V2NIMConversationResultCallback - 查询会话列表成功回调,可自定义。
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    macOS/Windows
    C++virtual void getConversationList(uint64_t offset,
        uint32_t limit,
        V2NIMSuccessCallback<V2NIMConversationResult> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    offset uint64_t - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit uint32_t - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversationResult
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptgetConversationList(offset: number, limit: number): Promise<V2NIMConversationResult>
    
    参数名称 类型 是否必填 默认值 说明
    offset Number - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit Number - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。
    HarmonyOS
    TypeScriptgetConversationList(offset: number, limit: number): Promise<V2NIMConversationResult>
    
    参数名称 类型 是否必填 默认值 说明
    offset Number - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit Number - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。

    示例代码

    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
    C++conversationService.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
    }
    
    HarmonyOS
    TypeScripttry {
      const result = await nim.conversationService.getConversationList(0, 100)
      // success
    } catch (err) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<V2NIMConversationResult> 分页查询会话列表结果相关信息

    相关回调

    Android/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调,包含 V2NIMConversationResult
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    iOS
    • 请求成功,返回 V2NIMConversationResultCallback 回调,可自定义设置。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    getConversationListByOption

    接口描述

    根据指定条件分页查询会话列表。

    该方法根据指定条件从客户端本地分页获取会话数据,直到获取全量会话,SDK 会进行数据同步并返回对应回调通知 UI 层。

    数据同步完成前,可能查询不到完整数据。

    参数说明

    Android
    Javavoid getConversationListByOption(long offset, int limit, V2NIMConversationOption option, V2NIMSuccessCallback<V2NIMConversationResult> success,
    V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    offset Long - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit Int - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。
    option V2NIMConversationOption - 查询条件,设置为空则查询所有会话列表。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversationResult
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    iOS
    Objective-C- (void)getConversationListByOption:(long long)offset
                                limit:(NSInteger)limit
                                option:(V2NIMConversationOption *)option
                                success:(nullable V2NIMConversationResultCallback)success
                                failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    offset Long - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit NSInteger - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。
    option V2NIMConversationOption - 查询条件,设置为空则查询所有会话列表。
    success V2NIMConversationResultCallback - 查询会话列表成功回调,可自定义。
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    macOS/Windows
    C++virtual void getConversationListByOption(uint64_t offset,
        uint32_t limit,
        V2NIMConversationOption option,
        V2NIMSuccessCallback<V2NIMConversationResult> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    offset uint64_t - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit uint32_t - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。
    option V2NIMConversationOption - 查询条件,设置为空则查询所有会话列表。
    success V2NIMSuccessCallback - 查询成功回调,返回 V2NIMConversationResult
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptgetConversationListByOption(offset: number, limit: number, option: V2NIMConversationOption): Promise<V2NIMConversationResult>
    
    参数名称 类型 是否必填 默认值 说明
    offset Number - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit Number - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。
    option V2NIMConversationOption - 查询条件,设置为空则查询所有会话列表。
    HarmonyOS
    TypeScriptgetConversationListByOption(offset: number, limit: number, option: V2NIMConversationOption): Promise<V2NIMConversationResult>
    
    参数名称 类型 是否必填 默认值 说明
    offset Number - 分页偏移。首次调用传 0,后续调用时传入上一次调用返回的 offset
    limit Number - 单次查询会话数量上限,建议不超过 100。设置为小于或等于 0 则默认为 100。
    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
    C++V2NIMConversationOption 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
    }
    
    HarmonyOS
    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
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<V2NIMConversationResult> 分页查询会话列表结果相关信息

    相关回调

    Android/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调,包含 V2NIMConversationResult
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    iOS
    • 请求成功,返回 V2NIMConversationResultCallback 回调,可自定义设置。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    getConversationListByIds

    接口描述

    批量查询指定的会话列表。

    数据同步完成前,可能查询不到完整数据。

    参数说明

    Android
    Javavoid getConversationListByIds(@NonNull List<String> conversationIds, V2NIMSuccessCallback<List<V2NIMConversation>> success,
    V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds List - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询成功回调,返回 List<V2NIMConversation>。
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    iOS
    Objective-C- (void)getConversationListByIds:(NSString *)conversationIds
                             success:(nullable V2NIMConversationListCallback)success
                             failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds NSString - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMConversationListCallback - 查询成功回调,可自定义。
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    macOS/Windows
    C++virtual void getConversationListByIds(nstd::vector<nstd::string> conversationIds,
        V2NIMSuccessCallback<V2NIMConversationList> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds String - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询会话列表成功回调,返回 List<V2NIMConversation>。
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptgetConversationListByIds(conversationIds: string[]): Promise<V2NIMConversation[]>
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds string[] - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    HarmonyOS
    TypeScriptgetConversationListByIds(conversationIds: string[]): Promise<V2NIMConversation[]>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++auto 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
    }
    
    HarmonyOS
    TypeScriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
    try {
      let result: V2NIMConversation[] = await this.conversationService.getConversationListByIds(conversationIds)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<V2NIMConversation[]> 会话列表相关信息

    相关回调

    Android/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调,包含 V2NIMConversation 列表。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    iOS
    • 请求成功,返回 V2NIMConversationListCallback 回调,可自定义设置。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    updateConversation

    接口描述

    更新指定会话的服务端扩展字段。

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

    更新前请确保该会话已存在。

    参数说明

    Android
    Javavoid updateConversation(@NonNull String conversationId, V2NIMConversationUpdate updateInfo, V2NIMSuccessCallback<Void> success,
    V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,可以更新服务端扩展字段,会多端同步
    success V2NIMSuccessCallback - 更新会话成功回调
    failure V2NIMFailureCallback - 更新会话失败回调,返回 错误码
    iOS
    Objective-C- (void)updateConversation:(NSString *)conversationId
                    updateInfo:(V2NIMConversationUpdate *)updateInfo
                       success:(nullable V2NIMSuccessCallback)success
                       failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,可以更新服务端扩展字段,会多端同步
    success V2NIMSuccessCallback - 更新会话成功回调
    failure V2NIMFailureCallback - 更新会话失败回调,返回 错误码
    macOS/Windows
    C++virtual void updateConversation(nstd::string conversationId,
        V2NIMConversationUpdate updateInfo,
        V2NIMSuccessCallback<void> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,可以更新服务端扩展字段,会多端同步
    success V2NIMSuccessCallback - 更新会话成功回调
    failure V2NIMFailureCallback - 更新会话失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptupdateConversation(conversationId: string, updateInfo: V2NIMConversationUpdate): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,可以更新服务端扩展字段,会多端同步
    HarmonyOS
    TypeScriptupdateConversation(conversationId: string, updateInfo: V2NIMConversationUpdate): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++auto 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
    }
    
    HarmonyOS
    TypeScriptlet conversationId: string = "cjl|1|cjl1"
    let userInfo: V2NIMConversationUpdate = {
      serverExtension: "serverExtension"
    }
    try {
      await this.conversationService.updateConversation(conversationId, userInfo)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<void>

    相关回调

    Android/iOS/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调。更新成功,返回 onConversationChanged 回调。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    更新成功,返回 onConversationChanged 回调。

    updateConversationLocalExtension

    接口描述

    更新指定会话的本地扩展字段。

    本地扩展字段更新后,SDK 会返回会话变更回调 onConversationChanged

    本地扩展字段不会多端同步,web 端仅存内存。

    更新前请确保该会话已存在。

    参数说明

    Android
    Javavoid updateConversation(@NonNull String conversationId, V2NIMConversationUpdate updateInfo, V2NIMSuccessCallback<Void> success,
    V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,可以更新服务端扩展字段,会多端同步
    success V2NIMSuccessCallback - 更新会话成功回调
    failure V2NIMFailureCallback - 更新会话失败回调,返回 错误码
    iOS
    Objective-C- (void)updateConversation:(NSString *)conversationId
                    updateInfo:(V2NIMConversationUpdate *)updateInfo
                       success:(nullable V2NIMSuccessCallback)success
                       failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,可以更新服务端扩展字段,会多端同步
    success V2NIMSuccessCallback - 更新会话成功回调
    failure V2NIMFailureCallback - 更新会话失败回调,返回 错误码
    macOS/Windows
    C++virtual void updateConversation(nstd::string conversationId,
        V2NIMConversationUpdate updateInfo,
        V2NIMSuccessCallback<void> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,可以更新服务端扩展字段,会多端同步
    success V2NIMSuccessCallback - 更新会话成功回调
    failure V2NIMFailureCallback - 更新会话失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptupdateConversation(conversationId: string, updateInfo: V2NIMConversationUpdate): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    updateInfo V2NIMConversationUpdate - 会话更新对象,可以更新服务端扩展字段,会多端同步
    HarmonyOS
    TypeScriptupdateConversation(conversationId: string, updateInfo: V2NIMConversationUpdate): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++auto 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
    }
    
    HarmonyOS
    TypeScriptlet conversationId: string = "cjl|1|cjl1"
    let userInfo: V2NIMConversationUpdate = {
      serverExtension: "serverExtension"
    }
    try {
      await this.conversationService.updateConversation(conversationId, userInfo)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<void>

    相关回调

    Android/iOS/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调。更新成功,返回 onConversationChanged 回调。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    更新成功,返回 onConversationChanged 回调。

    stickTopConversation

    接口描述

    将会话置顶。最多支持置顶 100 条会话。

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

    置顶前请确保该会话已存在。

    参数说明

    Android
    Javavoid stickTopConversation(@NonNull String conversationId, boolean stickTop, V2NIMSuccessCallback<Void> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    stickTop Boolean - 是否置顶会话。
    success V2NIMSuccessCallback - 置顶会话成功回调
    failure V2NIMFailureCallback - 置顶会话失败回调,返回 错误码
    iOS
    Objective-C- (void)stickTopConversation:(NSString *)conversationId
                        stickTop:(BOOL)stickTop
                         success:(nullable V2NIMSuccessCallback)success
                         failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId NSString - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    stickTop BOOL - 是否置顶会话。
    success V2NIMSuccessCallback - 置顶会话成功回调
    failure V2NIMFailureCallback - 置顶会话失败回调,返回 错误码
    macOS/Windows
    C++virtual void stickTopConversation(nstd::string conversationId,
        bool stickTop,
        V2NIMSuccessCallback<void> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    stickTop BOOL - 是否置顶会话。
    success V2NIMSuccessCallback - 置顶会话成功回调
    failure V2NIMFailureCallback - 置顶会话失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptstickTopConversation(conversationId: string, stickTop: boolean): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    stickTop Boolean - 是否置顶会话。
    HarmonyOS
    TypeScriptstickTopConversation(conversationId: string, stickTop: boolean): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++auto 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
    }
    
    HarmonyOS
    TypeScriptlet conversationId: string = "cjl|1|cjl1"
    let stickTop: boolean = true;
    try {
      await this.conversationService.stickTopConversation(conversationId, stickTop)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<void>

    相关回调

    Android/iOS/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调。置顶成功,返回 onConversationChanged 回调。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    置顶成功,返回 onConversationChanged 回调。

    getTotalUnreadCount

    接口描述

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

    • 数据同步完成前,可能查询不到完整数据。
    • 该接口为同步。

    参数说明

    Android
    Javaint getTotalUnreadCount();
    

    无参数

    iOS
    Objective-C- (NSInteger)getTotalUnreadCount;
    

    无参数

    macOS/Windows
    C++virtual uint32_t getTotalUnreadCount() = 0;
    

    无参数

    Web/uni-app/小程序
    TypeScriptgetTotalUnreadCount(): number
    

    无参数

    HarmonyOS
    TypeScriptgetTotalUnreadCount(): number
    

    无参数

    示例代码

    Android
    Javaint totalUnreadCount = NIMClient.getService(V2NIMConversationService.class).getTotalUnreadCount();
    
    iOS
    Objective-CNSInteger count = [NIMSDK.sharedSDK.v2ConversationService getTotalUnreadCount];
    
    macOS/Windows
    C++auto totalUnreadCount = conversationService.getTotalUnreadCount();
    
    Web/uni-app/小程序
    TypeScriptconst count = nim.V2NIMConversationService.getTotalUnreadCount()
    
    HarmonyOS
    TypeScriptconst unreadCount: number = this.conversationService.getTotalUnreadCount()
    

    返回值

    全部会话的消息总未读数

    getUnreadCountByIds

    接口描述

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

    • 查询前请确保指定的会话已存在。
    • 数据同步完成前,可能查询不到完整数据。

    参数说明

    Android
    Javavoid getUnreadCountByIds(@NonNull List<String> conversationIds, V2NIMSuccessCallback<Integer> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds List<String> - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 获取成功回调,返回指定会话列表的总未读数。
    failure V2NIMFailureCallback - 获取失败回调,返回 错误码
    iOS
    Objective-C- (void)getUnreadCountByIds:(NSArray<NSString *> *)conversationIds
                        success:(nullable V2NIMConversationUnreadCountCallback)success
                        failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds NSArray<NSString> - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMConversationUnreadCountCallback - 获取会话未读数成功回调,可自定义。
    failure V2NIMFailureCallback - 获取失败回调,返回 错误码
    macOS/Windows
    C++virtual void getUnreadCountByIds(nstd::vector<nstd::string> conversationIds,
        V2NIMSuccessCallback<uint32_t> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds nstd::vectornstd::string - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 获取成功回调,返回指定会话列表的总未读数。
    failure V2NIMFailureCallback - 获取失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptgetUnreadCountByIds(conversationIds: string[]): Promise<number>
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds string[] - 会话 ID 列表,不可为空,否则返回 191004 参数错误。
    HarmonyOS
    TypeScriptgetUnreadCountByIds(conversationIds: string[]): Promise<number>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++auto 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
    }
    
    HarmonyOS
    TypeScriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
    try {
      const unreadCount: number = await this.conversationService.getUnreadCountByIds(conversationIds)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<number> 指定的会话列表的总未读数。

    相关回调

    Android//macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调,包含指定的会话列表的总未读数。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    iOS
    • 请求成功,返回 V2NIMConversationUnreadCountCallback 回调,可自定义设置。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    getUnreadCountByFilter

    接口描述

    获取过滤后的所有会话列表消息总未读数。

    数据同步完成前,可能查询不到完整数据。

    参数说明

    Android
    Javavoid getUnreadCountByFilter(V2NIMConversationFilter filter, V2NIMSuccessCallback<Integer> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 过滤器配置,SDK 会按照该参数配置进行滤,并返回过滤后的会话列表的消息总未读数。
    success V2NIMSuccessCallback - 获取成功回调,返回过滤后的会话列表的总未读数。
    failure V2NIMFailureCallback - 获取失败回调,返回 错误码
    iOS
    Objective-C- (void)getUnreadCountByFilter:(V2NIMConversationFilter *)filter
                           success:(nullable V2NIMConversationUnreadCountCallback)success
                           failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 过滤器配置,SDK 会按照该参数配置进行滤,并返回过滤后的会话列表的消息总未读数。
    success V2NIMConversationUnreadCountCallback - 获取会话未读数成功回调,可自定义。
    failure V2NIMFailureCallback - 获取失败回调,返回 错误码
    macOS/Windows
    C++virtual void getUnreadCountByFilter(V2NIMConversationFilter filter, V2NIMSuccessCallback<uint32_t> success, V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 过滤器配置,SDK 会按照该参数配置进行滤,并返回过滤后的会话列表的消息总未读数。
    success V2NIMSuccessCallback - 获取成功回调,返回过滤后的会话列表的总未读数。
    failure V2NIMFailureCallback - 获取失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptgetUnreadCountByFilter(filter: V2NIMConversationFilter): Promise<number>
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 过滤器配置,SDK 会按照该参数配置进行滤,并返回过滤后的会话列表的消息总未读数。
    HarmonyOS
    TypeScriptgetUnreadCountByFilter(filter: V2NIMConversationFilter): Promise<number>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++V2NIMConversationFilter 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
    }
    
    HarmonyOS
    TypeScriptlet filter: V2NIMConversationFilter = {
      conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
    }
    try {
      let unreadCount: number = await this.conversationService.getUnreadCountByFilter(filter)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<number> 过滤后的会话列表的消息总未读数。

    相关回调

    Android/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调,包含过滤后的会话列表的消息总未读数。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    iOS
    • 请求成功,返回 V2NIMConversationUnreadCountCallback 回调,可自定义设置。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序/HarmonyOS

    clearTotalUnreadCount

    接口描述

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

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

    参数说明

    Android
    Javavoid clearTotalUnreadCount(V2NIMSuccessCallback<Void> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    iOS
    Objective-C- (void)clearTotalUnreadCount:(nullable V2NIMSuccessCallback)success
                          failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    macOS/Windows
    C++virtual void clearTotalUnreadCount(V2NIMSuccessCallback<void> success, V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptclearTotalUnreadCount(): Promise<void>
    

    无参数

    HarmonyOS
    TypeScriptclearTotalUnreadCount(): Promise<void>
    

    无参数

    示例代码

    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
    C++conversationService.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
    }
    
    HarmonyOS
    TypeScripttry {
      await nim.V2NIMConversationService.clearTotalUnreadCount()
      // Success
    } catch (err) {
      // handle error
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<void>

    相关回调

    Android/iOS/macOS/Windows
    Web/uni-app/小程序/HarmonyOS

    clearUnreadCountByIds

    接口描述

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

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

    调用前请确保指定的会话已存在。

    参数说明

    Android
    Javavoid clearUnreadCountByIds(@NonNull List<String> conversationIds, V2NIMSuccessCallback<List<V2NIMConversationOperationResult>> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds List - 会话 ID 列表。
  • 会话 ID 列表。不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
  • success V2NIMSuccessCallback - 清零成功回调,返回 List<V2NIMConversationOperationResult>,仅包含清零失败的会话 ID 及相关错误码。
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    iOS
    Objective-C- (void)clearUnreadCountByIds:(NSArray<NSString *> *)conversationIds
                          success:(nullable V2NIMConversationOperationResultListCallback)success
                          failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds NSArray - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
  • success V2NIMConversationOperationResultListCallback - 清零成功回调,可自定义设置。
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    macOS/Windows
    C++virtual void clearUnreadCountByIds(nstd::vector<nstd::string> conversationIds,
        V2NIMSuccessCallback<nstd::vector<V2NIMConversationOperationResult>> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds String - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
  • success V2NIMSuccessCallback - 清零成功回调,返回 V2NIMConversationOperationResult 列表,仅包含清零失败的会话 ID 及相关错误码。
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptclearUnreadCountByIds(conversationIds: string[]): Promise<V2NIMConversationOperationResult[]>
    
    参数名称 类型 是否必填 默认值 说明
    conversationIds String[] - 会话 ID 列表。
  • 不可为空,否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
  • HarmonyOS
    TypeScriptclearUnreadCountByIds(conversationIds: string[]): Promise<V2NIMConversationOperationResult[]>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++auto 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
    }
    
    HarmonyOS
    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
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    相关回调

    Android/macOS/Windows
    iOS
    Web/uni-app/小程序/HarmonyOS

    clearUnreadCountByGroupId

    接口描述

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

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

    调用前请确保指定的会话分组已存在。

    参数说明

    Android
    Javavoid clearUnreadCountByGroupId(@NonNull String groupId, V2NIMSuccessCallback<Void> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    groupId String - 会话分组 ID。通过调用 createConversationGroup 获得。不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    iOS
    Objective-C- (void)clearUnreadCountByGroupId:(NSString *)groupId
                              success:(nullable V2NIMSuccessCallback)success
                              failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    groupId String - 会话分组 ID。通过调用 createConversationGroup 获得。不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    macOS/Windows
    C++virtual void clearUnreadCountByGroupId(nstd::string groupId, V2NIMSuccessCallback<void> success, V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    groupId String - 会话分组 ID。通过调用 createConversationGroup 获得。不可为空,否则返回 191004 参数错误。
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptclearUnreadCountByGroupId(groupId: string): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    groupId String - 会话分组 ID。通过调用 createConversationGroup 获得。不可为空,否则返回 191004 参数错误。
    HarmonyOS
    TypeScriptclearUnreadCountByGroupId(groupId: string): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    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
    C++conversationService.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
    }
    
    HarmonyOS
    TypeScriptlet groupId: string = "0123456789"
    try {
      await this.conversationService.clearUnreadCountByGroupId(groupId)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<void>

    相关回调

    Android/iOS/macOS/Windows
    Web/uni-app/小程序/HarmonyOS

    clearUnreadCountByTypes

    接口描述

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

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

    参数说明

    Android
    Javavoid clearUnreadCountByTypes(@NonNull List<V2NIMConversationType> conversationTypes, V2NIMSuccessCallback<Void> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationTypes List<V2NIMConversationType> - 会话类型
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    iOS
    Objective-C- (void)clearUnreadCountByTypes:(NSArray<NSNumber *> *)conversationTypes
                            success:(nullable V2NIMSuccessCallback)success
                            failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationTypes NSArray<NSNumber *> * - 会话类型
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    macOS/Windows
    C++virtual void clearUnreadCountByTypes(nstd::vector<V2NIMConversationType> conversationTypes,
        V2NIMSuccessCallback<void> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    conversationTypes nstd::vector<V2NIMConversationType> - 会话类型
    success V2NIMSuccessCallback - 清零成功回调
    failure V2NIMFailureCallback - 清零失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScriptclearUnreadCountByTypes(types: V2NIMConversationType[]): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    types V2NIMConversationType[] - 会话类型
    HarmonyOS
    TypeScriptclearUnreadCountByTypes(types: V2NIMConversationType[]): Promise<void>
    
    参数名称 类型 是否必填 默认值 说明
    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) {
            // TODO
        }
    }, new V2NIMFailureCallback(){
        @Override
        public void onFailure(V2NIMError error){
            int code = error.getCode();
            String desc = error.getDesc();
            // TODO
        }
    });
    
    iOS
    Objective-C[NIMSDK.sharedSDK.v2ConversationService clearUnreadCountByTypes:@[
        @(V2NIM_CONVERSATION_TYPE_P2P),
        @(V2NIM_CONVERSATION_TYPE_TEAM),
    ] success:^{
    
        } failure:^(V2NIMError * _Nonnull error) {
            // handle error
        }];
    
    macOS/Windows
    C++conversationService.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])
      // todo Success.
    } catch (err) {
      // todo err.code
    }
    
    HarmonyOS
    TypeScriptlet conversationTypes:V2NIMConversationType[] = [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
    try {
      await this.conversationService.clearUnreadCountByTypes(conversationTypes)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/HarmonyOS

    Promise<void>

    相关回调

    Android/iOS/macOS/Windows
    Web/uni-app/小程序/HarmonyOS

    subscribeUnreadCountByFilter

    接口描述

    订阅过滤后的会话未读数变化监听。您可以多次调用该方法,订阅多个过滤器的会话未读数监听。

    订阅成功后,当过滤后的会话未读数变化,SDK 返回 onUnreadCountChangedByFilter 回调。

    参数说明

    Android
    Javavoid subscribeUnreadCountByFilter(@NonNull V2NIMConversationFilter filter);
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象
  • 如果该对象参数均为空,则返回 191004 错误码。
  • 如果该对象设置多个参数且生效,则返回参数对应的多个回调。如果设置多个参数但有参数错误未生效,则不触发任何回调。
  • iOS
    Objective-C- (void)subscribeUnreadCountByFilter:(V2NIMConversationFilter *)filter;
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象
  • 如果该对象参数均为空,则返回 191004 错误码。
  • 如果该对象设置多个参数且生效,则返回参数对应的多个回调。如果设置多个参数但有参数错误未生效,则不触发任何回调。
  • macOS/Windows
    C++virtual void subscribeUnreadCountByFilter(V2NIMConversationFilter filter) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象
  • 如果该对象参数均为空,则返回 191004 错误码。
  • 如果该对象设置多个参数且生效,则返回参数对应的多个回调。如果设置多个参数但有参数错误未生效,则不触发任何回调。
  • Web/uni-app/小程序
    TypeScriptsubscribeUnreadCountByFilter(filter: V2NIMConversationFilter): void
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象
  • 如果该对象参数均为空,则返回 191004 错误码。
  • 如果该对象设置多个参数且生效,则返回参数对应的多个回调。如果设置多个参数但有参数错误未生效,则不触发任何回调。
  • HarmonyOS
    TypeScriptsubscribeUnreadCountByFilter(filter: V2NIMConversationFilter): void
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象
  • 如果该对象参数均为空,则返回 191004 错误码。
  • 如果该对象设置多个参数且生效,则返回参数对应的多个回调。如果设置多个参数但有参数错误未生效,则不触发任何回调。
  • 示例代码

    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
    C++V2NIMConversationFilter filter;
    filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
    conversationService.subscribeUnreadCountByFilter(filter);
    
    Web/uni-app/小程序
    TypeScriptconst filter = {
        conversationTypes: [1]
    }
    nim.V2NIMConversationService.subscribeUnreadCountByFilter(filter)
    
    HarmonyOS
    TypeScriptconst filter: V2NIMConversationFilter = {
      conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
    }
    try {
      this.conversationService.subscribeUnreadCountByFilter(filter)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    unsubscribeUnreadCountByFilter

    接口描述

    取消订阅过滤后的会话未读数变化监听。

    参数说明

    Android
    Javavoid unsubscribeUnreadCountByFilter(@NonNull V2NIMConversationFilter filter);
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象。如果该对象参数均为空,则返回 191004 错误码。
    iOS
    Objective-C- (void)unsubscribeUnreadCountByFilter:(V2NIMConversationFilter *)filter;
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象。如果该对象参数均为空,则返回 191004 错误码。
    macOS/Windows
    C++virtual void unsubscribeUnreadCountByFilter(V2NIMConversationFilter filter) = 0;
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象。如果该对象参数均为空,则返回 191004 错误码。
    Web/uni-app/小程序
    TypeScriptunsubscribeUnreadCountByFilter(filter: V2NIMConversationFilter): void
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象。如果该对象参数均为空,则返回 191004 错误码。
    HarmonyOS
    TypeScriptunsubscribeUnreadCountByFilter(filter: V2NIMConversationFilter): void
    
    参数名称 类型 是否必填 默认值 说明
    filter V2NIMConversationFilter - 会话过滤对象。如果该对象参数均为空,则返回 191004 错误码。

    示例代码

    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
    C++V2NIMConversationFilter filter;
    filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
    conversationService.unsubscribeUnreadCountByFilter(filter);
    
    Web/uni-app/小程序
    TypeScriptconst filter = {
        conversationTypes: [1]
    }
    nim.V2NIMConversationService.unsubscribeUnreadCountByFilter(filter)
    
    HarmonyOS
    TypeScriptconst filter: V2NIMConversationFilter = {
      conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
    }
    try {
      this.conversationService.unsubscribeUnreadCountByFilter(filter)
      // success
    } catch (e) {
      // fail
    }
    

    返回值

    markConversationRead

    接口描述

    标记会话已读时间戳。当前只支持 P2P,高级群,超大群会话类型。

    标记成功后,SDK 会同步本地数据库和缓存。

    参数说明

    Android
    Java/**
     * 标记会话已读时间戳
     * 当前只支持 P2P,高级群,超大群
     * @param conversationId 会话 ID
     * @param success 查询成功回调
     * @param failure 查询失败回调
     */
    void markConversationRead(String conversationId, V2NIMSuccessCallback<Long> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMSuccessCallback - 标记成功回调,返回 readTime
    failure V2NIMFailureCallback - 标记失败回调,返回 错误码
    iOS
    Objective-C/// 成功接收标记会话已读时间戳
    typedef void (^V2NIMMarkConversationReadCallback)(NSTimeInterval timestamp);
    
    /**
     * 标记会话已读时间戳
     *
     * @param conversationId 会话 ID
     * @param success 成功回调
     * @param failure 失败回调
     */
    - (void)markConversationRead:(NSString *)conversationId
                         success:(nullable V2NIMMarkConversationReadCallback)success
                         failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId NSString - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMMarkConversationReadCallback - 标记成功回调 可自定义。
    failure V2NIMFailureCallback - 标记会话失败回调,返回 错误码
    macOS/Windows
    C++virtual void v2::V2NIMConversationService::markConversationRead    (    nstd::string     conversationId,
    V2NIMSuccessCallback< time_t >     success,
    V2NIMFailureCallback     failure
    )
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMSuccessCallback - 标记成功回调,返回 readTime
    failure V2NIMFailureCallback - 标记失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScript  /**
       * 标记会话已读时间戳
       *
       * 注: 当该方法调用后,SDK 可能给多端账户抛出以下的事件
       *
       * {@link V2NIMConversationListener.onConversationReadTimeUpdated | V2NIMConversationListener.onConversationReadTimeUpdated} <br/>
       *
       */
    markConversationRead(conversationId: string): Promise<number>
    
    参数名称 类型 是否必填 默认值 说明
    conversationId string - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。

    示例代码

    Android
    JavaString sessionId = "会话对象 ID";
    V2NIMConversationType conversationType = V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P;
    String conversationId = V2NIMConversationIdUtil.conversationId(sessionId, conversationType);
    NIMClient.getService(V2NIMConversationService.class).markConversationRead(conversationId,
            new V2NIMSuccessCallback<Long>() {
                @Override
                public void onSuccess(Long aLong) {
    
                }
            },
            new V2NIMFailureCallback() {
                @Override
                public void onFailure(V2NIMError error) {
    
                }
            });
    
    iOS
    Objective-C- (void)markRead
    {
        [NIMSDK.sharedSDK.v2ConversationService markConversationRead:@"conversationId" success:^(NSTimeInterval timestamp) {
            // result
        } failure:^(V2NIMError * _Nonnull error) {
            // error
        }];
    }
    
    macOS/Windows
    C++conversationService.markConversationRead(
        "conversationId",
        []() {
            // mark conversation read succeeded
        },
        [](V2NIMError error) {
            // mark conversation read failed, handle error
        )};
    
    Web/uni-app/小程序
    TypeScriptawait nim.V2NIMConversationService.markConversationRead('sender|1|receiver')
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序

    Promise<number>

    相关回调

    Android/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调。标记成功,返回 readTime
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    iOS
    • 请求成功,返回 V2NIMMarkConversationReadCallback 回调,可自定义。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序

    getConversationReadTime

    接口描述

    获取指定会话的已读时间戳。

    • 查询前请确保指定的会话已存在。
    • 数据同步完成前,可能查询不到完整数据。

    参数说明

    Android
    Java/**
     * 获取会话已读时间戳
     * 当前只支持 P2P,高级群,超大群
     * @param conversationId 会话 ID
     * @param success 查询成功回调
     * @param failure 查询失败回调
     */
    void getConversationReadTime(String conversationId, V2NIMSuccessCallback<Long> success, V2NIMFailureCallback failure);
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询成功回调,返回 readTime
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    iOS
    Objective-C/// 成功接收已读时间戳
    typedef void (^V2NIMConversationReadTimeCallback)(NSTimeInterval timestamp);
    
    /**
     * 获取会话已读时间戳
     *
     * @param conversationId 会话 ID
     * @param success 成功回调
     * @param failure 失败回调
     */
    - (void)getConversationReadTime:(NSString *)conversationId
                            success:(nullable V2NIMConversationReadTimeCallback)success
                            failure:(nullable V2NIMFailureCallback)failure;
    
    参数名称 类型 是否必填 默认值 说明
    conversationId NSString - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMConversationReadTimeCallback - 查询成功回调 可自定义。
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    macOS/Windows
    C++virtual void v2::V2NIMConversationService::getConversationReadTime    (    nstd::string     conversationId,
    V2NIMSuccessCallback< time_t >     success,
    V2NIMFailureCallback     failure
    )
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。
    success V2NIMSuccessCallback - 查询成功回调,返回 readTime
    failure V2NIMFailureCallback - 查询失败回调,返回 错误码
    Web/uni-app/小程序
    TypeScript  /**
       * 获取会话已读时间戳。该时间包含多端已读时间戳
       */
    getConversationReadTime(conversationId: string): Promise<number>
    
    参数名称 类型 是否必填 默认值 说明
    conversationId String - 会话 ID,如果为空、不合法、不存在则返回 191004 参数错误。

    示例代码

    Android
    JavaString sessionId = "会话对象 ID";
    V2NIMConversationType conversationType = V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P;
    String conversationId = V2NIMConversationIdUtil.conversationId(sessionId, conversationType);
    NIMClient.getService(V2NIMConversationService.class).getConversationReadTime(conversationId,
            new V2NIMSuccessCallback<Long>() {
                @Override
                public void onSuccess(Long aLong) {
    
                }
            },
            new V2NIMFailureCallback() {
                @Override
                public void onFailure(V2NIMError error) {
    
                }
            });
    
    iOS
    Objective-C- (void)getReadTime
    {
        [NIMSDK.sharedSDK.v2ConversationService getConversationReadTime:@"conversationId" success:^(NSTimeInterval timestamp) {
            // result
        } failure:^(V2NIMError * _Nonnull error) {
            // error
        }];
    }
    
    macOS/Windows
    C++conversationService.getConversationReadTime(
        "conversationId",
        [](time_t readTime) {
            // get conversation read time succeeded
        },
        [](V2NIMError error) {
            // get conversation read time failed, handle error
        )};
    
    Web/uni-app/小程序
    TypeScriptconst readTime = await nim.V2NIMConversationService.getConversationReadTime('sender|1|receiver')
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序

    Promise<number>

    相关回调

    Android/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调。标记成功,返回 readTime
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    iOS
    • 请求成功,返回 V2NIMConversationReadTimeCallback 回调,可自定义。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含会话相关错误码。
    Web/uni-app/小程序

    此文档是否对你有帮助?
    有帮助
    去反馈
    • 支持平台
    • API 概览
    • 会话监听
    • 会话操作
    • 会话未读数
    • 接口类
    • addConversationListener
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • removeConversationListener
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • on("EventName")
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • off("EventName")
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • createConversation
    • 接口描述
    • 使用场景
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • deleteConversation
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • deleteConversationListByIds
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • getConversation
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • getConversationList
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • getConversationListByOption
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • getConversationListByIds
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • updateConversation
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • updateConversationLocalExtension
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • stickTopConversation
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • getTotalUnreadCount
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • getUnreadCountByIds
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • getUnreadCountByFilter
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • clearTotalUnreadCount
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • clearUnreadCountByIds
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • clearUnreadCountByGroupId
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • clearUnreadCountByTypes
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • subscribeUnreadCountByFilter
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • unsubscribeUnreadCountByFilter
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • markConversationRead
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调
    • getConversationReadTime
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调