会话管理 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

会话管理

更新时间： 2024/04/17 15:00:35

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

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

技术原理

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

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

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

前提条件

已实现登录 IM。

监听会话相关事件

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

Android/iOS/macOS/Windows

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

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

示例代码：

调用 addConversationListener 方法：

Android

javaNIMClient.getService(V2NIMConversationService.class).addConversationListener(new V2NIMConversationListener() {
@Override
public void onSyncStarted() {
     // Sync started
}

@Override
public void onSyncFinished() {
     // Sync finished
}

@Override
public void onSyncFailed(V2NIMError error) {
     // Sync failed
}

@Override
public void onConversationCreated(V2NIMConversation conversation) {
     // Conversation created
}

@Override
public void onConversationDeleted(List<String> conversationIds) {
     // Conversations deleted
}

@Override
public void onConversationChanged(List<V2NIMConversation> conversationList) {
     // Conversations changed
}

@Override
public void onTotalUnreadChanged(int unreadCount) {
     // Total unread count changed
}

@Override
public void onUnreadChangedByFilter(V2NIMConversationFilter filter, int unreadCount) {
     // Filter unread count changed
}
};
NIMClient.getService(V2NIMConversationService.class).addConversationListener(listener);

iOS

objective-c@interface V2ConversationServiceSample : NSObject <V2NIMConversationListener>

@end

@implementation V2ConversationServiceSample

- (void)onSyncStarted
{
// Sync started
}

- (void)onSyncFinished
{
// Sync finished
}

- (void)onSyncFailed:(V2NIMError *)error
{
// Sync failed
}

- (void)onConversationCreated:(V2NIMConversation *)conversation
{
// Conversation created
}

- (void)onConversationDeleted:(NSArray<NSString *> *)conversationIds
{
// Conversations deleted
}

- (void)onConversationChanged:(NSArray<V2NIMConversation *> *)conversations
{
// Conversations changed
}

- (void)onTotalUnreadCountChanged:(NSInteger)unreadCount
{
// Total unread count changed
}

- (void)onUnreadCountChangedByFilter:(V2NIMConversationFilter *)filter
                         unreadCount:(NSInteger)unreadCount
{
// Filter unread count changed
}

- (void)addConversationListener
{
[NIMSDK.sharedSDK.v2ConversationService addConversationListener:self];
}

@end

macOS/Windows

cppV2NIMConversationListener listener;
listener.onSyncStarted = []() {
// handle conversation sync start event
};
listener.onSyncFinished = []() {
// handle conversation sync finish event
};
listener.onSyncFailed = [](V2NIMError error) {
// handle conversation sync failed event
};
listener.onConversationCreated = [](V2NIMConversation conversation) {
// handle conversation created event
};
listener.onConversationDeleted = [](nstd::string conversationId) {
// handle conversation deleted event
};
listener.onConversationChanged = [](V2NIMConversationList conversationList) {
// handle conversation changed event
};
listener.onTotalUnreadChanged = [](uint32_t unreadCount) {
// handle total unread count changed event
};
listener.onUnreadChangedByFilter = [](V2NIMConversationFilter filter, uint32_t unreadCount) {
// handle unread count changed by group event
};
conversationService.addConversationListener(listener);

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

Android

javaNIMClient.getV2NIMConversationServcie().removeConversationListener(listener);

iOS

objective-cid<V2NIMConversationListener> listener;
[NIMSDK.sharedSDK.v2ConversationService removeConversationListener:listener];

macOS/Windows

cppV2NIMConversationListener listener;
conversationService.removeConversationListener(listener);

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

Android

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

iOS

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

macOS/Windows

cppV2NIMConversationFilter filter;
filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
conversationService.subscribeUnreadCountByFilter(filter);

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

Android

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

iOS

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

macOS/Windows

cppV2NIMConversationFilter filter;
filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
conversationService.unsubscribeUnreadCountByFilter(filter);

Web/uni-app/小程序/Harmony

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

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

示例代码：

Web/uni-app/小程序

typescriptnim.V2NIMConversationService.on("onSyncStarted", function () {})
nim.V2NIMConversationService.on("onSyncFinished", function () {})
nim.V2NIMConversationService.on("onSyncFailed", function (err) {})
nim.V2NIMConversationService.on("onConversationCreated", function (conversation:    V2NIMConversation) {})
nim.V2NIMConversationService.on("onConversationDeleted", function (conversationIds:     string[]) {})
nim.V2NIMConversationService.on("onConversationChanged", function (conversationList:    V2NIMConversation[]) {})
nim.V2NIMConversationService.on("onTotalUnreadChanged", function (unreadCount: number)  {})
nim.V2NIMConversationService.on("onUnreadChangedByFilter", function (filter:    V2NIMConversationFilter & { equals: (filter: V2NIMConversationFilter) => boolean },    unreadCount: number) {
  // Success
  // if filter.equals(TARGET_FILTER)
})

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

typescriptnim.V2NIMConversationService.off("onSyncStarted")
nim.V2NIMConversationService.off("onSyncFinished")
nim.V2NIMConversationService.off("onSyncFailed")
nim.V2NIMConversationService.off("onConversationCreated")
nim.V2NIMConversationService.off("onConversationDeleted")
nim.V2NIMConversationService.off("onConversationChanged")
nim.V2NIMConversationService.off("onTotalUnreadChanged")
nim.V2NIMConversationService.off("onUnreadChangedByFilter")

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

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

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

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

Harmony

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

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

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

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

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

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

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

创建会话

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID 组成方式：用户账号（accid）\|会话类型（`V2NIMConversationType`）\|聊天对象账号（accid）或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法，则返回 191004 参数错误。不可设置为空，否则也返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	创建会话成功回调，返回 `V2NIMConversation`。
`failure`	`V2NIMFailureCallback`	是	-	创建会话失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID 组成方式：用户账号（accid）\|会话类型（`V2NIMConversationType`）\|聊天对象账号（accid）或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法，则返回 191004 参数错误。不可设置为空，否则也返回 191004 参数错误。
`success`	`V2NIMConversationCallback`	是	-	创建会话成功回调，可自定义。
`failure`	`V2NIMFailureCallback`	是	-	创建会话失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID 组成方式：用户账号（accid）\|会话类型（`V2NIMConversationType`）\|聊天对象账号（accid）或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法，则返回 191004 参数错误。不可设置为空，否则也返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	创建会话成功回调，返回 `V2NIMConversation`。
`failure`	`V2NIMFailureCallback`	是	-	创建会话失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID 组成方式：用户账号（accid）\|会话类型（`V2NIMConversationType`）\|聊天对象账号（accid）或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法，则返回 191004 参数错误。不可设置为空，否则也返回 191004 参数错误。

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID 组成方式：用户账号（accid）\|会话类型（`V2NIMConversationType`）\|聊天对象账号（accid）或群组 ID。如果未按照该方式组成会话 ID 或组成参数不合法，则返回 191004 参数错误。不可设置为空，否则也返回 191004 参数错误。

示例代码：

Android

javaString conversationId = V2NIMConversationIdUtil.p2pConversationId("accountId");
NIMClient.getService(V2NIMConversationService.class).createConversation (conversationId, new V2NIMSuccessCallback<V2NIMConversation>(){
    @Override
    public void onSuccess(V2NIMConversation conversation){
        // conversation created
    }
}, new V2NIMFailureCallback(){
    @Override
    public void onFailure(V2NIMError error){
        int code = error.getCode();
        String desc = error.getDesc();
        // create failed, handle error
    }
});

iOS

objective-cNSString *conversationId = [V2NIMConversationIdUtil p2pConversationId:@"accountId"];
[NIMSDK.sharedSDK.v2ConversationService createConversation:conversationId success:^(V2NIMConversation *conversation) {
    // conversation created
} failure:^(V2NIMError *error) {
    // create failed, handle error
}];

macOS/Windows

cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
conversationService.createConversation(
    conversationId,
    [](V2NIMConversation conversation) {
        // create succeeded
    },
    [](V2NIMError error) {
        // create failed, handle error
    });

Web/uni-app/小程序

typescripttry {
  const data = await nim.V2NIMConversationService.createConversation("CONVERSATION_ID");
  // conversation created
} catch (err) {
  // create failed, handle error
}

Harmony

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

获取会话

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

分页获取所有会话列表

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`offset`	Long	是	-	分页偏移。首次调用传 0，后续调用时传入一次调用返回的 `offset`。
`limit`	Int	是	-	单次查询会话数量上限，建议不超过 100设置为小于或等于 0 则默认为 100。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMConversationResult`。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`offset`	Long	是	-	分页偏移。首次调用传 0，后续调用时传入一次调用返回的 `offset`。
`limit`	NSInteger	是	-	单次查询会话数量上限，建议不超过100。设置为小于或等于 0 则默认为 10。
`success`	`V2NIMConversationResultCallback`	是	-	查询话列表成功回调，可自定义。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`offset`	uint64_t	是	-	分页偏移。首次调用传 0，后续调用传入上一次调用返回的 `offset`。
`limit`	uint32_t	是	-	单次查询会话数量上限，建议不超过100。设置为小于或等于 0 则默认为 10。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMConversationResult`。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`offset`	Number	是	-	分页偏移。首次调用传 0，后续调用时传上一次调用返回的 `offset`。
`limit`	Number	是	-	单次查询会话数量上限，建议不超过 10。设置为小于或等于 0 则默认为 10。

Harmony

参数名称	类型	是否必填	默认值	描述
`offset`	Number	是	-	分页偏移。首次调用传 0，后续调用时传上一次调用返回的 `offset`。
`limit`	Number	是	-	单次查询会话数量上限，建议不超过 10。设置为小于或等于 0 则默认为 10。

示例代码：

Android

javaNIMClient.getV2NIMConversationServcie().getConversionList(0, 100, new V2NIMSuccessCallback<V2NIMConversationResult>() {
    @Override
    public void onSuccess(V2NIMConversationResult result) {
        // success     
    }    
}, new V2NIMFailueCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        int code = error.code;
        String desc = error.desc;
        // handle error
    }   
});

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService getConversationList:0 limit:10 success:^(V2NIMConversationResult *result) {
    // receive result
} failure:^(V2NIMError *error) {
    // handle error
}];

macOS/Windows

cppconversationService.getConversationList(
    lastCursor,
    10,
    [](V2NIMConversationResult result) {
        // get conversation list succeeded
    },
    [](V2NIMError error) {
        // get conversation list failed, handle error
    });

Web/uni-app/小程序

typescripttry {
const result = await nim.V2NIMConversationService.getConversationList(0, 100)
// receive result
} catch (err) {
// handle error
}

Harmony

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

获取指定单条会话

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMConversation`。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationId`	NSString	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`success`	`V2NIMConversationCallback`	是	-	查询会话成功回调，可自定义。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMConversation`。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。	查询失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。

示例代码：

Android

javaNIMClient.getV2NIMConversationServcie().getConversation("会话id", new V2NIMSuccessCallback<V2NIMConversation>(){
    @Override
    public void onSuccess(V2NIMConversation conversation){
        // success    
    }    
}, new V2NIMFailueCallback(){
    @Override
    public void onFailure(V2NIMError error){
        int code = error.getCode();
        String desc = error.getDesc();
        // handle error
    }   
});

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService getConversation:@"conversationId" success:^(V2NIMConversation *conversation) {
    // success
} failure:^(V2NIMError *error) {
    // handle error
}];

macOS/Windows

cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
conversationService.getConversation(
    conversationId,
    [](V2NIMConversation conversation) {
        // get conversation succeeded
    },
    [](V2NIMError error) {
        // get conversation failed, handle error
    });

Web/uni-app/小程序

typescripttry {
const data = await nim.V2NIMConversationService.getConversation("TARGET_CONVERSATION_ID")
// success
} catch (err) {
// handle error
}

Harmony

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

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

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`offset`	Long	是	-	分页偏移。首次调用传 0，后续调用时传入上一次调用返回的 `offset`。
`limit`	Int	是	-	单次查询会话数量上限，建议不超过 100。设置为小于或等于 0 则默认为 10
`option`	`V2NIMConversationOption`	是	-	查询条件，设置为空则查询所有会话列表。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMConversationResult`。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`offset`	Long	是	-	分页偏移。首次调用传 0，后续调用时传入上一次调用返回的 `offset`。
`limit`	NSInteger	是	-	单次查询会话数量上限，建议不超过 100。设置为小于或等于 0 则默认为 10
`option`	`V2NIMConversationOption`	是	-	查询条件，设置为空则查询所有会话列表。
`success`	`V2NIMConversationResultCallback`	是	-	查询会话列表成功回调，可自定义。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`offset`	uint64_t	是	-	分页偏移。首次调用传 0，后续调用时传入上一次调用返回的 `offset`。
`limit`	uint32_t	是	-	单次查询会话数量上限，建议不超过 100。设置为小于或等于 0 则默认为 10
`option`	`V2NIMConversationOption`	是	-	查询条件，设置为空则查询所有会话列表。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMConversationResult`。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`offset`	Number	是	-	分页偏移。首次调用传 0，后续调用时传入上一次调用返回的 `offset`。
`limit`	Number	是	-	单次查询会话数量上限，建议不超过 100。设置为小于或等于 0 则默认为 10
`option`	`V2NIMConversationOption`	是	-	查询条件，设置为空则查询所有会话列表。

Harmony

参数名称	类型	是否必填	默认值	描述
`offset`	Number	是	-	分页偏移。首次调用传 0，后续调用时传入上一次调用返回的 `offset`。
`limit`	Number	是	-	单次查询会话数量上限，建议不超过 100。设置为小于或等于 0 则默认为 10
`option`	`V2NIMConversationOption`	是	-	查询条件，设置为空则查询所有会话列表。

示例代码：

Android

javaV2NIMConversationOption option = new V2NIMConversationOption();
List<Integer> conversionTypes = new ArrayList<Integer>();
conversionTypes.add(1);
options.setConversionTypes =conversionTypes;
option.onlyUnread = true; 
NIMClient.getV2NIMConversationServcie().getConversionListByOption(0, 100,option, new      V2NIMSuccessCallback<V2NIMConversationResult>>(){
    @Override
    public void onSuccess<V2NIMConversationResult>(V2NIMConversationResult result){
        // receive result     
    }    
}, new V2NIMFailueCallback(){
    @Override
    public void onFailure(V2NIMError error){
        int code = error.code;
        String desc = error.desc;
        // handle error
    }   
});

iOS

objective-cV2NIMConversationOption *option = [[V2NIMConversationOption alloc] init];
option.conversationTypes = @[
    @(V2NIM_CONVERSATION_TYPE_P2P),
    @(V2NIM_CONVERSATION_TYPE_TEAM),
];
option.conversationGroupIds = @[
    @"groupIdA",
    @"groupIdB",
];
option.onlyUnread = YES;
[NIMSDK.sharedSDK.v2ConversationService getConversationListByOption:0 limit:10 option:option success:^(V2NIMConversationResult *  result) {
    // receive result
} failure:^(V2NIMError * error) {
    // handle error
}];

macOS/Windows

cppV2NIMConversationOption option;
option.onlyUnread = true;
option.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
conversationService.getConversationListByOption(
    lastCursor,
    10,
    option,
    [](V2NIMConversationResult result) {
        // get conversation list succeeded
    },
    [](V2NIMError error) {
        // get conversation list failed, handle error
    });

Web/uni-app/小程序

typescripttry {
const list = await nim.V2NIMConversationService.getConversationListByOption(0, 100, {
    conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
    onlyUnread: true,
})
// Success
} catch (err) {
// handle error
}

Harmony

typescriptlet offset: number = 0;
let limit: number = 100;
let option: V2NIMConversationOption = {
conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
}

try {
let result: V2NIMConversationResult = await this.conversationService.getConversationListByOption(offset, limit, option)
// success
} catch (e) {
// fail
}

批量获取指定的会话列表

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationIds`	List	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 List<`V2NIMConversation`>。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationIds`	NSString	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。
`success`	`V2NIMConversationListCallback`	是	-	查询成功回调，可自定义。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	查询会话列表成功回调，返回 List<`V2NIMConversation`>。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationIds`	string[]	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationIds`	string[]	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。

示例代码：

Android

javaNIMClient.getService(V2NIMConversationService.class).getConversationListByIds(ids, new    V2NIMSuccessCallback<List<V2NIMConversation>>() {
    @Override
    public void onSuccess(List<V2NIMConversation> conversations) {
        // receive conversation list
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        int code = error.getCode();
        String desc = error.getDesc();
        // handle error
    }
});

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService getConversationListByIds:@[@"conversationIdA", @"conversationIdB"] success:^    (NSArray<V2NIMConversation *> *conversationList) {
    // receive conversation list
} failure:^(V2NIMError *error) {
    // handle error
}];

macOS/Windows

cppauto conversationIds = nstd::vector<nstd::string>();
conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account1"));
conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account2"));
conversationService.getConversationListByIds(
    conversationIds,
    [](V2NIMConversationList list) {
        // get conversation list succeeded
    },
    [](V2NIMError error) {
        // get conversation list failed, handle error
    });

Web/uni-app/小程序

typescripttry {
const ids = ["ID1", "ID2"]
const list = await nim.V2NIMConversationService.getConversationListByIds(ids)
// receive conversation list
} catch (err) {
// handle error
}

Harmony

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

更新会话扩展字段

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`updateInfo`	`V2NIMConversationUpdate`	是	-	会话更新对象，包括本地扩展字段以及服务端扩展字段：本地扩展字段，不会多端同步服务器扩展字段，会多端同步
`success`	`V2NIMSuccessCallback`	是	-	更新会话成功回调
`failure`	`V2NIMFailureCallback`	是	-	更新会话失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`updateInfo`	`V2NIMConversationUpdate`	是	-	会话更新对象，包括本地扩展字段以及服务端扩展字段：本地扩展字段，不会多端同步服务器扩展字段，会多端同步
`success`	`V2NIMSuccessCallback`	是	-	更新会话成功回调
`failure`	`V2NIMFailureCallback`	是	-	更新会话失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`updateInfo`	`V2NIMConversationUpdate`	是	-	会话更新对象，包括本地扩展字段以及服务端扩展字段：本地扩展字段，不会多端同步服务器扩展字段，会多端同步
`success`	`V2NIMSuccessCallback`	是	-	更新会话成功回调
`failure`	`V2NIMFailureCallback`	是	-	更新会话失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`updateInfo`	`V2NIMConversationUpdate`	是	-	会话更新对象，包括本地扩展字段以及服务端扩展字段：本地扩展字段，不会多端同步服务器扩展字段，会多端同步

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`updateInfo`	`V2NIMConversationUpdate`	是	-	会话更新对象，包括本地扩展字段以及服务端扩展字段：本地扩展字段，不会多端同步服务器扩展字段，会多端同步

示例代码：

Android

javaV2NIMConversationUpdate updateInfo = new V2NIMConversationUpdate();
updateInfo.setServerExtension("serverextension");
updateInfo.setLocalExtension("localextension");
NIMClient.getService(V2NIMConversationService.class).updateConversation ("conversationId", updateInfo, new     V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void unused) {
        // success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        int code = error.getCode();
        String desc = error.getDesc();
        // handle error
    }
});

iOS

objective-cV2NIMConversationUpdate *info = [[V2NIMConversationUpdate alloc] init];
info.localExtension = @"localExtension";
info.serverExtension = @"serverExtension";
[NIMSDK.sharedSDK.v2ConversationService updateConversation:@"conversationId"    updateInfo:info success:^{
    // success
} failure:^(V2NIMError *error) {
    // handle error
}];

macOS/Windows

cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
V2NIMConversationUpdate param;
param.extension = "extension";
conversationService.updateConversation(
    conversationId,
    param,
    []() {
        // update succeeded
    },
    [](V2NIMError error) {
        // update failed, handle error
    });

Web/uni-app/小程序

typescripttry {
const params = { serverExtention: "This is a new text" }
await nim.V2NIMConversationService.updateConversation("CONVERSATION_ID", params)
// Success
} catch (err) {
// handle error
}

Harmony

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

删除会话

删除指定单条会话

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

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

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`clearMessage`	Boolean	否	false	是否同步删除会话中本地和服务端的历史消息删除本地和服务端的历史消 / li> 只删除会话，保留历史消息。
`success`	`V2NIMSuccessCallback`	是	-	删除会话成功回调
`failure`	`V2NIMFailureCallback`	是	-	删除会话失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空或不存在则返回 191004 参数错误。
`clearMessage`	Bool	否	false	是否同步删除会话对应的历史消息删除历史消息。只删除会话，保消息。
`success`	`V2NIMSuccessCallback`	是	-	删除会话成功回调
`failure`	`V2NIMFailureCallback`	是	-	删除会话失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空或不存在则返回 191004 参数错误。
`clearMessage`	Bool	否	false	是否同步删除会话对应的历史消息删除历史消息。只删除会话，保史消息。
`success`	`V2NIMSuccessCallback`	是	-	删除会话成功回调
`failure`	`V2NIMFailureCallback`	是	-	删除会话失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空或不存在则返回 191004 参数错误。
`clearMessage`	Boolean	否	false	是否同步删除会话对应的历史消息删除历史消息。只删除会话，保历史消息。

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空或不存在则返回 191004 参数错误。
`clearMessage`	Boolean	否	false	是否同步删除会话对应的历史消息删除历史消息。只删除会话，保历史消息。

示例代码：

Android

javaNIMClient.getService(V2NIMConversationService.class).deleteConversation("会话id", false, new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void unused) {
        // delete succeeded
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        int code = error.getCode();
        String desc = error.getDesc();
        // delete failed, handle error
    }
});

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService deleteConversation:@"conversationId" clearMessage:NO success:^{
    // delete succeeded
} failure:^(V2NIMError *error) {
    // delete failed, handle error
}];

macOS/Windows

cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
conversationService.deleteConversation(
    conversationId,
    true,
    []() {
        // delete succeeded
    },
    [](V2NIMError error) {
        // delete failed, handle error
    });

Web/uni-app/小程序

typescripttry {
await nim.V2NIMConversationService.deleteConversation("CONVERSATION_ID", true);
// delete succeeded
} catch (err) {
// delete failed, handle error
}

Harmony

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

批量删除指定会话列表

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

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

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationIds`	List	是	-	会话 ID 列表。不可为空，否则返回 191004 参数错误。单次删除上限为 100 条。
`clearMessage`	Boolean	否	false	是否同步删除会话对应的历史消息删除历史消息。只删除会话，保历史消息。
`success`	`V2NIMSuccessCallback`	是	-	删除会话成功回调，返回 `V2NIMConversationOperationResult`，仅包含删除失败的会话 ID 及相关错误码。
`failure`	`V2NIMFailureCallback`	是	-	删除会话失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationIds`	NSArray	是	-	会话 ID 列表。不可为空，否则返回 191004 参数错误。单次调用上限为 100 条。
`clearMessage`	Bool	否	false	是否同步删除会话对应的历史消息删除历史消息。只删除会话，保留历史消息。
`success`	`V2NIMConversationOperationResultListCallback`	是	-	删除会话成功回调，可自定义设置。
`failure`	`V2NIMFailureCallback`	是	-	删除会话失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String	是	-	会话 ID 列表。不可为空，否则返回 191004 参数错误。单次删除上限为 100 条。
`clearMessage`	Bool	否	false	是否同步删除会话对应的历史消息删除历史消息。只删除会话，保史消息。
`success`	`V2NIMSuccessCallback`	是	-	删除会话成功回调，返回 `V2NIMConversationOperationResult`，仅包含删除失败的会话 ID 及相关错误码
`failure`	`V2NIMFailureCallback`	是	-	删除会话失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String[]	是	-	会话 ID 列表。不可为空，否则返回 191004 参数错误。单次删除上限为 100 条。
`clearMessage`	Boolean	否	false	是否同步删除会话对应的历史消息删除历史消息。只删除会话，保历史消息。

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String[]	是	-	会话 ID 列表。不可为空，否则返回 191004 参数错误。单次删除上限为 100 条。
`clearMessage`	Boolean	否	false	是否同步删除会话对应的历史消息删除历史消息。只删除会话，保历史消息。

示例代码：

Android

javaNIMClient.getService(V2NIMConversationService.class).deleteConversationListByIds(ids, new      V2NIMSuccessCallback<List<V2NIMConversationOperationResult>>() {
    @Override
    public void onSuccess(List<V2NIMConversationOperationResult> results) {
        // delete succeeded, check failed conversation
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        int code = error.getCode();
        String desc = error.getDesc();
        // delete failed, handle error
    }
});

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService deleteConversationListByIds:@[@"conversationIdA", @"conversationIdB"] clearMessage:NO     success:^(NSArray<V2NIMConversationOperationResult *> *resultList) {
    if (resultList.count > 0) {
        // delete succeeded, check failed conversation
    }
} failure:^(V2NIMError *error) {
    // handle error
}];

macOS/Windows

cppauto conversationIds = nstd::vector<nstd::string>();
conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account1"));
conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account2"));
conversationService.deleteConversationListByIds(
    conversationIds,
    true,
    [](nstd::vector<V2NIMConversationOperationResult> failedList) {
        // delete succeeded, check failed conversation
    },
    [](V2NIMError error) {
        // delete failed, handle error
    });

Web/uni-app/小程序

typescripttry {
const ids = ["CONVERSATION_ID1", "CONVERSATION_ID2"]
await nim.V2NIMConversationService.deleteConversationListByIds(ids, true)
// delete succeeded, check failed conversation
} catch (err) {
// delete failed, handle error
}

Harmony

typescriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
let clearMessage: boolean = true;
try {
let deleteFailedConversationList: V2NIMConversationOperationResult[] = await this.conversationService.deleteConversationListByIds(conversationIds, clearMessage)
if (deleteFailedConversationList && deleteFailedConversationList.length > 0) {
    // partial success
} else {
    // all success
}
} catch (e) {
// fail
}

消息未读数

获取消息未读数

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

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

示例代码：

Android

javaint totalUnreadCount = NIMClient.getService(V2NIMConversationService.class).getTotalUnreadCount();

iOS

objective-cNSInteger count = [NIMSDK.sharedSDK.v2ConversationService getTotalUnreadCount];

macOS/Windows

cppauto totalUnreadCount = conversationService.getTotalUnreadCount();

Web/uni-app/小程序

typescriptconst count = nim.V2NIMConversationService.getTotalUnreadCount()

Harmony

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

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationIds`	List	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回指定会话列表的总未读数。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationIds`	NSArray	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。
`success`	`V2NIMConversationUnreadCountCallback`	是	-	获取会话未读数成功回调，可自定义。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回指定会话列表的总未读数。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String	是	-	会话 ID 列表，不可为空，否则返回 191004 参数错误。

示例代码：

Android

javaNIMClient.getService(V2NIMConversationService.class).getUnreadCountByIds(ids, new V2NIMSuccessCallback<Integer>(){
    @Override
    public void onSuccess(Integer count){
        // receive unread count
    }
},new V2NIMFailureCallback(){
    @Override
    public void onFailure(V2NIMError error){
        int code = error.getCode();
        String desc = error.getDesc();
        // handle error
    }
});

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService getUnreadCountByIds:@[@"conversationIdA", @"conversationIdB"] success:^(NSInteger    unreadCount) {
    // receive unread count
} failure:^(V2NIMError * _Nonnull error) {
    // handle error
}];

macOS/Windows

cppauto conversationIds = nstd::vector<nstd::string>();
conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account1"));
conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account2"));
conversationService.getUnreadCountByIds(
    conversationIds,
    [](uint32_t count) {
        // get unread count succeeded
    },
    [](V2NIMError error) {
        // get unread count failed, handle error
    });

Web/uni-app/小程序

typescripttry {
const counts = await nim.V2NIMConversationService.getUnreadCountByIds(["CONVERSATION_ID1", "CONVERSATION_ID2"]);    
} catch (err) {
    // Handle error
}

Harmony

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`filter`	`V2NIMConversationFilter`	是	-	过滤器配置，SDK会按照该参数配置进行滤，并返回过滤后的会话的消息总未读数。
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回过滤后的会话列表的总未读数。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`filter`	`V2NIMConversationFilter`	是	-	过滤器配置，SDK会按照该参数配置进行滤，并返回过滤后的会话的消息总未读数。
`success`	`V2NIMConversationUnreadCountCallback`	是	-	获取会话未读数成功回调，可自定义。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`filter`	`V2NIMConversationFilter`	是	-	过滤器配置，SDK会按照该参数配置进行滤，并返回过滤后的会话的消息总未读数。
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回过滤后的会话列表的总未读数。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`filter`	`V2NIMConversationFilter`	是	-	过滤器配置，SDK会按照该参数配置进行滤，并返回过滤后的会话的消息总未读数。

Harmony

参数名称	类型	是否必填	默认值	描述
`filter`	`V2NIMConversationFilter`	是	-	过滤器配置，SDK会按照该参数配置进行滤，并返回过滤后的会话的消息总未读数。

示例代码：

Android

javaV2NIMConversationFilter filter = new V2NIMConversationFilter();
List<V2NIMConversationType> conversionTypes = new ArrayList<>();
conversionTypes.add(V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
filter.setConversationTypes(conversionTypes);
filter.setConversationGroupId("会话分组id");
NIMClient.getService(V2NIMConversationService.class).getUnreadCountByFilter(filter, new V2NIMSuccessCallback<Integer>(){
    @Override
    public void onSuccess(Integer count){
        // receive unread count
    }
},new V2NIMFailureCallback(){
    @Override
    public void onFailure(V2NIMError error){
        int code = error.getCode();
        String desc = error.getDesc();
        // handle error
    }
});

iOS

objective-cV2NIMConversationFilter *filter = [[V2NIMConversationFilter alloc] init];
filter.conversationTypes = @[
    @(V2NIM_CONVERSATION_TYPE_P2P),
    @(V2NIM_CONVERSATION_TYPE_TEAM)
];
filter.conversationGroupId = @"groupId";
filter.ignoreMuted = YES;

[NIMSDK.sharedSDK.v2ConversationService getUnreadCountByFilter:filter
    success:^(NSInteger unreadCount) {
        // receive unread count
    }
    failure:^(V2NIMError * _Nonnull error) {
        // handle error
    }];

macOS/Windows

cppV2NIMConversationFilter filter;
filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
conversationService.getUnreadCountByFilter(
    filter,
    [](uint32_t count) {
        // get unread count succeeded
    },
    [](V2NIMError error) {
        // get unread count failed, handle error
    });

Web/uni-app/小程序

typescripttry {
// P2P type
const filter = { conversationTypes: [1] }
const counts = await nim.V2NIMConversationService.getUnreadCountByFilter(filter)
// receive unread count
} catch (err) {
// handle error
}

Harmony

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

未读数清零

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

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

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

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

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

参数说明：

Android

参数名称类型是否必填默认值描述

success V2NIMSuccessCallback 是 - 清零成功回调

failure V2NIMFailureCallback 是 - 清零失败回调，返回错误码。

iOS

参数名称类型是否必填默认值描述

success V2NIMSuccessCallback 是 - 清零成功回调

failure V2NIMFailureCallback 是 - 清零失败回调，返回错误码。

macOS/Windows

参数名称类型是否必填默认值描述

success V2NIMSuccessCallback 是 - 清零成功回调

failure V2NIMFailureCallback 是 - 清零失败回调，返回错误码。

Web/uni-app/小程序
无参数

Harmony
无参数

示例代码：

Android

javaNIMClient.getService(V2NIMConversationService.class).clearTotalUnreadCount(new V2NIMSuccessCallback<Void>(){
    @Override
    public void onSuccess(Void unused) {
        // success
    }
}, new V2NIMFailureCallback(){
    @Override
    public void onFailure(V2NIMError error){
        int code = error.getCode();
        String desc = error.getDesc();
        // handle error
    }
});

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService clearTotalUnreadCount:^{

} failure:^(V2NIMError * _Nonnull error) {
    // handle error
}];

macOS/Windows

cppconversationService.clearTotalUnreadCount(
    []() {
        // clear total unread count succeeded
    },
    [](V2NIMError error) {
        // clear total unread count failed, handle error
    });

Web/uni-app/小程序

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

Harmony

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

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

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationIds`	List	是	-	会话 ID 列表。会话 ID 列表。不可为空，否则返回 191004 参数错误。单次调用上限为 10 条。
`success`	`V2NIMSuccessCallback`	是	-	清零成功回调，返回 List<`V2NIMConversationOperationResult`>，仅包含清零失败的会话 ID 及相关错误码。
`failure`	`V2NIMFailureCallback`	是	-	清零失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationIds`	NSArray	是	-	会话 ID 列表。不可为空，否则返回 191004 参数错误。单次调用上限为 10 条。
`success`	`V2NIMConversationOperationResultListCallback`	是	-	清零成功回调，可自定义设置。
`failure`	`V2NIMFailureCallback`	是	-	清零失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String	是	-	会话 ID 列表。不可为空，否则返回 191004 参数错误。单次调用上限为 10 条。
`success`	`V2NIMSuccessCallback`	是	-	清零成功回调，返回 `V2NIMConversationOperationResult` 列表，仅包含清零失败的会话 ID 及相关错误码。
`failure`	`V2NIMFailureCallback`	是	-	清零失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String[]	是	-	会话 ID 列表。不可为空，否则返回 191004 参数错误。单次调用上限为 10 条。

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationIds`	String[]	是	-	会话 ID 列表。不可为空，否则返回 191004 参数错误。单次调用上限为 10 条。

示例代码：

Android

javaNIMClient.getService(V2NIMConversationService.class).clearUnreadCountByIds(ids, new V2NIMSuccessCallback<List<V2NIMConversationOperationResult>>(){
    @Override
    public void onSuccess(List<V2NIMConversationOperationResult> results){
        // check failed conversation
    }
}, new V2NIMFailureCallback(){
    @Override
    public void onFailure(V2NIMError error){
        int code = error.getCode();
        String desc = error.getDesc();
        // handle error
    }
});

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService clearUnreadCountByIds:@[@"conversationIdA", @"conversationIdB"] success:^(NSArray<V2NIMConversationOperationResult *> *resultList) {
    if (resultList.count > 0) {
        // check failed conversation
    }
} failure:^(V2NIMError * _Nonnull error) {
    // handle error
}];

macOS/Windows

cppauto conversationIds = nstd::vector<nstd::string>();
conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account1"));
conversationIds.emplace_back(V2NIMConversationId::p2pConversationId("account2"));
conversationService.clearUnreadCountByIds(
    conversationIds,
    [](nstd::vector<V2NIMConversationOperationResult> failedList) {
        // clear unread count succeeded
    },
    [](V2NIMError error) {
        // clear unread count failed, handle error
    });

Web/uni-app/小程序

typescripttry {
  await nim.V2NIMConversationService.clearUnreadCountByIds(["CONVERSATION_ID1", "CONVERSATION_ID2"])
  // Success
} catch (err) {
  // handle error
}

Harmony

typescriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
try {
  const deleteFailedConversationList: V2NIMConversationOperationResult[] = await this.conversationService.clearUnreadCountByIds(conversationIds)
  if (deleteFailedConversationList && deleteFailedConversationList.length > 0) {
    // partial success
  } else {
    // all success
  }
} catch (e) {
  // fail
}

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

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`groupId`	String	是	-	会话分组 ID。通过调用 createConversationGroup 获得。不可为空，否则返回 191004 错误码。
`success`	`V2NIMSuccessCallback`	是	-	清零成功回调
`failure`	`V2NIMFailureCallback`	是	-	清零失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`groupId`	String	是	-	会话分组 ID。通过调用 createConversationGroup 获得。不可为空，否则返回 191004 错误码。
`success`	`V2NIMSuccessCallback`	是	-	清零成功回调
`failure`	`V2NIMFailureCallback`	是	-	清零失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`groupId`	String	是	-	会话分组 ID。通过调用 createConversationGroup 获得。不可为空，否则返回 191004 错误码。
`success`	`V2NIMSuccessCallback`	是	-	清零成功回调
`failure`	`V2NIMFailureCallback`	是	-	清零失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`groupId`	String	是	-	会话分组 ID。通过调用 createConversationGroup 获得。不可为空，否则返回 191004 错误码。

Harmony

参数名称	类型	是否必填	默认值	描述
`groupId`	String	是	-	会话分组 ID。通过调用 createConversationGroup 获得。不可为空，否则返回 191004 错误码。

示例代码：

Android

javaNIMClient.getService(V2NIMConversationService.class).clearUnreadCountByGroupId("会话分组id",new V2NIMSuccessCallback<Void>(){
    @Override
    public void onSuccess(Void unused) {
        // success
    }
}, new V2NIMFailureCallback(){
    @Override
    public void onFailure(V2NIMError error){
        int code = error.getCode();
        String desc = error.getDesc();
        // handle error
    }
});

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService clearUnreadCountByGroupId:@"groupId" success:^{

        } failure:^(V2NIMError * _Nonnull error) {
            // handle error
        }];

macOS/Windows

cppconversationService.clearUnreadCountByGroupId(
    "groupId",
    []() {
        // clear unread count succeeded
    },
    [](V2NIMError error) {
        // clear unread count failed, handle error
    });

Web/uni-app/小程序

typescripttry {
await nim.V2NIMConversationService.clearUnreadCountByGroupId('GROUP_ID')
// Success
} catch (err) {
// handle error
}

Harmony

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

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

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationTypes`	List<`V2NIMConversationType`>	是	-	会话类型
`success`	`V2NIMSuccessCallback`	是	-	清零成功回调
`failure`	`V2NIMFailureCallback`	是	-	清零失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationTypes`	NSArray<NSNumber >	是	-	会话类型
`success`	`V2NIMSuccessCallback`	是	-	清零成功回调
`failure`	`V2NIMFailureCallback`	是	-	清零失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationTypes`	List<`V2NIMConversationType`>	是	-	会话类型
`success`	`V2NIMSuccessCallback`	是	-	清零成功回调
`failure`	`V2NIMFailureCallback`	是	-	清零失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`types`	`V2NIMConversationType`[]	是	-	会话类型

Harmony

参数名称	类型	是否必填	默认值	描述
`types`	`V2NIMConversationType`[]	是	-	会话类型

示例代码：

Android

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

iOS

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

macOS/Windows

cppconversationService.clearUnreadCountByTypes(
    {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM},
    []() {
        // clear unread count succeeded
    },
    [](V2NIMError error) {
        // clear unread count failed, handle error
    });

Web/uni-app/小程序

typescripttry {
await nim.V2NIMConversationService.clearUnreadCountByTypes([1])
// Success
} catch (err) {
// handle error
}

Harmony

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

进阶功能

会话置顶

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

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

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

参数说明：

Android

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`stickTop`	Boolean	是	-	是否置顶会话。
`success`	`V2NIMSuccessCallback`	是	-	置顶会话成功回调
`failure`	`V2NIMFailureCallback`	是	-	置顶会话失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationId`	NSString	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`stickTop`	BOOL	是	-	是否置顶会话。
`success`	`V2NIMSuccessCallback`	是	-	置顶会话成功回调
`failure`	`V2NIMFailureCallback`	是	-	置顶会话失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`stickTop`	BOOL	是	-	是否置顶会话。
`success`	`V2NIMSuccessCallback`	是	-	置顶会话成功回调
`failure`	`V2NIMFailureCallback`	是	-	置顶会话失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`stickTop`	Boolean	是	-	是否置顶会话。

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
`stickTop`	Boolean	是	-	是否置顶会话。

示例代码：

Android

javaNIMClient.getService(V2NIMConversationService.class).stickTopConversation("会话id", true, new V2NIMSuccessCallback<Void>() {
        @Override
        public void onSuccess(Void unused) {
            // success
        }
    }, new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            int code = error.getCode();
            String desc = error.getDesc();
            // handle error
        }
    });

iOS

objective-c[NIMSDK.sharedSDK.v2ConversationService stickTopConversation:@"conversationId" stickTop:YES success:^{
    // success
} failure:^(V2NIMError *error) {
    // handle error
}];

macOS/Windows

cppauto conversationId = V2NIMConversationId::p2pConversationId("account1");
conversationService.stickTopConversation(
    conversationId,
    true,
    []() {
        // stick top succeeded
    },
    [](V2NIMError error) {
        // stick top failed, handle error
    });

Web/uni-app/小程序

typescripttry {
await nim.V2NIMConversationService.stickTopConversation("CONVERSATION_ID", true)
// Success
} catch (err) {
// handle error
}

Harmony

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

技术原理

前提条件

监听会话相关事件

创建会话

获取会话

分页获取所有会话列表

获取指定单条会话

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

批量获取指定的会话列表

更新会话扩展字段

删除会话

删除指定单条会话

批量删除指定会话列表

消息未读数

获取消息未读数

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

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

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

未读数清零

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

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

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

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

进阶功能

会话置顶

相关信息