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

开发者中心

IM 即时通讯

集成开发

云端会话管理

更新时间： 2024/11/27 11:19:52

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

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

支持平台

本文内容适用的开发平台或框架如下表所示：

Android	iOS	macOS/Windows	Web/uni-app/小程序	Node.js/Electron	HarmonyOS	Flutter
✔️️️	✔️️️	✔️️️	✔️️️	✔️️️	✔️️	✔️️

技术原理

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

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

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

前提条件

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

已在网易云信控制台为应用开通 云端会话 开关。开启步骤请参考《控制台文档》配置应用。
已实现登录 IM。

监听会话相关事件

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

Android/iOS/macOS/Windows

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

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

示例代码：

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

JavaNIMClient.getV2NIMConversationServcie().removeConversationListener(listener);

iOS

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

macOS/Windows

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

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

Android

JavaV2NIMConversationFilter filter = new V2NIMConversationFilter();
List<V2NIMConversationType> conversionTypes = new ArrayList<>();
conversionTypes.add(V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
filter.setConversationTypes(conversionTypes);
filter.setConversationGroupId("会话分组 ID");
filter.setIgnoreMuted(true);
V2NIMError result = NIMClient.getService(V2NIMConversationService.class).subscribeUnreadCountByFilter(filter);
if(result == null){
    // success
}else{
    int code = result.getCode();
    String desc = result.getDesc();
    // handle error
}

iOS

Objective-CV2NIMConversationFilter *filter = [[V2NIMConversationFilter alloc] init];
filter.conversationTypes = @[
    @(V2NIM_CONVERSATION_TYPE_P2P),
    @(V2NIM_CONVERSATION_TYPE_TEAM),
];
filter.conversationGroupId = @"groupId";
filter.ignoreMuted = YES;
[NIMSDK.sharedSDK.v2ConversationService subscribeUnreadCountByFilter:filter];

macOS/Windows

C++V2NIMConversationFilter filter;
filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
conversationService.subscribeUnreadCountByFilter(filter);

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

Android

JavaV2NIMError result = NIMClient.getService(V2NIMConversationService.class).unsubscribeUnreadCountByFilter(filter);
if(result == null){
    // success
}else{
    int code = result.getCode();
    String desc = result.getDesc();
    // handle error
}

iOS

Objective-CV2NIMConversationFilter *filter = [[V2NIMConversationFilter alloc] init];
filter.conversationTypes = @[
    @(V2NIM_CONVERSATION_TYPE_P2P),
    @(V2NIM_CONVERSATION_TYPE_TEAM),
];
filter.conversationGroupId = @"groupId";
filter.ignoreMuted = YES;
[NIMSDK.sharedSDK.v2ConversationService unsubscribeUnreadCountByFilter:filter];

macOS/Windows

C++V2NIMConversationFilter filter;
filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
conversationService.unsubscribeUnreadCountByFilter(filter);

Web/uni-app/小程序/Node.js/Electron/HarmonyOS

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

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

示例代码：

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

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

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

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

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

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

TypeScriptconst filter = {
    conversationTypes: [1]
}
nim.V2NIMConversationService.unsubscribeUnreadCountByFilter(filter)

Node.js/Electron

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("onTotalUnreadCountChanged", function (unreadCount: number) {})
v2.conversationService.on("onUnreadCountChangedByFilter", function (filter: V2NIMConversationFilter & { equals: (filter: V2NIMConversationFilter) => boolean }, unreadCount: number) {
// Update UI with success message.
// if filter.equals(TARGET_FILTER)
})

如需移除会话相关监听，可调用 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")

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

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

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

TypeScriptconst filter = {
    conversationTypes: [1]
}
await v2.conversationService.unsubscribeUnreadCountByFilter(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) => {
// Update UI with success message.
// if filter.equals(TARGET_FILTER)
})

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

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

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

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

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

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

Flutter

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

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

示例代码：

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

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

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

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

Dartawait NimCore.instance.conversationService.subscribeUnreadCountByFilter(filter)

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

Dartawait NimCore.instance.conversationService.unsubscribeUnreadCountByFilter(filter)

创建会话

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

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

示例代码：

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
}

Node.js/Electron

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

HarmonyOS

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 回调）后再进行该操作，否则可能无法获取到全量完整会话列表。

示例代码：

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
}

Node.js/Electron

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

HarmonyOS

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 回调）后再进行该操作，否则可能无法获取到完整会话数据。

示例代码：

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
}

Node.js/Electron

TypeScripttry {
  const conversation = await v2.conversationService.getConversation('conversation1')
  // 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
}

Flutter

Dartawait NimCore.instance.conversationService.getConversation(conversationId)

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

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

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

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

示例代码：

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
}

Node.js/Electron

TypeScripttry {
  const result = await v2.conversationService.getConversationListByOption(0, 10, {
    conversationTypes: [1, 2]
  })
  // 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
}

Flutter

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

批量获取指定的会话列表

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

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

示例代码：

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
}

Node.js/Electron

TypeScripttry {
  const list = await v2.conversationService.getConversationListByIds(['conversation1', 'conversation2'])
  // 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
}

Flutter

Dartawait NimCore.instance.conversationService.getConversationListByIds(conversationIds)

更新会话

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

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

示例代码：

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 = { 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
}

HarmonyOS

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。

示例代码：

Android

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
}

HarmonyOS

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 回调）后再进行该操作。

示例代码：

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
}

Node.js/Electron

TypeScripttry {
  await v2.conversationService.deleteConversation('conversation1', 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
}

Flutter

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

批量删除指定会话列表

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

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

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

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

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

示例代码：

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
}

Node.js/Electron

TypeScripttry {
  const result = await v2.conversationService.deleteConversationListByIds(['conversation1', 'conversation2'], 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
}

Flutter

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

消息未读数

获取消息未读数

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

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

示例代码：

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

Node.js/Electron

TypeScriptconst count = await v2.conversationService.getTotalUnreadCount()

HarmonyOS

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

Flutter

Dartawait NimCore.instance.conversationService.getTotalUnreadCount()

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

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

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

示例代码：

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
}

Node.js/Electron

TypeScripttry {
  const count = await v2.conversationService.getUnreadCountByIds(['conversation1', 'conversation2'])
} 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
}

Flutter

Dartawait NimCore.instance.conversationService.getUnreadCountByIds(conversationIds)

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

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

示例代码：

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
}

Node.js/Electron

TypeScripttry {
  // P2P type
  const count = await v2.conversationService.getUnreadCountByFilter({ conversationTypes: [1, 2] })
  // 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
}

Flutter

Dartawait NimCore.instance.conversationService.getUnreadCountByFilter(filter)

未读数清零

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

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

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

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

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

示例代码：

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
}

Node.js/Electron

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

HarmonyOS

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

Flutter

Dartawait NimCore.instance.conversationService.clearTotalUnreadCount()

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

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

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

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

示例代码：

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
}

Node.js/Electron

TypeScripttry {
  const result = await v2.conversationService.clearUnreadCountByIds(['conversation1', 'conversation2'])
  // 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
}

Flutter

Dartawait NimCore.instance.conversationService.clearUnreadCountByIds(conversationIds)

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

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

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

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

示例代码：

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
}

Node.js/Electron

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

HarmonyOS

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

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

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

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

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

示例代码：

Android

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

iOS

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

macOS/Windows

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
}

HarmonyOS

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 会同步本地数据库和缓存。

示例代码：

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

Node.js/Electron

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

HarmonyOS

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

Flutter

Dartawait NimCore.instance.conversationService.markConversationRead(conversationId)

获取会话已读时间戳

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

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

示例代码：

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

Node.js/Electron

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

HarmonyOS

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

Flutter

Dartawait NimCore.instance.conversationService.getConversationReadTime(conversationId)

进阶功能

会话置顶

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

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

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

示例代码：

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
}

Node.js/Electron

TypeScripttry {
  await v2.conversationService.stickTopConversation('conversation1', 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
}

Flutter

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

涉及接口

Android/iOS/macOS/Windows

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`	置顶会话

Web/uni-app/小程序/Node.js/Electron/HarmonyOS

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`	根据会话类型清除指定本地会话类型的所有未读数
`stickTopConversation`	置顶会话

Flutter

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

此文档是否对你有帮助？

有帮助

去反馈

支持平台
技术原理
前提条件
监听会话相关事件
创建会话
获取会话
分页获取所有会话列表
获取指定单条会话
根据查询选项分页获取会话列表
批量获取指定的会话列表
更新会话
更新会话本地扩展字段
删除会话
删除指定单条会话
批量删除指定会话列表
消息未读数
获取消息未读数
未读数清零
标记会话已读
进阶功能
会话置顶
相关信息
涉及接口

支持平台

技术原理

前提条件

监听会话相关事件

创建会话

获取会话

分页获取所有会话列表

获取指定单条会话

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

批量获取指定的会话列表

更新会话

更新会话本地扩展字段

删除会话

删除指定单条会话

批量删除指定会话列表

消息未读数

获取消息未读数

未读数清零

标记会话已读

进阶功能

会话置顶

相关信息

涉及接口