云端会话管理 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

云端会话管理

更新时间： 2025/07/17 11:26:50

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

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

支持平台

本文内容适用的开发平台或框架如下表所示，本文涉及的接口请参考下文相关接口章节：

安卓	iOS	macOS/Windows	Web/uni-app/小程序	Node.js/Electron	鸿蒙	Flutter
✔️️️	✔️️️	✔️️️	✔️️️	✔️️️	✔️️	✔️️

技术原理

网易云信 IM 支持云端（服务端）会话，在服务器进行存储和维护，支持存储和查询用户全量的会话历史消息。有关服务端会话及未读数，请参考服务端 API 云端会话管理。

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

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

前提条件

根据本文操作前，请确保您已经完成了以下设置：

已在网易云信控制台为应用开通 云端会话 开关。开启步骤请参考《控制台文档》配置应用。
已在初始化时开启云端会话功能。若不开启，将默认使用本地会话功能。
安卓
将 SDKOptions.enableV2CloudConversation 设置为 true，只有设置为 true 后，才能正常使用云端会话 V2NIMConversationService 服务。具体请请参考初始化 SDK。

iOS
将 V2NIMSDKOption.enableV2CloudConversation 设置为 YES，只有设置为 YES 后，才能正常使用云端会话 V2NIMConversationService 服务。具体请请参考初始化 SDK。

macOS/Windows
将 V2NIMBasicOption.enableCloudConversation 设置为 true，只有设置为 true 后，才能正常使用云端会话 V2NIMConversationService 服务。具体请请参考初始化 SDK。

Web/uni-app/小程序
将 NIMInitializeOptions.enableV2CloudConversation 设置为 true，只有设置为 true 后，才能正常使用云端会话 V2NIMConversationService 服务。具体请请参考初始化 SDK。

Node.js/Electron
将 V2NIMBasicOption.enableCloudConversation 设置为 true，只有设置为 true 后，才能正常使用云端会话 V2NIMConversationService 服务。具体请请参考初始化 SDK。

鸿蒙
在初始化中注册 云端会话（CONVERSATION）和 云端会话分组（CONVERSATION_GROUP）服务。具体请请参考初始化 SDK。
Flutter
- Android 平台：将 NIMAndroidSDKOptions.enableV2CloudConversation 设置为 true，只有设置为 true 后，才能正常使用云端会话 ConversationService 服务。
- iOS 平台：将 NIMIOSSDKOptions.enableV2CloudConversation 设置为 true，只有设置为 true 后，才能正常使用云端会话 ConversationService 服务。
具体请请参考初始化 SDK。
已实现登录 IM。

监听会话相关事件

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

注册监听

云端会话相关回调：

onSyncStarted：数据同步开始回调。
onSyncFinished：数据同步结束回调。如果数据同步已开始，建议在数据同步结束后再进行其他会话操作。
onSyncFailed：数据同步失败回调。
onConversationCreated：会话成功创建回调。
onConversationDeleted：主动删除会话回调。
onConversationChanged：会话变更回调。当置顶会话、会话有新消息、主动更新会话成功时会触发该回调。
onTotalUnreadCountChanged：会话消息总未读数变更回调。
onUnreadCountChangedByFilter：过滤后的未读数变更回调。调用 subscribeUnreadCountByFilter 方法订阅监听后，当会话过滤后的未读数变化时会返回该回调。
onConversationReadTimeUpdated：同一账号多端登录后的会话已读时间戳标记的回调。

示例代码：

安卓

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

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

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

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

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

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);

Web/uni-app/小程序

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

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) {
// Update UI with success message.
// if filter.equals(TARGET_FILTER)
})

Node.js/Electron

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

TypeScriptv2.conversationService.on("syncStarted", function () {})
v2.conversationService.on("syncFinished", function () {})
v2.conversationService.on("syncFailed", function (err) {})
v2.conversationService.on("conversationCreated", function (conversation: V2NIMConversation) {})
v2.conversationService.on("conversationDeleted", function (conversationIds: string[]) {})
v2.conversationService.on("conversationChanged", function (conversationList: V2NIMConversation[]) {})
v2.conversationService.on("totalUnreadCountChanged", function (unreadCount: number) {})
v2.conversationService.on("unreadCountChangedByFilter", function (filter: V2NIMConversationFilter & { equals: (filter: V2NIMConversationFilter) => boolean }, unreadCount: number) {
// Update UI with success message.
// if filter.equals(TARGET_FILTER)
})

鸿蒙

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

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) => {
// Update UI with success message.
// if filter.equals(TARGET_FILTER)
})

Flutter

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

Dartsubsriptions.add(NimCore.instance.conversationService.onSyncStarted.listen((e) {
    //do something
    }));
    subsriptions.add(NimCore.instance.conversationService.onSyncFinished.listen((e) {
    //do something
    }));
    subsriptions.add(NimCore.instance.conversationService.onSyncFailed.listen((e) {
    //do something
    }));
    subsriptions.add(NimCore.instance.conversationService.onConversationCreated.listen((e) {
    //do something
    }));
    subsriptions.add(NimCore.instance.conversationService.onConversationDeleted.listen((e) {
    //do something
    }));
    subsriptions.add(NimCore.instance.conversationService.onConversationChanged.listen((e) {
    //do something
    }));
    subsriptions.add(NimCore.instance.conversationService.onTotalUnreadCountChanged.listen((e) {
    //do something
    }));
    subsriptions.add(NimCore.instance.conversationService.onUnreadCountChangedByFilter.listen((e) {
    //do something
    }));
    subsriptions.add(NimCore.instance.conversationService.onConversationReadTimeUpdated.listen((e) {
    //do something
    }));

移除监听

安卓

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

JavaNIMClient.getService(V2NIMConversationService.class).removeConversationListener(listener);

iOS

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

Objective-Cid<V2NIMConversationListener> listener;
[NIMSDK.sharedSDK.v2ConversationService removeConversationListener:listener];

macOS/Windows

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

C++V2NIMConversationListener listener;
conversationService.removeConversationListener(listener);

Web/uni-app/小程序

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

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

Node.js/Electron

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

TypeScriptv2.conversationService.off("syncStarted")
v2.conversationService.off("syncFinished")
v2.conversationService.off("syncFailed")
v2.conversationService.off("conversationCreated")
v2.conversationService.off("conversationDeleted")
v2.conversationService.off("conversationChanged")
v2.conversationService.off("totalUnreadCountChanged")
v2.conversationService.off("unreadCountChangedByFilter")

鸿蒙

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

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

Flutter

如需移除会话相关监听，可调用 cancel。

Dartsubsriptions.forEach((subsription) {
    subsription.cancel();
    });

过滤监听

调用 subscribeUnreadCountByFilter 方法订阅指定过滤条件过滤后的会话未读数变化监听：

安卓

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)

Node.js/Electron

TypeScriptconst filter = {
    conversationTypes: [1]
}
await v2.conversationService.subscribeUnreadCountByFilter(filter)

鸿蒙

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

Flutter

Dartawait NimCore.instance.conversationService.subscribeUnreadCountByFilter(filter)

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

安卓

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)

Node.js/Electron

TypeScriptconst filter = {
    conversationTypes: [1]
}
await v2.conversationService.unsubscribeUnreadCountByFilter(filter)

鸿蒙

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

Flutter

Dartawait NimCore.instance.conversationService.unsubscribeUnreadCountByFilter(filter)

创建会话

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

创建成功后，SDK 会返回创建成功回调 onConversationCreated，并同步缓存和数据库。

示例代码：

安卓

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
}

Node.js/Electron

TypeScriptconst conversation = await v2.conversationService.createConversation('conversation1')

鸿蒙

TypeScripttypescript
let conversationId: string = "cjl|1|cjl1";
try {
let conv: V2NIMConversation = await this.conversationService.createConversation(conversationId)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.createConversation(conversationId)

获取会话

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

分页获取所有会话列表

调用 getConversationList 方法分页获取会话数据，直到获取全量会话。

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

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

示例代码：

安卓

JavaNIMClient.getService(V2NIMConversationService.class).getConversationList(0, 100, new V2NIMSuccessCallback<V2NIMConversationResult>() {
    @Override
    public void onSuccess(V2NIMConversationResult result) {
        // success
    }
}, new V2NIMFailureCallback() {
    @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
}

Node.js/Electron

TypeScripttry {
  const result = await v2.conversationService.getConversationList(0, 10)
  // receive result
} catch (err) {
  // handle error
}

鸿蒙

TypeScripttry {
const result = await nim.conversationService.getConversationList(0, 100)
// success
} catch (err) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.getConversationList(offset, limit)

获取指定单条会话

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

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

示例代码：

安卓

JavaNIMClient.getService(V2NIMConversationService.class).getConversation("会话 ID", new V2NIMSuccessCallback<V2NIMConversation>(){
    @Override
    public void onSuccess(V2NIMConversation conversation){
        // 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 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
}

Node.js/Electron

TypeScripttry {
  const conversation = await v2.conversationService.getConversation('conversation1')
  // success
} catch (err) {
  // handle error
}

鸿蒙

TypeScriptlet conversationId: string = "cjl|1|cjl1";
try {
let conv: V2NIMConversation = await this.conversationService.getConversation(conversationId)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.getConversation(conversationId)

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

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

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

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

示例代码：

安卓

JavaV2NIMConversationOption option = new V2NIMConversationOption();
List<Integer> conversionTypes = new ArrayList<Integer>();
conversionTypes.add(1);
options.setConversionTypes =conversionTypes;
option.onlyUnread = true;
NIMClient.getService(V2NIMConversationService.class).getConversationListByOption(0, 100,option, new      V2NIMSuccessCallback<V2NIMConversationResult>>(){
    @Override
    public void onSuccess<V2NIMConversationResult>(V2NIMConversationResult result){
        // receive result
    }
}, new V2NIMFailureCallback(){
    @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
}

Node.js/Electron

TypeScripttry {
  const result = await v2.conversationService.getConversationListByOption(0, 10, {
    conversationTypes: [1, 2]
  })
  // Success
} catch (err) {
  // handle error
}

鸿蒙

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
}

Flutter

Dartawait NimCore.instance.conversationService.getConversationListByOption(offset, limit, option)

批量获取指定的会话列表

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

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

示例代码：

安卓

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
}

Node.js/Electron

TypeScripttry {
  const list = await v2.conversationService.getConversationListByIds(['conversation1', 'conversation2'])
  // receive conversation list
} catch (err) {
  // handle error
}

鸿蒙

TypeScriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
try {
let result: V2NIMConversation[] = await this.conversationService.getConversationListByIds(conversationIds)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.getConversationListByIds(conversationIds)

更新会话

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

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

示例代码：

安卓

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 = { serverExtension: "This is a new text" }
await nim.V2NIMConversationService.updateConversation("CONVERSATION_ID", params)
// Success
} catch (err) {
// handle error
}

Node.js/Electron

TypeScripttry {
  await v2.conversationService.updateConversation('conversation1', { name: 'newName' })
  // Success
} catch (err) {
  // handle error
}

鸿蒙

TypeScriptlet conversationId: string = "cjl|1|cjl1"
let userInfo: V2NIMConversationUpdate = {
serverExtension: "serverExtension"
}
try {
await this.conversationService.updateConversation(conversationId, userInfo)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.updateConversation(conversationId, updateInfo)

更新会话本地扩展字段

调用 updateConversationLocalExtension 更新会话本地扩展字段。

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

示例代码：

安卓

JavaNIMClient.getService(V2NIMConversationService.class).updateConversationLocalExtension("conversationId", localExtension, 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 updateConversationLocalExtension:@"conversationId" localExtension:@"localExtension" success:^{
    // success
} failure:^(V2NIMError *error) {
    // handle error
}];

macOS/Windows

C++auto conversationId = V2NIMConversationIdUtil::p2pConversationId("account1");
conversationService.updateConversationLocalExtension(
    conversationId,
    "localExtension",
    []() {
        // update succeeded
    },
    [](V2NIMError error) {
        // update failed, handle error
    });

Web/uni-app/小程序

TypeScripttry {
  await nim.V2NIMConversationService.updateConversationLocalExtension("CONVERSATION_ID", "newLocalExtension!")
  // Update UI with success message.
} catch (err) {
  // Handle error with err.code
}

Node.js/Electron

TypeScripttry {
  await v2.conversationService.updateConversationLocalExtension('conversation1', 'newExtension')
  // Update UI with success message.
} catch (err) {
  // Handle error with err.code
}

鸿蒙

TypeScriptlet conversationId: string = "cjl|1|cjl1"
let localExtension: string = "localExtension"
try {
  await this.conversationService.updateConversationLocalExtension(conversationId, localExtension)
  // success
} catch (e) {
  // fail
}

Flutter

Dartawait NimCore.instance.conversationService.updateConversationLocalExtension(conversationId, localExtension)

删除会话

删除指定单条会话

调用 deleteConversation 根据会话 ID 删除指定会话（包括本地和云端会话），且支持指定是否删除会话内的历史消息（包括本地和漫游消息）。

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

删除成功后，SDK 会返回删除成功回调 onConversationDeleted，并同步数据库和缓存。

如果被删除会话中有消息未读，SDK 还会返回 onTotalUnreadCountChanged 和 onUnreadCountChangedByFilter 回调。

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

示例代码：

安卓

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
}

Node.js/Electron

TypeScripttry {
  await v2.conversationService.deleteConversation('conversation1', true)
  // delete succeeded
} catch (err) {
  // delete failed, handle error
}

鸿蒙

TypeScriptlet conversationId: string = "cjl|1|cjl1";
let clearMessage: boolean = true;
try {
await this.conversationService.deleteConversation(conversationId, clearMessage)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.deleteConversation(conversationId, clearMessage)

批量删除指定会话列表

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

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

每一条最近会话删除成功后，SDK 均会返回删除成功回调 onConversationDeleted 回调，并同步数据库和缓存。

如果被删除会话中有消息未读，SDK 还会返回 onTotalUnreadCountChanged 和 onUnreadCountChangedByFilter 回调。

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

示例代码：

安卓

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
}

Node.js/Electron

TypeScripttry {
  const result = await v2.conversationService.deleteConversationListByIds(['conversation1', 'conversation2'], true)
  // delete succeeded, check failed conversation
} catch (err) {
  // delete failed, handle error
}

鸿蒙

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
}

Flutter

Dartawait NimCore.instance.conversationService.deleteConversationListByIds(conversationIds, clearMessage)

消息未读数

获取消息未读数

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

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

示例代码：

安卓

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()

Node.js/Electron

TypeScriptconst count = await v2.conversationService.getTotalUnreadCount()

鸿蒙

TypeScriptconst unreadCount: number = this.conversationService.getTotalUnreadCount()

Flutter

Dartawait NimCore.instance.conversationService.getTotalUnreadCount()

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

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

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

示例代码：

安卓

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
}

Node.js/Electron

TypeScripttry {
  const count = await v2.conversationService.getUnreadCountByIds(['conversation1', 'conversation2'])
} catch (err) {
    // Handle error
}

鸿蒙

TypeScriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
try {
const unreadCount: number = await this.conversationService.getUnreadCountByIds(conversationIds)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.getUnreadCountByIds(conversationIds)

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

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

示例代码：

安卓

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
}

Node.js/Electron

TypeScripttry {
  // P2P type
  const count = await v2.conversationService.getUnreadCountByFilter({ conversationTypes: [1, 2] })
  // receive unread count
} catch (err) {
  // handle error
}

鸿蒙

TypeScriptlet filter: V2NIMConversationFilter = {
conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
}
try {
let unreadCount: number = await this.conversationService.getUnreadCountByFilter(filter)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.getUnreadCountByFilter(filter)

未读数清零

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

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

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

清零成功后，SDK 返回 onTotalUnreadCountChanged、onConversationChanged 和 onUnreadCountChangedByFilter 回调，并同步数据库和缓存。

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

示例代码：

安卓

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
}

Node.js/Electron

TypeScripttry {
  await v2.conversationService.clearTotalUnreadCount()
  // Success
} catch (err) {
  // handle error
}

鸿蒙

TypeScripttry {
await nim.V2NIMConversationService.clearTotalUnreadCount()
// Success
} catch (err) {
// handle error
}

Flutter

Dartawait NimCore.instance.conversationService.clearTotalUnreadCount()

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

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

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

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

示例代码：

安卓

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
}

Node.js/Electron

TypeScripttry {
  const result = await v2.conversationService.clearUnreadCountByIds(['conversation1', 'conversation2'])
  // Success
} catch (err) {
  // handle error
}

鸿蒙

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
}

Flutter

Dartawait NimCore.instance.conversationService.clearUnreadCountByIds(conversationIds)

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

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

清零成功后，SDK 返回 onTotalUnreadCountChanged、onConversationChanged 和 onUnreadCountChangedByFilter 回调，并同步数据库和缓存。

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

示例代码：

安卓

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
}

Node.js/Electron

TypeScripttry {
  await v2.conversationService.clearUnreadCountByGroupId('groupId')
  // Success
} catch (err) {
  // handle error
}

鸿蒙

TypeScriptlet groupId: string = "0123456789"
try {
await this.conversationService.clearUnreadCountByGroupId(groupId)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.clearUnreadCountByGroupId(groupId)

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

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

清零成功后，SDK 返回 onTotalUnreadCountChanged、onConversationChanged 和 onUnreadCountChangedByFilter 回调，并同步数据库和缓存。

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

示例代码：

安卓

JavaList<V2NIMConversationType> conversionTypes = new ArrayList<>();
conversionTypes.add(V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
NIMClient.getService(V2NIMConversationService.class).clearUnreadCountByTypes(conversionTypes,new V2NIMSuccessCallback<Void>(){
    @Override
    public void onSuccess(Void unused) {
        // success
    }
}, new V2NIMFailureCallback(){
    @Override
    public void onFailure(V2NIMError error){
        int code = error.getCode();
        String desc = error.getDesc();
        // handle error
    }
});

iOS

Objective-C[NIMSDK.sharedSDK.v2ConversationService clearUnreadCountByTypes:@[
        @(V2NIM_CONVERSATION_TYPE_P2P),
        @(V2NIM_CONVERSATION_TYPE_TEAM),
    ] success:^{
        // success
    } failure:^(V2NIMError * _Nonnull error) {
        // handle error
    }];

macOS/Windows

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])
// Success
} catch (err) {
// handle error
}

Node.js/Electron

TypeScripttry {
  await v2.conversationService.clearUnreadCountByTypes([1, 2])
  // Update UI with success message.
} catch (err) {
  // Handle error with err.code
}

鸿蒙

TypeScriptlet conversationTypes:V2NIMConversationType[] = [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
try {
await this.conversationService.clearUnreadCountByTypes(conversationTypes)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.clearUnreadCountByTypes(conversationTypes)

标记会话已读

标记会话已读

调用 markConversationRead 方法标记指定会话已读。当前只支持 P2P，高级群，超大群会话类型。

标记成功后，会触发 onConversationReadTimeUpdated 回调，返回标记已读的时间戳。SDK 会同步数据库和缓存。

示例代码：

安卓

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')

Node.js/Electron

TypeScriptconst time = await v2.conversationService.markConversationRead('conversation1')

鸿蒙

TypeScriptawait nim.conversationService.markConversationRead('sender|1|receiver')

Flutter

Dartawait NimCore.instance.conversationService.markConversationRead(conversationId)

获取会话已读时间戳

调用 getConversationReadTime 方法获取指定会话的已读时间戳。

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

示例代码：

安卓

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')

Node.js/Electron

TypeScriptconst time = await v2.conversationService.getConversationReadTime('conversation1')

鸿蒙

TypeScriptconst readTime = await nim.conversationService.getConversationReadTime('sender|1|receiver')

Flutter

Dartawait NimCore.instance.conversationService.getConversationReadTime(conversationId)

进阶功能

会话置顶

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

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

使用会话置顶功能前，您需要已开通 IM 套餐包并在网易云信控制台的 应用管理 > 产品功能 > IM 即时通讯 > 全局功能 路径下开通会话指定功能。
建议您在数据同步完成（收到 onSyncFinished 回调）后再进行该操作。

示例代码：

安卓

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
}

Node.js/Electron

TypeScripttry {
  await v2.conversationService.stickTopConversation('conversation1', true)
  // Success
} catch (err) {
  // handle error
}

鸿蒙

TypeScriptlet conversationId: string = "cjl|1|cjl1"
let stickTop: boolean = true;
try {
await this.conversationService.stickTopConversation(conversationId, stickTop)
// success
} catch (e) {
// fail
}

Flutter

Dartawait NimCore.instance.conversationService.stickTopConversation(conversationId, stickTop)

查询置顶会话

查询当前全量置顶的云端会话列表。

Android

JavaNIMClient.getService(V2NIMConversationService.class).getStickTopConversationList(
    new V2NIMSuccessCallback<List<V2NIMConversation>>() {
        @Override
        public void onSuccess(List<V2NIMConversation> conversationList) {
            // receive result
        }
    }, new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            int code = error.getCode();
            String desc = error.getDesc();
            // handle error
        }
    }
);

iOS

Objective-C[[NIMSDK sharedSDK].v2ConversationService getStickTopConversationList:^(NSArray<V2NIMConversation *> * _Nonnull conversationList) {
    // 获取成功
} failure:^(V2NIMError * _Nonnull error) {
    // 获取失败
}];

macOS/Windows

C++conversationService.getStickTopConversationList(
    [](const nstd::vector<V2NIMConversation>& conversationList) {
        // get stick top conversation list succeeded
    },
    [](V2NIMError error) {
        // get stick top conversation list failed, handle error
    });

Web/uni-app/小程序

TypeScripttry {
  const list = await nim.V2NIMConversationService.getStickTopConversationList()
  // receive result
} catch (err) {
  // handle error
}

Node.js/Electron

TypeScriptconst list = await v2.conversationService.getStickTopConversationList()

鸿蒙

TypeScripttry {
  const conversationList: V2NIMConversation[] = await nim.conversationService.getStickTopConversationList();
  // success
} catch (err) {
  // fail
}

Flutter

dartfinal result = await NimCore.instance.conversationService.getStickTopConversationList();

API	说明
`addConversationListener`	注册云端会话相关监听器
`removeConversationListener`	取消注册云端会话相关监听器
`subscribeUnreadCountByFilter`	订阅过滤后的会话未读数变化
`unsubscribeUnreadCountByFilter`	取消订阅过滤后的会话未读数变化
`createConversation`	创建一条空会话
`getConversationList`	获取会话列表
`getConversation`	获取单条会话
`getConversationListByOption`	获取指定会话列表
`getConversationListByIds`	根据会话 ID 批量获取会话列表
`updateConversation`	更新会话服务端扩展字段
`updateConversationLocalExtension`	更新指定会话的本地扩展字段
`deleteConversation`	删除一条会话
`deleteConversationListByIds`	根据会话 ID 批量删除会话列表
`getTotalUnreadCount`	获取全部会话的消息总未读数
`getUnreadCountByIds`	获取指定会话列表的消息总未读数
`getUnreadCountByFilter`	根据过滤参数获取相应的消息未读数
`clearTotalUnreadCount`	清空所有会话总的未读数
`clearUnreadCountByIds`	清空指定会话列表的消息总未读数
`clearUnreadCountByGroupId`	根据会话分组 ID 清除分组内所有会话的消息总未读数
`clearUnreadCountByTypes`	根据会话类型清除指定会话类型的所有未读数
`markConversationRead`	标记会话已读时间戳
`getConversationReadTime`	获取会话已读时间戳
`stickTopConversation`	置顶会话
`getStickTopConversationList`	查询当前置顶的全量云端会话列表

API	说明
`on("EventName")`	注册云端会话相关监听器
`off("EventName")`	取消注册云端会话相关监听器
`subscribeUnreadCountByFilter`	订阅过滤后的会话未读数变化
`unsubscribeUnreadCountByFilter`	取消订阅过滤后的会话未读数变化
`createConversation`	创建一条空会话
`getConversationList`	获取会话列表
`getConversation`	获取单条会话
`getConversationListByOption`	获取指定会话列表
`getConversationListByIds`	根据会话 ID 批量获取会话列表
`updateConversation`	更新会话服务端扩展字段
`updateConversationLocalExtension`	更新指定会话的本地扩展字段
`deleteConversation`	删除一条会话
`deleteConversationListByIds`	根据会话 ID 批量删除会话列表
`getTotalUnreadCount`	获取全部会话的消息总未读数
`getUnreadCountByIds`	获取指定会话列表的消息总未读数
`getUnreadCountByFilter`	根据过滤参数获取相应的消息未读数
`clearTotalUnreadCount`	清空所有会话总的未读数
`clearUnreadCountByIds`	清空指定会话列表的消息总未读数
`clearUnreadCountByGroupId`	根据会话分组 ID 清除分组内所有会话的消息总未读数
`clearUnreadCountByTypes`	根据会话类型清除指定会话类型的所有未读数
`markConversationRead`	标记会话已读时间戳
`getConversationReadTime`	获取会话已读时间戳
`stickTopConversation`	置顶会话
`getStickTopConversationList`	查询当前置顶的全量云端会话列表

API	说明
`listen`	注册云端会话相关监听器
`cancel`	取消注册云端会话相关监听器
`createConversation`	创建一条空会话
`deleteConversation`	删除一条会话
`deleteConversationListByIds`	批量删除会话列表
`getConversation`	获取单条会话
`getConversationList`	获取会话列表
`getConversationListByOption`	获取指定会话列表
`getConversationListByIds`	根据会话 ID 批量获取会话列表
`updateConversation`	更新会话服务端扩展字段
`updateConversationLocalExtension`	更新会话本地扩展字段
`stickTopConversation`	置顶会话
`getTotalUnreadCount`	获取全部会话的消息总未读数
`getUnreadCountByIds`	获取指定会话列表的消息总未读数
`getUnreadCountByFilter`	根据过滤参数获取相应的消息未读数
`clearTotalUnreadCount`	清空所有会话总的未读数
`clearUnreadCountByIds`	清空指定会话列表的消息总未读数
`clearUnreadCountByTypes`	根据会话类型清除指定会话类型的所有未读数
`subscribeUnreadCountByFilter`	订阅过滤后的会话未读数变化
`unsubscribeUnreadCountByFilter`	取消订阅过滤后的会话未读数变化
`markConversationRead`	标记会话已读时间戳
`getConversationReadTime`	获取会话已读时间戳
`clearUnreadCountByGroupId`	根据会话分组 ID 清除分组内所有会话的消息总未读数
`getStickTopConversationList`	查询当前置顶的全量云端会话列表

支持平台

技术原理

前提条件

监听会话相关事件

注册监听

移除监听

过滤监听

创建会话

获取会话

分页获取所有会话列表

获取指定单条会话

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

批量获取指定的会话列表

更新会话

更新会话本地扩展字段

删除会话

删除指定单条会话

批量删除指定会话列表

消息未读数

获取消息未读数

未读数清零

标记会话已读

进阶功能

会话置顶

查询置顶会话

相关信息

相关接口