开发者中心
IM 即时通讯
V10
知识库工单
中文
新手入门资源下载了解产品集成开发客户端 API服务端 API常见问题
输入关键词搜索
输入关键词搜索
在线咨询微信咨询电话咨询
API 概览
登录相关
会话相关
本地会话
云端会话
云端会话分组
消息相关
消息构建
消息操作
系统通知
群组相关
用户相关
用户状态订阅
好友关系
AI 数字人
系统设置
存储服务
聊天室
聊天室管理
聊天室消息构建
聊天室服务
聊天室队列服务
类/枚举
Flutter
登录相关
会话相关
本地会话
云端会话
云端会话分组
消息相关
消息构建
消息操作
系统通知
群组相关
用户相关
用户状态订阅
好友相关
AI 数字人
系统设置
存储服务
聊天室
聊天室管理
聊天室消息构建
聊天室服务
聊天室队列服务
类/枚举
错误码
信令
开发者中心IM 即时通讯客户端 API本地会话

本地会话

更新时间： 2025/07/28 17:22:05

网易云信即时通讯 SDK（NetEase IM SDK，以下简称 NIM SDK）支持本地会话管理功能，包括创建、更新、删除本地会话等基础操作，以及置顶会话等进阶操作。

本地会话列表由 SDK 维护并提供查询、监听变化的接口，当会话变更时，SDK 会自动更新会话列表并通知，您无需手动更新。

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

API 概览

本地会话监听

API 说明 起始版本
listen 注册本地会话相关监听 v10.6.0
cancel 取消注册本地会话相关监听 v10.6.0

本地会话操作

API 说明 起始版本
createConversation 创建一条空本地会话 v10.6.0
updateConversationLocalExtension 更新会话的本地扩展信息 v10.6.0
deleteConversation 删除一条本地会话 v10.6.0
deleteConversationListByIds 根据会话 ID 批量删除本地会话列表 v10.6.0
stickTopConversation 置顶会话 v10.6.0
getConversation 根据会话 ID 获取单条本地会话 v10.6.0
getConversationList 获取所有本地会话列表 v10.6.0
getConversationListByIds 根据会话 ID 批量获取本地会话列表 v10.6.0
getConversationListByOption 根据指定的筛选条件获取本地会话列表 v10.6.0
getStickTopConversationList 查询当前全量置顶的本地会话列表 v10.9.0

本地会话未读数

API 说明 起始版本
getTotalUnreadCount 获取全部本地会话的消息总未读数 v10.6.0
getUnreadCountByIds 根据会话 ID 获取指定本地会话的消息总未读数 v10.6.0
getUnreadCountByFilter 根据过滤参数获取相应的消息未读数 v10.6.0
clearTotalUnreadCount 清除所有本地会话的消息总未读数 v10.6.0
clearUnreadCountByIds 根据会话 ID 清除指定本地会话列表的消息未读数 v10.6.0
clearUnreadCountByTypes 根据会话类型清除指定本地会话类型的消息未读数 v10.6.0
subscribeUnreadCountByFilter 订阅指定过滤条件的本地会话消息未读数变化 v10.6.0
unsubscribeUnreadCountByFilter 取消订阅指定过滤条件的本地会话消息未读数变化 v10.6.0
markConversationRead 标记本地会话已读时间戳 v10.6.0
getConversationReadTime 获取本地会话已读时间戳 v10.6.0

接口类

V2NIMLocalConversationService 类提供创建、删除、更新、获取、置顶本地会话，本地会话消息未读数相关、注册本地会话监听等接口。

listen

接口描述

注册本地会话监听器。

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

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

回调事件

  • onSyncStarted：数据同步开始回调。建议在回调完成后操作数据，如果在此期间操作数据，会出现数据不全，只能操作部分数据的情况。
  • onSyncFinished：数据同步结束回调。此回调后需要用户重新获取本地会话列表。回调后可任意操作相关的本地会话数据。
  • onSyncFailed：数据同步失败回调。此回调后可以操作本地会话数据，但由于同步失败，本地只能操作已有数据，数据可能不全。在相关错误恢复后，SDK 会逐步按需重建会话数据。
  • onConversationCreated：本地会话创建回调，返回创建的本地会话对象。当本端或多端同步主动创建本地会话成功时会触发该回调。
  • onConversationDeleted：本地会话删除回调，返回被删除的本地会话 ID 列表。当本端或多端同步主动删除本地会话成功时会触发该回调。
  • onConversationChanged：本地会话变更回调，返回变更后的会话列表。当本端或多端同步调用会话置顶、免打扰、更新消息内容成功时会触发该回调。
  • onTotalUnreadCountChanged：本地会话消息总未读数变更回调，返回变更后的消息未读数。
  • onUnreadCountChangedByFilter：指定过滤条件的会话消息未读数变更，根据过滤条件返回变更后的消息未读数。
  • onConversationReadTimeUpdated：同一账号多端登录会话已读时间戳标记时间变更回调，返回同步标记的会话 ID 和标记的时间戳。

回调事件详细信息请参考 会话相关监听器。

示例代码

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

cancel

接口描述

取消注册本地会话相关监听。

该接口为同步接口。

示例代码

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

createConversation

接口描述

创建一条空本地会话。

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

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

适用场景

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

参数说明

DartFuture<NIMResult<NIMConversation>> createConversation( String conversationId )
参数名称 类型 是否必填 说明
conversationId String 是 本地会话 ID，通过调用 ConversationIdUtil 的对应函数创建。
  • 组成方式：用户账号（accountId）| 会话类型（NIMConversationType）| 聊天对象账号（accountId）或群组 ID。
  • 不可设置为空，否则返回 191004 参数错误。
    		•

    示例代码

    Dartawait NimCore.instance.localConversationService.createConversation(conversationId)

    返回值

    NIMResult<NIMConversation>：本地会话信息

    相关回调

    onConversationCreated：本地会话创建回调

    deleteConversation

    接口描述

    根据会话 ID 删除指定的本地会话。

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

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

    参数说明

    DartFuture<NIMResult<void>> deleteConversation( String conversationId, bool clearMessage )
    参数名称 类型 是否必填 说明
    conversationId String 是 会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
    clearMessage bool 否 是否删除本地会话对应的本地历史消息。
  • true：清空本地历史消息。
  • false：只删除本地会话，保留本地历史消息。
    • 默认值为 false。

    示例代码

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

    返回值

    NIMResult<void>

    相关回调

    • onConversationDeleted：本地会话删除回调
    • onTotalUnreadCountChanged：本地会话消息总未读数变更回调
    • onUnreadCountChangedByFilter：指定过滤条件的本地会话消息未读数变更回调

    deleteConversationListByIds

    接口描述

    根据会话 ID 批量删除指定的本地会话列表。

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

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

    参数说明

    DartFuture<NIMResult<List<NIMConversationOperationResult>>> deleteConversationListByIds( List<String> conversationIds, bool clearMessage )
    参数名称 类型 是否必填 说明
    conversationIds List<String> 是 会话 ID 列表。
  • 不可为空，否则返回 191004 参数错误。
  • 单次调用上限为 100 条。
    		•
    clearMessage bool 否 是否删除本地会话对应的本地历史消息。
  • true：清空本地历史消息。
  • false：只删除本地会话，保留本地历史消息。
    • 默认值为 false。

    示例代码

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

    返回值

    NIMResult<List<NIMConversationOperationResult>>：单条本地会话操作结果信息

    相关回调

    • onConversationDeleted：本地会话删除回调
    • onTotalUnreadCountChanged：本地会话消息总未读数变更回调
    • onUnreadCountChangedByFilter：指定过滤条件的本地会话消息未读数变更回调

    getConversation

    接口描述

    根据会话 ID 获取单条本地会话。

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

    参数说明

    DartFuture<NIMResult<NIMConversation>> getConversation( String conversationId )
    参数名称 类型 是否必填 说明
    conversationId String 是 会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。

    示例代码

    Dartawait NimCore.instance.localConversationService.getConversation(conversationId)

    返回值

    NIMResult<NIMConversation>：本地会话信息

    相关回调

    无

    getConversationList

    接口描述

    分页查询所有本地会话列表。

    该方法从客户端本地分页获取会话数据，本地历史会话数据无上限，因此建议分页多次获取，直到获取全量会话数据，SDK 会进行数据同步并返回对应回调通知 UI 层。

    • 查询的本地会话列表结果中，置顶会话排首位。
    • 数据同步完成前，可能查询不到完整数据或者查询到的是老数据。
    • 查询云端会话时，当正好查询完所有数据时，下次查询时才会提示查询完毕（finished = true）。但是查询本地会话时，当正好查询完所有本地数据时，当次查询时就会提示查询完毕（finished = true）。

    参数说明

    DartFuture<NIMResult<NIMConversationResult>> getConversationList( int offset, int limit )
    参数名称 类型 是否必填 说明
    offset int 是 分页偏移。首次调用传 0，后续调用时传入上一次调用返回的 offset。
    limit int 是 单次查询会话数量上限，建议不超过 100。设置为小于或等于 0 则默认为 100。

    示例代码

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

    返回值

    NIMResult<NIMConversationResult>：查询本地会话列表结果相关信息

    相关回调

    无

    getConversationListByOption

    接口描述

    根据指定的筛选条件分页查询本地会话列表。

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

    数据同步完成前，可能查询不到完整数据或者查询到的是老数据。

    参数说明

    DartFuture<NIMResult<NIMConversationResult>> getConversationListByOption(
  int offset,
  int limit, {
  NIMConversationOption? option,
  })
    参数名称 类型 是否必填 说明
    offset int 是 分页偏移。首次调用传 0，后续调用时传入上一次调用返回的 offset。
    limit int 是 单次查询会话数量上限，建议不超过 100。设置为小于或等于 0 则默认为 100。
    option NIMConversationOption 是 查询条件，设置为空则查询所有本地会话列表。

    示例代码

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

    返回值

    NIMResult<NIMConversationResult>：查询会话列表结果相关信息

    相关回调

    无

    getConversationListByIds

    接口描述

    根据会话 ID 批量查询指定的本地会话列表。

    数据同步完成前，可能查询不到完整数据或者查询到的是老数据。

    参数说明

    DartFuture<NIMResult<List<NIMConversation>>> getConversationListByIds( List<String> conversationIds )
    参数名称 类型 是否必填 说明
    conversationIds List<String> 是 会话 ID 列表，不可为空，否则返回 191004 参数错误。

    示例代码

    Dartawait NimCore.instance.localConversationService.getConversationListByIds(conversationIds)

    返回值

    NIMResult<List<NIMConversation>>：本地会话列表相关信息

    相关回调

    无

    updateConversationLocalExtension

    接口描述

    更新本地会话的本地扩展信息。

    本地扩展字段更新后，SDK 会返回会话变更回调 onConversationChanged，并同步更新缓存和数据库。

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

    参数说明

    DartFuture<NIMResult<void>> updateConversationLocalExtension( String conversationId, String localExtension )
    参数名称 类型 是否必填 说明
    conversationId String 是 会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
    localExtension String 是 更新本地会话本地扩展字段。

    示例代码

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

    返回值

    NIMResult<void>

    相关回调

    onConversationChanged：本地会话变更回调

    stickTopConversation

    接口描述

    置顶指定的本地会话。最多支持置顶 100 个本地会话。

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

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

    参数说明

    DartFuture<NIMResult<void>> stickTopConversation( String conversationId, bool stickTop )
    参数名称 类型 是否必填 说明
    conversationId String 是 会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。
    stickTop bool 是 是否置顶。

    示例代码

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

    返回值

    NIMResult<void>

    相关回调

    onConversationChanged：本地会话变更回调

    getStickTopConversationList

    接口描述

    查询当前全量置顶的本地会话列表。

    参数说明

    DartFuture<NIMResult<List<NIMConversation>>> getStickTopConversationList()

    示例代码

    Dartfinal result = await NimCore.instance.localConversationService.getStickTopConversationList();

    返回值

    NIMResult<List<NIMConversation>> 置顶的本地会话列表

    相关回调

    无

    getTotalUnreadCount

    接口描述

    获取所有本地会话的消息总未读数。

    • 数据同步完成前，可能查询不到完整数据或者查询到的是老数据。
    • 该接口为同步接口。

    参数说明

    DartFuture<NIMResult<int>> getTotalUnreadCount()

    无参数。

    示例代码

    Dartawait NimCore.instance.localConversationService.getTotalUnreadCount()

    返回值

    NIMResult<int>：全部会话的消息总未读数

    相关回调

    无

    getUnreadCountByIds

    接口描述

    根据会话 ID 获取指定本地会话列表的消息总未读数。

    返回的消息总未读数为所有合法会话的消息未读数的总和。

    数据同步完成前，可能查询不到完整数据或者查询到的是老数据。

    参数说明

    DartFuture<NIMResult<int>> getUnreadCountByIds( List<String> conversationIds )
    参数名称 类型 是否必填 说明
    conversationIds List<String> 是 会话 ID 列表，不可为空，否则返回 191004 参数错误。

    示例代码

    Dartawait NimCore.instance.localConversationService.getUnreadCountByIds(conversationIds)

    返回值

    NIMResult<int>：指定的本地会话列表的总未读数

    相关回调

    无

    getUnreadCountByFilter

    接口描述

    根据过滤条件获取过滤后的所有本地会话列表的消息总未读数。

    数据同步完成前，可能查询不到完整数据或者查询到的是老数据。

    参数说明

    DartFuture<NIMResult<int>> getUnreadCountByFilter( NIMConversationFilter filter )
    参数名称 类型 是否必填 说明
    filter NIMConversationFilter 是 过滤器配置，SDK 会按照该参数配置进行滤，并返回过滤后的本地会话列表的消息总未读数。

    示例代码

    Dartawait NimCore.instance.localConversationService.getUnreadCountByFilter(filter)

    返回值

    NIMResult<int>：过滤后的本地会话列表的消息总未读数

    相关回调

    无

    clearTotalUnreadCount

    接口描述

    将所有本地会话的消息未读数清零。

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

    参数说明

    DartFuture<NIMResult<void>> clearTotalUnreadCount()

    无参数

    示例代码

    Dartawait NimCore.instance.localConversationService.clearTotalUnreadCount()

    返回值

    NIMResult<void>

    相关回调

    • onTotalUnreadCountChanged：本地会话消息总未读数变更回调
    • onConversationChanged：本地会话变更回调
    • onUnreadCountChangedByFilter：指定过滤条件的会话消息未读数变更回调

    clearUnreadCountByIds

    接口描述

    根据会话 ID 将指定的本地会话列表的消息未读数清零。

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

    参数说明

    DartFuture<NIMResult<List<NIMConversationOperationResult>>> clearUnreadCountByIds( List<String> conversationIds )
    参数名称 类型 是否必填 说明
    conversationIds List<String> 是 会话 ID 列表。
  • 不可为空，否则返回 191004 参数错误。
  • 单次调用上限为 10 条。
    		•

    示例代码

    Dartawait NimCore.instance.localConversationService.clearUnreadCountByIds(conversationIds)

    返回值

    NIMResult<List<NIMConversationOperationResult>>：单条本地会话操作结果信息

    相关回调

    • onTotalUnreadCountChanged：本地会话消息总未读数变更回调
    • onConversationChanged：本地会话变更回调
    • onUnreadCountChangedByFilter：指定过滤条件的会话消息未读数变更回调

    clearUnreadCountByTypes

    接口描述

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

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

    参数说明

    DartFuture<NIMResult<void>> clearUnreadCountByTypes( List<NIMConversationType> conversationTypes )
    参数名称 类型 是否必填 说明
    conversationTypes List<NIMConversationType> 是 会话类型。

    示例代码

    Dartawait NimCore.instance.localConversationService.clearUnreadCountByTypes(conversationTypes)

    返回值

    NIMResult<void>

    相关回调

    • onTotalUnreadCountChanged：本地会话消息总未读数变更回调
    • onConversationChanged：本地会话变更回调
    • onUnreadCountChangedByFilter：指定过滤条件的会话消息未读数变更回调

    subscribeUnreadCountByFilter

    接口描述

    订阅指定过滤条件过滤后的本地会话未读数变化。可按需多次调用该方法，订阅多个过滤器的本地会话未读数变化。

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

    该接口为同步接口。

    参数说明

    DartFuture<NIMResult<NIMError?>> subscribeUnreadCountByFilter( NIMConversationFilter filter )
    参数名称 类型 是否必填 说明
    filter NIMConversationFilter 是 本地会话过滤对象。
  • 如果该对象参数均为空，则返回 191004 错误码。
  • 如果该对象设置多个参数且生效，则返回值对应的多个回调。如果设置多个参数但有参数错误未生效，则不触发任何回调。
    		•

    示例代码

    Dartawait NimCore.instance.localConversationService.subscribeUnreadCountByFilter(filter)

    返回值

    NIMResult<NIMError>：错误码

    相关回调

    onUnreadCountChangedByFilter：指定过滤条件的会话消息未读数变更回调

    unsubscribeUnreadCountByFilter

    接口描述

    取消订阅指定过滤条件过滤后的本地会话未读数变化。

    该接口为同步接口。

    参数说明

    DartFuture<NIMResult<NIMError?>> unsubscribeUnreadCountByFilter( NIMConversationFilter filter )
    参数名称 类型 是否必填 说明
    filter NIMConversationFilter 是 本地会话过滤对象。如果该对象参数均为空，则返回 191004 错误码。

    示例代码

    Dartawait NimCore.instance.localConversationService.unsubscribeUnreadCountByFilter(filter)

    返回值

    NIMResult<NIMError>：错误码

    相关回调

    onUnreadCountChangedByFilter：指定过滤条件的会话消息未读数变更回调

    markConversationRead

    接口描述

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

    标记成功后，SDK 会同步更新缓存和数据库。

    参数说明

    DartFuture<NIMResult<int>> markConversationRead( String conversationId )
    参数名称 类型 是否必填 说明
    conversationId String 是 会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。

    示例代码

    Dartawait NimCore.instance.localConversationService.markConversationRead(conversationId)

    返回值

    NIMResult：标记时间

    相关回调

    无

    getConversationReadTime

    接口描述

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

    数据同步完成前，可能查询不到完整数据或者查询到的是老数据。

    参数说明

    DartFuture<NIMResult<int>> getConversationReadTime( String conversationId )
    参数名称 类型 是否必填 说明
    conversationId String 是 会话 ID，如果为空、不合法、不存在则返回 191004 参数错误。

    示例代码

    Dartawait NimCore.instance.localConversationService.getConversationReadTime(conversationId)

    返回值

    NIMResult<int>：时间戳

    相关回调

    无

    此文档是否对你有帮助？
    有帮助
    去反馈
    • API 概览
    • 本地会话监听
    • 本地会话操作
    • 本地会话未读数
    • 接口类
    • listen
    • cancel
    • createConversation
    • deleteConversation
    • deleteConversationListByIds
    • getConversation
    • getConversationList
    • getConversationListByOption
    • getConversationListByIds
    • updateConversationLocalExtension
    • stickTopConversation
    • getStickTopConversationList
    • getTotalUnreadCount
    • getUnreadCountByIds
    • getUnreadCountByFilter
    • clearTotalUnreadCount
    • clearUnreadCountByIds
    • clearUnreadCountByTypes
    • subscribeUnreadCountByFilter
    • unsubscribeUnreadCountByFilter
    • markConversationRead
    • getConversationReadTime
    在线咨询微信咨询电话咨询
    © 1997-2024 网易公司增值电信业务许可证B1-20180288浙B1.B2-20090185浙公网安备浙公网安备 33010802002218号浙ICP备17006647号-3工业和信息化部备案管理系统网站隐私政策