云端会话管理
更新时间: 2024/08/28 15:21:25
云信 IM 支持云端会话管理功能,包括创建、更新、删除会话等基础操作,以及置顶会话等进阶操作。
本文介绍如何调用 NIM SDK 的接口实现云端会话管理。
技术原理
云信 IM 支持云端(服务端)会话,在服务器进行存储和维护,支持存储和查询用户全量的会话历史消息。服务端会话及未读数请参考 新版服务端 API-云端会话管理。
当用户发送消息时,SDK 会自动创建会话并更新最近会话列表,但在特定场景下需要您手动创建会话,例如:创建一个空会话占位。
SDK 会自动同步服务端数据,如果您注册了会话相关监听,数据同步开始和同步结束均有回调通知;如果数据同步已开始,建议您在数据同步结束后再进行会话其他操作;在新设备登录 IM 后,SDK 会根据当前的漫游、离线消息自动生成最近会话列表。
前提条件
监听会话相关事件
在进行会话相关操作前,您可以提前注册监听相关事件。注册成功后,当会话相关事件发生时,SDK 会触发对应回调通知。
Android/iOS/macOS/Windows
调用 addConversationListener
方法注册会话相关监听器,监听数据同步开始结束、会话创建、删除、变更及未读数变化等。
-
相关回调:
onSyncStarted
:数据同步开始回调。onSyncFinished
:数据同步结束回调。如果数据同步已开始,建议在数据同步结束后再进行其他会话操作。onSyncFailed
:数据同步失败回调。onConversationCreated
:会话成功创建回调。当本地端或多端同步创建会话成功时会触发该回调。onConversationDeleted
:主动删除会话回调。当本地端或多端同步删除会话成功时会触发该回调。onConversationChanged
:会话变更回调。当本地端或多端同步置顶会话、会话有新消息、主动更新会话成功时会触发该回调。onTotalUnreadCountChanged
:会话消息总未读数变更回调。onUnreadCountChangedByFilter
:过滤后的未读数变更回调。调用subscribeUnreadCountByFilter
方法订阅监听后,当会话过滤后的未读数变化时会返回该回调。onConversationReadTimeUpdated
:同一账号多端登录后的会话已读时间戳标记的回调。
-
示例代码:
调用
addConversationListener
方法:Androidjava
V2NIMConversationListener 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);
iOSobjective-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/Windowscpp
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
。Androidjava
NIMClient.getV2NIMConversationServcie().removeConversationListener(listener);
iOSobjective-c
id<V2NIMConversationListener> listener; [NIMSDK.sharedSDK.v2ConversationService removeConversationListener:listener];
macOS/Windowscpp
V2NIMConversationListener listener; conversationService.removeConversationListener(listener);
调用
subscribeUnreadCountByFilter
方法订阅过滤后的会话未读数变化监听:Androidjava
V2NIMConversationFilter 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 }
iOSobjective-c
V2NIMConversationFilter *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/Windowscpp
V2NIMConversationFilter filter; filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM}; conversationService.subscribeUnreadCountByFilter(filter);
如需取消订阅可调用
unsubscribeUnreadCountByFilter
方法:Androidjava
V2NIMError result = NIMClient.getService(V2NIMConversationService.class).unsubscribeUnreadCountByFilter(filter); if(result == null){ // success }else{ int code = result.getCode(); String desc = result.getDesc(); // handle error }
iOSobjective-c
V2NIMConversationFilter *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/Windowscpp
V2NIMConversationFilter 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
方法订阅监听后,当会话过滤后的未读数变化时会返回该回调。onConversationReadTimeUpdated
:同一账号多端登录后的会话已读时间戳标记的回调。
-
示例代码:
Web/uni-app/小程序typescript
nim.V2NIMConversationService.on("onSyncStarted", function () {}) nim.V2NIMConversationService.on("onSyncFinished", function () {}) nim.V2NIMConversationService.on("onSyncFailed", function (err) {}) nim.V2NIMConversationService.on("onConversationCreated", function (conversation: V2NIMConversation) {}) nim.V2NIMConversationService.on("onConversationDeleted", function (conversationIds: string[]) {}) nim.V2NIMConversationService.on("onConversationChanged", function (conversationList: V2NIMConversation[]) {}) nim.V2NIMConversationService.on("onTotalUnreadCountChanged", function (unreadCount: number) {}) nim.V2NIMConversationService.on("onUnreadCountChangedByFilter", function (filter: V2NIMConversationFilter & { equals: (filter: V2NIMConversationFilter) => boolean }, unreadCount: number) { // todo success // if filter.equals(TARGET_FILTER) })
如需移除会话相关监听,可调用
off("EventName")
。typescript
nim.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
方法订阅过滤后的会话未读数变化监听:typescript
const filter = { conversationTypes: [1] } nim.V2NIMConversationService.subscribeUnreadCountByFilter(filter)
如需取消订阅可调用
unsubscribeUnreadCountByFilter
方法:typescript
const filter = { conversationTypes: [1] } nim.V2NIMConversationService.unsubscribeUnreadCountByFilter(filter)
Harmonytypescript
nim.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")
。typescript
nim.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
方法订阅过滤后的会话未读数变化监听:typescript
const filter: V2NIMConversationFilter = { conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P] } try { this.conversationService.subscribeUnreadCountByFilter(filter) // success } catch (e) { // fail }
如需取消订阅可调用
unsubscribeUnreadCountByFilter
方法:typescript
const 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 参数错误。
- 组成方式: 用户账号 (accid)|会话类型(
-
示例代码:
Androidjava
String 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 } });
iOSobjective-c
NSString *conversationId = [V2NIMConversationIdUtil p2pConversationId:@"accountId"]; [NIMSDK.sharedSDK.v2ConversationService createConversation:conversationId success:^(V2NIMConversation *conversation) { // conversation created } failure:^(V2NIMError *error) { // create failed, handle error }];
macOS/Windowscpp
auto conversationId = V2NIMConversationId::p2pConversationId("account1"); conversationService.createConversation( conversationId, [](V2NIMConversation conversation) { // create succeeded }, [](V2NIMError error) { // create failed, handle error });
Web/uni-app/小程序typescript
try { const data = await nim.V2NIMConversationService.createConversation("CONVERSATION_ID"); // conversation created } catch (err) { // create failed, handle error }
Harmonytypescript
typescript 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。 -
示例代码:
Androidjava
NIMClient.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 } });
iOSobjective-c
[NIMSDK.sharedSDK.v2ConversationService getConversationList:0 limit:10 success:^(V2NIMConversationResult *result) { // receive result } failure:^(V2NIMError *error) { // handle error }];
macOS/Windowscpp
conversationService.getConversationList( lastCursor, 10, [](V2NIMConversationResult result) { // get conversation list succeeded }, [](V2NIMError error) { // get conversation list failed, handle error });
Web/uni-app/小程序typescript
try { const result = await nim.V2NIMConversationService.getConversationList(0, 100) // receive result } catch (err) { // handle error }
Harmonytypescript
try { 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 参数错误。 -
示例代码:
Androidjava
NIMClient.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 } });
iOSobjective-c
[NIMSDK.sharedSDK.v2ConversationService getConversation:@"conversationId" success:^(V2NIMConversation *conversation) { // success } failure:^(V2NIMError *error) { // handle error }];
macOS/Windowscpp
auto conversationId = V2NIMConversationId::p2pConversationId("account1"); conversationService.getConversation( conversationId, [](V2NIMConversation conversation) { // get conversation succeeded }, [](V2NIMError error) { // get conversation failed, handle error });
Web/uni-app/小程序typescript
try { const data = await nim.V2NIMConversationService.getConversation("TARGET_CONVERSATION_ID") // success } catch (err) { // handle error }
Harmonytypescript
let 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
是 - 查询条件,设置为空则查询所有会话列表。 -
示例代码:
Androidjava
V2NIMConversationOption 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 } });
iOSobjective-c
V2NIMConversationOption *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/Windowscpp
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/小程序typescript
try { const list = await nim.V2NIMConversationService.getConversationListByOption(0, 100, { conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P] onlyUnread: true, }) // Success } catch (err) { // handle error }
Harmonytypescript
let offset: number = 0; let limit: number = 100; let option: V2NIMConversationOption = { conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P] } try { let result: V2NIMConversationResult = await this.conversationService.getConversationListByOption(offset, limit, option) // success } catch (e) { // fail }
批量获取指定的会话列表
调用 getConversationListByIds
按照会话 ID 批量获取会话列表。
获取的会话列表结果中,置顶会话排首位。如有多个置顶会话,则按照时间顺序倒序展示。
如果数据同步已开始(收到 onSyncStarted
回调),建议您在数据同步完成(收到 onSyncFinished
回调)后再进行该操作,否则可能无法获取到完整的会话列表。
-
参数说明:
Android参数名称 类型 是否必填 默认值 描述 conversationIds
List 是 - 会话 ID 列表,不可为空,否则返回 191004 参数错误。 success
V2NIMSuccessCallback
是 - 查询成功回调,返回 List< V2NIMConversation
>。failure
V2NIMFailureCallback
是 - 查询失败回调,返回错误码。 iOS参数名称 类型 是否必填 默认值 描述 conversationIds
NSString 是 - 会话 ID 列表,不可为空,否则返回 191004 参数错误。 success
V2NIMConversationListCallback
是 - 查询成功回调,可自定义。 failure
V2NIMFailureCallback
是 - 查询失败回调,返回错误码。 macOS/Windows参数名称 类型 是否必填 默认值 描述 conversationIds
String 是 - 会话 ID 列表,不可为空,否则返回 191004 参数错误。 success
V2NIMSuccessCallback
是 - 查询会话列表成功回调,返回 List< V2NIMConversation
>。failure
V2NIMFailureCallback
是 - 查询失败回调,返回错误码。 Web/uni-app/小程序参数名称 类型 是否必填 默认值 描述 conversationIds
string[] 是 - 会话 ID 列表,不可为空,否则返回 191004 参数错误。 Harmony参数名称 类型 是否必填 默认值 描述 conversationIds
string[] 是 - 会话 ID 列表,不可为空,否则返回 191004 参数错误。 -
示例代码:
Androidjava
NIMClient.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 } });
iOSobjective-c
[NIMSDK.sharedSDK.v2ConversationService getConversationListByIds:@[@"conversationIdA", @"conversationIdB"] success:^ (NSArray<V2NIMConversation *> *conversationList) { // receive conversation list } failure:^(V2NIMError *error) { // handle error }];
macOS/Windowscpp
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/小程序typescript
try { const ids = ["ID1", "ID2"] const list = await nim.V2NIMConversationService.getConversationListByIds(ids) // receive conversation list } catch (err) { // handle error }
Harmonytypescript
let 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
是 - 会话更新对象,包括本地扩展字段以及服务端扩展字段: - 本地扩展字段,不会多端同步
- 服务器扩展字段,会多端同步
-
示例代码:
Androidjava
V2NIMConversationUpdate 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 } });
iOSobjective-c
V2NIMConversationUpdate *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/Windowscpp
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/小程序typescript
try { const params = { serverExtention: "This is a new text" } await nim.V2NIMConversationService.updateConversation("CONVERSATION_ID", params) // Success } catch (err) { // handle error }
Harmonytypescript
let 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 还会返回 onTotalUnreadCountChanged
和 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 是否同步删除会话对应的历史消息 - 删除历史消息。
- 只删除会话,保历 史消息。
-
示例代码:
Androidjava
NIMClient.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 } });
iOSobjective-c
[NIMSDK.sharedSDK.v2ConversationService deleteConversation:@"conversationId" clearMessage:NO success:^{ // delete succeeded } failure:^(V2NIMError *error) { // delete failed, handle error }];
macOS/Windowscpp
auto conversationId = V2NIMConversationId::p2pConversationId("account1"); conversationService.deleteConversation( conversationId, true, []() { // delete succeeded }, [](V2NIMError error) { // delete failed, handle error });
Web/uni-app/小程序typescript
try { await nim.V2NIMConversationService.deleteConversation("CONVERSATION_ID", true); // delete succeeded } catch (err) { // delete failed, handle error }
Harmonytypescript
let 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 还会返回 onTotalUnreadCountChanged
和 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 是否同步删除会话对应的历史消息 - 删除历史消息。
- 只删除会话,保历史消息。
-
示例代码:
Androidjava
NIMClient.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 } });
iOSobjective-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/Windowscpp
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/小程序typescript
try { const ids = ["CONVERSATION_ID1", "CONVERSATION_ID2"] await nim.V2NIMConversationService.deleteConversationListByIds(ids, true) // delete succeeded, check failed conversation } catch (err) { // delete failed, handle error }
Harmonytypescript
let conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"]; let clearMessage: boolean = true; try { let deleteFailedConversationList: V2NIMConversationOperationResult[] = await this.conversationService.deleteConversationListByIds(conversationIds, clearMessage) if (deleteFailedConversationList && deleteFailedConversationList.length > 0) { // partial success } else { // all success } } catch (e) { // fail }
消息未读数
获取消息未读数
获取全部会话消息总未读数
调用 getTotalUnreadCount
方法获取全部会话的消息总未读数。
如果数据同步已开始(收到 onSyncStarted
回调),建议您在数据同步完成(收到 onSyncFinished
回调)后再进行该操作,否则可能无法获取到完整会话数据。
示例代码:
javaint totalUnreadCount = NIMClient.getService(V2NIMConversationService.class).getTotalUnreadCount();
objective-cNSInteger count = [NIMSDK.sharedSDK.v2ConversationService getTotalUnreadCount];
cppauto totalUnreadCount = conversationService.getTotalUnreadCount();
typescriptconst count = nim.V2NIMConversationService.getTotalUnreadCount()
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 参数错误。 -
示例代码:
Androidjava
NIMClient.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 } });
iOSobjective-c
[NIMSDK.sharedSDK.v2ConversationService getUnreadCountByIds:@[@"conversationIdA", @"conversationIdB"] success:^(NSInteger unreadCount) { // receive unread count } failure:^(V2NIMError * _Nonnull error) { // handle error }];
macOS/Windowscpp
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/小程序typescript
try { const counts = await nim.V2NIMConversationService.getUnreadCountByIds(["CONVERSATION_ID1", "CONVERSATION_ID2"]); } catch (err) { // Handle error }
Harmonytypescript
let conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"]; try { const unreadCount: number = await this.conversationService.getUnreadCountByIds(conversationIds) // success } catch (e) { // fail }
获取过滤后的会话消息总未读数
调用 getUnreadCountByFilter
方法按照会话 ID 列表获取指定会话列表的消息总未读数。
如果数据同步已开始(收到 onSyncStarted
回调),建议您在数据同步完成(收到 onSyncFinished
回调)后再进行该操作,否则可能无法获取到完整的会话数据。
-
参数说明:
Android参数名称 类型 是否必填 默认值 描述 filter
V2NIMConversationFilter
是 - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。 success
V2NIMSuccessCallback
是 - 获取成功回调,返回过滤后的会话列表的总未读数。 failure
V2NIMFailureCallback
是 - 获取失败回调,返回错误码。 iOS参数名称 类型 是否必填 默认值 描述 filter
V2NIMConversationFilter
是 - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。 success
V2NIMConversationUnreadCountCallback
是 - 获取会话未读数成功回调,可自定 义。 failure
V2NIMFailureCallback
是 - 获取失败回调,返回错误码。 macOS/Windows参数名称 类型 是否必填 默认值 描述 filter
V2NIMConversationFilter
是 - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。 success
V2NIMSuccessCallback
是 - 获取成功回调,返回过滤后的会话列表的总未读数。 failure
V2NIMFailureCallback
是 - 获取失败回调,返回错误码。 Web/uni-app/小程序参数名称 类型 是否必填 默认值 描述 filter
V2NIMConversationFilter
是 - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。 Harmony参数名称 类型 是否必填 默认值 描述 filter
V2NIMConversationFilter
是 - 过滤器配置,SDK会按照该参数配置进行滤,并返回过滤后的会话的消息总未读数。 -
示例代码:
Androidjava
V2NIMConversationFilter 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 } });
iOSobjective-c
V2NIMConversationFilter *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/Windowscpp
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/小程序typescript
try { // P2P type const filter = { conversationTypes: [1] } const counts = await nim.V2NIMConversationService.getUnreadCountByFilter(filter) // receive unread count } catch (err) { // handle error }
Harmonytypescript
let filter: V2NIMConversationFilter = { conversationTypes: [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P] } try { let unreadCount: number = await this.conversationService.getUnreadCountByFilter(filter) // success } catch (e) { // fail }
未读数清零
云信 IM 支持将会话内的消息未读数清零,即标记为已读。
将全部会话消息总未读数清零
调用 clearTotalUnreadCount
将应用内全部会话的消息总未读数清零。
清零成功后,SDK 返回 onTotalUnreadCountChanged
、onConversationChanged
和 onUnreadCountChangedByFilter
回调,并同步数据库和缓存。
建议您在数据同步完成(收到 onSyncFinished
回调)后再进行该操作。
-
参数说明:
Android参数名称 类型 是否必填 默认值 描述 success
V2NIMSuccessCallback
是 - 清零成功回调 failure
V2NIMFailureCallback
是 - 清零失败回调,返回错误码。 iOS参数名称 类型 是否必填 默认值 描述 success
V2NIMSuccessCallback
是 - 清零成功回调 failure
V2NIMFailureCallback
是 - 清零失败回调,返回错误码。 macOS/Windows参数名称 类型 是否必填 默认值 描述 success
V2NIMSuccessCallback
是 - 清零成功回调 failure
V2NIMFailureCallback
是 - 清零失败回调,返回错误码。 Web/uni-app/小程序无参数
Harmony无参数
-
示例代码:
Androidjava
NIMClient.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 } });
iOSobjective-c
[NIMSDK.sharedSDK.v2ConversationService clearTotalUnreadCount:^{ } failure:^(V2NIMError * _Nonnull error) { // handle error }];
macOS/Windowscpp
conversationService.clearTotalUnreadCount( []() { // clear total unread count succeeded }, [](V2NIMError error) { // clear total unread count failed, handle error });
Web/uni-app/小程序typescript
try { await nim.V2NIMConversationService.clearTotalUnreadCount() // Success } catch (err) { // handle error }
Harmonytypescript
try { await nim.V2NIMConversationService.clearTotalUnreadCount() // Success } catch (err) { // handle error }
将指定会话列表的消息未读数清零
调用 clearUnreadCountByIds
按照会话 ID 批量将指定会话列表的消息未读数清零。
清零成功后,SDK 返回清零失败的会话 ID 列表,并触发 onTotalUnreadCountChanged
、onConversationChanged
和 onUnreadCountChangedByFilter
回调,同步数据库和缓存。
建议您在数据同步完成(收到 onSyncFinished
回调)后再进行该操作。
- 参数说明:
参数名称 | 类型 | 是否必填 | 默认值 | 描述 |
---|---|---|---|---|
conversationIds |
List |
是 | - | 会话 ID 列表。 |
success |
V2NIMSuccessCallback |
是 | - | 清零成功回调,返回 List<V2NIMConversationOperationResult >,仅包含清零失败的会话 ID 及相关错误码。 |
failure |
V2NIMFailureCallback |
是 | - | 清零失败回调,返回错误码。 |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 |
---|---|---|---|---|
conversationIds |
NSArray |
是 | - | 会话 ID 列表。 |
success |
V2NIMConversationOperationResultListCallback |
是 | - | 清零成功回调,可自定义设置。 |
failure |
V2NIMFailureCallback |
是 | - | 清零失败回调,返回错误码。 |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 |
---|---|---|---|---|
conversationIds |
String | 是 | - | 会话 ID 列表。 |
success |
V2NIMSuccessCallback |
是 | - | 清零成功回调,返回 V2NIMConversationOperationResult 列表,仅包含清零失败的会话 ID 及相关错误码。 |
failure |
V2NIMFailureCallback |
是 | - | 清零失败回调,返回错误码。 |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 |
---|---|---|---|---|
conversationIds |
String[] | 是 | - | 会话 ID 列表。 |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 |
---|---|---|---|---|
conversationIds |
String[] | 是 | - | 会话 ID 列表。 |
- 示例代码:
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
}
});
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
}];
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
});
typescripttry {
await nim.V2NIMConversationService.clearUnreadCountByIds(["CONVERSATION_ID1", "CONVERSATION_ID2"])
// Success
} catch (err) {
// handle error
}
typescriptlet conversationIds: string[] = ["cjl|1|cjl1", "cjl|2|cjl2"];
try {
const deleteFailedConversationList: V2NIMConversationOperationResult[] = await this.conversationService.clearUnreadCountByIds(conversationIds)
if (deleteFailedConversationList && deleteFailedConversationList.length > 0) {
// partial success
} else {
// all success
}
} catch (e) {
// fail
}
将指定分组的会话消息未读数清零
调用 clearUnreadCountByGroupId
按照会话分组 ID 将指定分组的会话消息未读数清零。
清零成功后,SDK 返回 onTotalUnreadCountChanged
、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 错误码。 -
示例代码:
Androidjava
NIMClient.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 } });
iOSobjective-c
[NIMSDK.sharedSDK.v2ConversationService clearUnreadCountByGroupId:@"groupId" success:^{ } failure:^(V2NIMError * _Nonnull error) { // handle error }];
macOS/Windowscpp
conversationService.clearUnreadCountByGroupId( "groupId", []() { // clear unread count succeeded }, [](V2NIMError error) { // clear unread count failed, handle error });
Web/uni-app/小程序typescript
try { await nim.V2NIMConversationService.clearUnreadCountByGroupId('GROUP_ID') // Success } catch (err) { // handle error }
Harmonytypescript
let groupId: string = "0123456789" try { await this.conversationService.clearUnreadCountByGroupId(groupId) // success } catch (e) { // fail }
将指定类型的会话消息未读数清零
调用 clearUnreadCountByTypes
方法按照会话类型批量将指定类型的会话消息未读数清零。
清零成功后,SDK 返回 onTotalUnreadCountChanged
、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
[]是 - 会话类型 -
示例代码:
Androidjava
List<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 } });
iOSobjective-c
[NIMSDK.sharedSDK.v2ConversationService clearUnreadCountByTypes:@[ @(V2NIM_CONVERSATION_TYPE_P2P), @(V2NIM_CONVERSATION_TYPE_TEAM), ] success:^{ // success } failure:^(V2NIMError * _Nonnull error) { // handle error }];
macOS/Windowscpp
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/小程序typescript
try { await nim.V2NIMConversationService.clearUnreadCountByTypes([1]) // Success } catch (err) { // handle error }
Harmonytypescript
let conversationTypes:V2NIMConversationType[] = [V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P] try { await this.conversationService.clearUnreadCountByTypes(conversationTypes) // success } catch (e) { // fail }
标记会话已读
标记会话已读
调用 markConversationRead
方法标记指定会话已读。当前只支持 P2P,高级群,超大群会话类型。
标记成功后,会触发 onConversationReadTimeUpdated
回调,返回标记已读的时间戳。SDK 会同步本地数据库和缓存。
示例代码:
JavaString sessionId = "会话对象 ID";
V2NIMConversationType conversationType = V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P;
String conversationId = V2NIMConversationIdUtil.conversationId(sessionId, conversationType);
NIMClient.getService(V2NIMConversationService.class).markConversationRead(conversationId,
new V2NIMSuccessCallback<Long>() {
@Override
public void onSuccess(Long aLong) {
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
}
});
Objective-C- (void)markRead
{
[NIMSDK.sharedSDK.v2ConversationService markConversationRead:@"conversationId" success:^(NSTimeInterval timestamp) {
// result
} failure:^(V2NIMError * _Nonnull error) {
// error
}];
}
C++conversationService.markConversationRead(
"conversationId",
[]() {
// mark conversation read succeeded
},
[](V2NIMError error) {
// mark conversation read failed, handle error
)};
TypeScriptawait nim.V2NIMConversationService.markConversationRead('sender|1|receiver')
获取会话已读时间戳
调用 getConversationReadTime
方法获取指定会话的已读时间戳。
- 查询前请确保指定的会话已存在。
- 数据同步完成前,可能查询不到完整数据。
示例代码:
JavaString sessionId = "会话对象 ID";
V2NIMConversationType conversationType = V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P;
String conversationId = V2NIMConversationIdUtil.conversationId(sessionId, conversationType);
NIMClient.getService(V2NIMConversationService.class).getConversationReadTime(conversationId,
new V2NIMSuccessCallback<Long>() {
@Override
public void onSuccess(Long aLong) {
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
}
});
Objective-C- (void)getReadTime
{
[NIMSDK.sharedSDK.v2ConversationService getConversationReadTime:@"conversationId" success:^(NSTimeInterval timestamp) {
// result
} failure:^(V2NIMError * _Nonnull error) {
// error
}];
}
C++conversationService.getConversationReadTime(
"conversationId",
[](time_t readTime) {
// get conversation read time succeeded
},
[](V2NIMError error) {
// get conversation read time failed, handle error
)};
TypeScriptconst readTime = await nim.V2NIMConversationService.getConversationReadTime('sender|1|receiver')
进阶功能
会话置顶
调用 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 是 - 是否置顶会话。 -
示例代码:
Androidjava
NIMClient.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 } });
iOSobjective-c
[NIMSDK.sharedSDK.v2ConversationService stickTopConversation:@"conversationId" stickTop:YES success:^{ // success } failure:^(V2NIMError *error) { // handle error }];
macOS/Windowscpp
auto conversationId = V2NIMConversationId::p2pConversationId("account1"); conversationService.stickTopConversation( conversationId, true, []() { // stick top succeeded }, [](V2NIMError error) { // stick top failed, handle error });
Web/uni-app/小程序typescript
try { await nim.V2NIMConversationService.stickTopConversation("CONVERSATION_ID", true) // Success } catch (err) { // handle error }
Harmonytypescript
let conversationId: string = "cjl|1|cjl1" let stickTop: boolean = true; try { await this.conversationService.stickTopConversation(conversationId, stickTop) // success } catch (e) { // fail }