本地会话管理 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

本地会话管理

更新时间： 2025/02/20 17:12:39

网易云信 IM 支持本地会话管理功能，包括创建、更新、删除本地会话等基础操作，以及置顶会话等进阶操作。本地会话列表由 SDK 维护并提供查询、监听变化的接口，当会话变更时，SDK 会自动更新会话列表并通知，您无需手动更新。

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

支持平台

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

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

技术原理

网易云信 IM 支持本地（客户端）会话，在客户端进行存储和维护，支持存储和查询用户全量的会话历史消息。

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

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

监听本地会话相关事件

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

监听

本地会话相关回调：

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

Android/iOS/macOS/Windows

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

示例代码：

Android

JavaV2NIMLocalConversationListener listener = new V2NIMLocalConversationListener() {
  @Override
  public void onSyncStarted() {  
  }
  @Override
  public void onSyncFinished() {
  }
  @Override
  public void onSyncFailed(V2NIMError error) {
  }
  @Override
  public void onConversationCreated(V2NIMLocalConversation conversation) {
  }
  @Override
  public void onConversationDeleted(List<String> conversationIds) {
  }
  @Override
  public void onConversationChanged(List<V2NIMLocalConversation> conversationList) {
  }
  @Override
  public void onTotalUnreadCountChanged(int unreadCount) {
  }
  @Override
  public void onUnreadCountChangedByFilter(V2NIMLocalConversationFilter filter, int unreadCount) {
  }
  @Override
  public void onConversationReadTimeUpdated(String conversationId, long readTime) {
  }
};
NIMClient.getService(V2NIMLocalConversationService.class).addConversationListener(listener);

iOS

Objective-C@interface SampleCode : NSObject<V2NIMLocalConversationListener>
@end

@implementation SampleCode
- (void)onSyncStarted
{  
}
- (void)onSyncFinished
{
}
/**
 * @param error 会话数据云端同步失败，可能为如下原因：网络连接断开；服务异常。可以根据相应错误码确定相关错误原因
 */
- (void)onSyncFailed:(V2NIMError *)error
{
}
- (void)onConversationCreated:(V2NIMLocalConversation *)conversation
{
}
/**
 * @param conversationIds 被删除的会话ID列表，可以根据该ID列表移除界面上展示的会话数据
 */
- (void)onConversationDeleted:(NSArray<NSString *> *)conversationIds
{
}
- (void)onConversationChanged:(NSArray<V2NIMLocalConversation *> *)conversationList
{
}
- (void)onTotalUnreadCountChanged:(NSInteger)unreadCount
{ 
}
- (void)onUnreadCountChangedByFilter:(V2NIMLocalConversationFilter *)filter
                         unreadCount:(NSInteger)unreadCount
{  
}
- (void)onConversationReadTimeUpdated:(NSString *)conversationId
                             readTime:(NSTimeInterval)readTime
{ 
}
- (void)addListener
{
    [[NIMSDK sharedSDK].v2LocalConversationService addConversationListener:self];
}
- (void)removeListener
{
    [[NIMSDK sharedSDK].v2LocalConversationService removeConversationListener:self];
}
@end

macOS/Windows

C++V2NIMLocalConversationListener 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 = [](V2NIMLocalConversation conversation) {
    // handle conversation created event
};
listener.onConversationDeleted = [](nstd::vector<nstd::string> conversationIds) {
    // handle conversation deleted event
};
listener.onConversationChanged = [](nstd::vector<V2NIMLocalConversation> conversationList) {
    // handle conversation changed event
};
listener.onTotalUnreadCountChanged = [](uint32_t unreadCount) {
    // handle total unread count changed event
};
listener.onUnreadCountChangedByFilter = [](V2NIMLocalConversationFilter filter, uint32_t unreadCount) {
    // handle unread count changed by group event
};
localConversationService.addConversationListener(listener);

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

Android

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

iOS

Objective-Cid<V2NIMLocalConversationListener> listener;
[NIMSDK.sharedSDK.v2LocalConversationService removeConversationListener:listener];

macOS/Windows

C++V2NIMLocalConversationListener listener;
// ...
localConversationService.addConversationListener(listener);
// ...
localConversationService.removeConversationListener(listener);

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

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

示例代码：

Web/uni-app/小程序

TypeScriptnim.V2NIMLocalConversationService.on("onSyncStarted", () => {});
nim.V2NIMLocalConversationService.on("onSyncFinished", () => {});
nim.V2NIMLocalConversationService.on("onSyncFailed", (err) => {});
nim.V2NIMLocalConversationService.on("onConversationCreated", (conversation: V2NIMLocalConversation) => {});
nim.V2NIMLocalConversationService.on("onConversationDeleted", (conversationIds: string[]) => {});
nim.V2NIMLocalConversationService.on("onConversationChanged", (conversationList: V2NIMLocalConversation[]) => {});
nim.V2NIMLocalConversationService.on("onTotalUnreadCountChanged", (unreadCount: number) => {});
nim.V2NIMLocalConversationService.on("onUnreadCountChangedByFilter", (filter: V2NIMLocalConversationFilter, unreadCount: number) => {});
nim.V2NIMLocalConversationService.on("onConversationReadTimeUpdated", (conversationId: string, readTime: number) => {});

Node.js/Electron

TypeScriptv2.localConversationService.on("syncStarted", function () {});
v2.localConversationService.on("syncFinished", function () {});
v2.localConversationService.on("syncFailed", function (err) {});
v2.localConversationService.on("conversationCreated", function (conversation: V2NIMLocalConversation) {});
v2.localConversationService.on("conversationDeleted", function (conversationIds: string[]) {});
v2.localConversationService.on("conversationChanged", function (conversationList: V2NIMLocalConversation[]) {});
v2.localConversationService.on("totalUnreadCountChanged", function (unreadCount: number) {});
v2.localConversationService.on("unreadCountChangedByFilter", function (filter: V2NIMLocalConversationFilter, unreadCount: number) {});
v2.localConversationService.on("conversationReadTimeUpdated", function (conversationId: string, readTime: number) {});

HarmonyOS

TypeScriptnim.localConversationService.on("onSyncStarted", () => {});
nim.localConversationService.on("onSyncFinished", () => {});
nim.localConversationService.on("onSyncFailed", (err) => {});
nim.localConversationService.on("onConversationCreated", (conversation: V2NIMLocalConversation) => {});
nim.localConversationService.on("onConversationDeleted", (conversationIds: string[]) => {});
nim.localConversationService.on("onConversationChanged", (conversationList: V2NIMLocalConversation[]) => {});
nim.localConversationService.on("onTotalUnreadCountChanged", (unreadCount: number) => {});
nim.localConversationService.on("onUnreadCountChangedByFilter", (filter: V2NIMLocalConversationFilter, unreadCount: number) => {});
nim.localConversationService.on("onConversationReadTimeUpdated", (conversationId: string, readTime: number) => {});

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

Web/uni-app/小程序

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

Node.js/Electron

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

HarmonyOS

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

过滤监听

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

Android

JavaList<V2NIMConversationType> conversationTypes = new ArrayList<>();
conversationTypes.add(V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
//是否忽略免打扰
boolean ignoreMuted = true;
V2NIMLocalConversationFilter filter = new V2NIMLocalConversationFilter(conversationTypes,ignoreMuted);
NIMClient.getService(V2NIMLocalConversationService.class).subscribeUnreadCountByFilter(filter);

iOS

Objective-CNSMutableArray<NSNumber *> *conversationTypes = [[NSMutableArray alloc] init];
[conversationTypes addObject:@(V2NIM_CONVERSATION_TYPE_P2P)];

// 是否忽略免打扰
BOOL ignoreMuted = YES;

V2NIMLocalConversationFilter *filter = [[V2NIMLocalConversationFilter alloc] init];
filter.conversationTypes = conversationTypes;
filter.ignoreMuted = ignoreMuted;

[[NIMSDK sharedSDK].v2LocalConversationService subscribeUnreadCountByFilter:filter];

macOS/Windows

C++V2NIMLocalConversationFilter filter;
filter.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
auto error = localConversationService.subscribeUnreadCountByFilter(filter);
if (error) {
    // subscribe failed, handle error
}

Web/uni-app/小程序

TypeScript// Eg. Subscribe to P2P conversation and ignore those muted conversation
nim.V2NIMLocalConversationService.subscribeUnreadCountByFilter({
  conversationTypes: [V2NIMConst.V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P];
  ignoreMuted: true;
})

Node.js/Electron

TypeScriptawait v2.localConversationService.subscribeUnreadCountByFilter({ conversationTypes: [1, 2] })

HarmonyOS

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

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

Android

JavaList<V2NIMConversationType> conversationTypes = new ArrayList<>();
conversationTypes.add(V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
//是否忽略免打扰
boolean ignoreMuted = true;
V2NIMLocalConversationFilter filter = new V2NIMLocalConversationFilter(conversationTypes,ignoreMuted);
NIMClient.getService(V2NIMLocalConversationService.class).unsubscribeUnreadCountByFilter(filter);

iOS

Objective-CNSMutableArray *conversationTypes = [[NSMutableArray alloc] init];
[conversationTypes addObject:@(V2NIM_CONVERSATION_TYPE_P2P)];

// 是否忽略免打扰
BOOL ignoreMuted = YES;

V2NIMLocalConversationFilter *filter = [[V2NIMLocalConversationFilter alloc] init];
filter.conversationTypes = conversationTypes;
filter.ignoreMuted = ignoreMuted;

[[NIMSDK sharedSDK].v2LocalConversationService unsubscribeUnreadCountByFilter:filter];

macOS/Windows

C++auto error = localConversationService.unsubscribeUnreadCountByFilter(filter);
if (error) {
    // unsubscribe failed, handle error
}

Web/uni-app/小程序

TypeScript// Eg. Subscribe to P2P conversation and ignore those muted conversation
const filter = {
  conversationTypes: [V2NIMConst.V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P];
  ignoreMuted: true;
}
nim.V2NIMLocalConversationService.subscribeUnreadCountByFilter(filter)
nim.V2NIMLocalConversationService.unsubscribeUnreadCountByFilter(filter)

Node.js/Electron

TypeScriptawait v2.localConversationService.unsubscribeUnreadCountByFilter({ conversationTypes: [1, 2] })

HarmonyOS

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

创建本地会话

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

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

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

示例代码：

Android

JavaString conversationId = "cjl|1|cjl1";
NIMClient.getService(V2NIMLocalConversationService.class).createConversation(conversationId, new V2NIMSuccessCallback<V2NIMLocalConversation>() {
  @Override
  public void onSuccess(V2NIMLocalConversation result) {
   // 创建成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 创建失败
  }
});

iOS

Objective-CNSString *conversationId = @"cjl|1|cjl1";
[[NIMSDK sharedSDK].v2LocalConversationService createConversation:conversationId
                                                          success:^(V2NIMLocalConversation *result) {
    // 创建成功
} failure:^(V2NIMError *error) {
    // 创建失败
}];

macOS/Windows

C++auto conversationId = V2NIMConversationIdUtil::p2pConversationId("account1");
localConversationService.createConversation(
    conversationId,
    [](V2NIMLocalConversation conversation) {
        // create succeeded
    },
    [](V2NIMError error) {
        // create failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst datas = await nim.V2NIMLocalConversationService.createConversation("CONVERSATION_ID")

Node.js/Electron

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

HarmonyOS

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

获取本地会话

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

分页获取所有本地会话列表

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

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

查询的本地会话列表结果中，置顶会话排首位。
如果会话数据同步已开始（收到 onSyncStarted 回调），建议您在数据同步完成（收到 onSyncFinished 回调）后再进行该操作，否则可能查询不到完整数据或者查询到的是老数据。
查询云端会话时，当正好查询完所有数据时，下次查询时才会提示查询完毕（finished = true）。但是查询本地会话时，当正好查询完所有本地数据时，当次查询时就会提示查询完毕（finished = true）。

示例代码：

Android

Javaint offset = 0;
//分页拉取数量，不建议超过100
int limit = 100;
NIMClient.getService(V2NIMLocalConversationService.class).getConversationList(offset, limit, new V2NIMSuccessCallback<V2NIMLocalConversationResult>() {
    @Override
    public void onSuccess(V2NIMLocalConversationResult result) {
        // 获取成功
        //本地会话列表
        List<V2NIMLocalConversation> conversationList = result.getConversationList();
        //是否拉取完毕
        boolean finished = result.isFinished();
        //下一次拉取偏移量，首次传入的offset值，后续拉取采用上一次返回的offset值。如果finished为true，则返回0
        long nextOffset = result.getOffset();
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //获取失败
    }
});

iOS

Objective-CNSInteger offset = 0;
// 分页拉取数量，不建议超过100
NSInteger limit = 100;
[[NIMSDK sharedSDK].v2LocalConversationService getConversationList:offset
                                                             limit:limit
                                                           success:^(V2NIMLocalConversationResult *result) {
    // 获取成功
    // 本地会话列表
    NSArray<V2NIMLocalConversation *> *conversationList = result.conversationList;
    // 是否拉取完毕
    BOOL finished = result.finished;
    // 下一次拉取偏移量，首次传入的offset值，后续拉取采用上一次返回的offset值。如果finished为true，则返回0
    NSInteger nextOffset = result.offset;
    } failure:^(V2NIMError *error) {
        // 获取失败
    }];

macOS/Windows

C++localConversationService.getConversationList(
    lastCursor,
    10,
    [](V2NIMLocalConversationResult result) {
        // get conversation list succeeded
    },
    [](V2NIMError error) {
        // get conversation list failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst { offset, finished, conversationList } = await nim.V2NIMLocalConversationService.getConversationList(0, 100)

Node.js/Electron

TypeScriptconst result = await v2.localConversationService.getConversationList(0, 10)

HarmonyOS

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

获取指定单条本地会话

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

如果数据同步已开始（收到 onSyncStarted 回调），建议您在数据同步完成（收到 onSyncFinished 回调）后再进行该操作，否则可能查询不到完整数据或者查询到的是老数据。

示例代码：

Android

JavaString conversationId = "cjl|1|cjl1";
NIMClient.getService(V2NIMLocalConversationService.class).getConversation(conversationId, new V2NIMSuccessCallback<V2NIMLocalConversation>() {
  @Override
  public void onSuccess(V2NIMLocalConversation result) {
    // 获取成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
    //获取失败   
  }
});

iOS

Objective-CNSString *conversationId = @"cjl|1|cjl1";

[[NIMSDK sharedSDK].v2LocalConversationService getConversation:conversationId
                                                      success:^(V2NIMLocalConversation *result) {
    // 获取成功
} failure:^(V2NIMError *error) {
    // 获取失败
}];

macOS/Windows

C++auto conversationId = V2NIMConversationIdUtil::p2pConversationId("account1");
localConversationService.getConversation(
    conversationId,
    [](V2NIMLocalConversation conversation) {
        // get conversation succeeded
    },
    [](V2NIMError error) {
        // get conversation failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst data = await nim.V2NIMLocalConversationService.getConversation("TARGET_CONVERSATION_ID")

Node.js/Electron

TypeScriptconst conversation = await v2.localConversationService.getConversation('conversation1')

HarmonyOS

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

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

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

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

示例代码：

Android

Javaint offset = 0;
//分页拉取数量，不建议超过100
int limit = 100;
//会话类型列表,为空表示查询所有类型，否则查询指定对话类型
List<V2NIMConversationType> conversationTypes = new ArrayList<>();
//是否只拉取未读会话，默认false
boolean onlyUnread = false;
V2NIMLocalConversationOption option = new V2NIMLocalConversationOption(conversationTypes, onlyUnread);
NIMClient.getService(V2NIMLocalConversationService.class).getConversationListByOption(offset, limit, option, new V2NIMSuccessCallback<V2NIMLocalConversationResult>() {
    @Override
    public void onSuccess(V2NIMLocalConversationResult result) {
        // 获取成功
        //本地会话列表
        List<V2NIMLocalConversation> conversationList = result.getConversationList();
        //是否拉取完毕
        boolean finished = result.isFinished();
        //下一次拉取偏移量，首次传入的offset值，后续拉取采用上一次返回的offset值。如果finished为true，则返回0
        long nextOffset = result.getOffset();
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //获取失败
    }
});

iOS

Objective-CNSInteger offset = 0;
// 分页拉取数量，不建议超过100
NSInteger limit = 100;
// 会话类型列表,为空表示查询所有类型，否则查询指定对话类型
NSArray<NSNumber *> *conversationTypes = @[];
// 是否只拉取未读会话，默认false
BOOL onlyUnread = NO;

V2NIMLocalConversationOption *option = [[V2NIMLocalConversationOption alloc] init];
option.conversationTypes = conversationTypes;
option.onlyUnread = onlyUnread;

[[NIMSDK sharedSDK].v2LocalConversationService getConversationListByOption:offset
                                                                     limit:limit
                                                                    option:option
                                                                   success:^(V2NIMLocalConversationResult *result) {
    // 获取成功
    // 本地会话列表
    NSArray<V2NIMLocalConversation *> *conversationList = result.conversationList;
    // 是否拉取完毕
    BOOL finished = result.finished;
    // 下一次拉取偏移量，首次传入的offset值，后续拉取采用上一次返回的offset值。如果finished为true，则返回0
    NSInteger nextOffset = result.offset;
} failure:^(V2NIMError *error) {
    // 获取失败
}];

macOS/Windows

C++V2NIMLocalConversationOption option;
option.onlyUnread = true;
option.conversationTypes = {V2NIM_CONVERSATION_TYPE_P2P, V2NIM_CONVERSATION_TYPE_TEAM};
localConversationService.getConversationListByOption(
    lastCursor,
    10,
    option,
    [](V2NIMLocalConversationResult result) {
        // get conversation list succeeded
    },
    [](V2NIMError error) {
        // get conversation list failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst { offset, finished, conversationList } = await nim.V2NIMLocalConversationService.getConversationListByOption(0, 100, {
  conversationTypes: [V2NIMConst.V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P]
  onlyUnread: true,
})

Node.js/Electron

TypeScriptconst result = await v2.localConversationService.getConversationListByOption(0, 10, {
  conversationTypes: [1, 2]
})

HarmonyOS

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

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

批量获取指定的本地会话列表

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

示例代码：

Android

JavaList<String> conversationIds = new ArrayList<>();
conversationIds.add("cjl|1|cjl1");
conversationIds.add("cjl|2|43243253");
conversationIds.add("cjl|3|234323432");
NIMClient.getService(V2NIMLocalConversationService.class).getConversationListByIds(conversationIds, new V2NIMSuccessCallback<List<V2NIMLocalConversation>>() {
  @Override
  public void onSuccess(List<V2NIMLocalConversation> result) {
   // 获取成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 获取失败
  }
});

iOS

Objective-CNSMutableArray *conversationIds = [[NSMutableArray alloc] init];
[conversationIds addObject:@"cjl|1|cjl1"];
[conversationIds addObject:@"cjl|2|43243253"];
[conversationIds addObject:@"cjl|3|234323432"];

[[NIMSDK sharedSDK].v2LocalConversationService getConversationListByIds:conversationIds
                                                                success:^(NSArray<V2NIMLocalConversation *> *result) {
    // 获取成功
} failure:^(V2NIMError *error) {
    // 获取失败
}];

macOS/Windows

C++auto conversationIds = nstd::vector<nstd::string>();
conversationIds.emplace_back(V2NIMConversationIdUtil::p2pConversationId("account1"));
conversationIds.emplace_back(V2NIMConversationIdUtil::p2pConversationId("account2"));
localConversationService.getConversationListByIds(
    conversationIds,
    [](nstd::vector<V2NIMLocalConversation> conversationList) {
        // get conversation list succeeded
    },
    [](V2NIMError error) {
        // get conversation list failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst datas = await nim.V2NIMLocalConversationService.getConversationListByIds(["TARGET_CONVERSATION_ID", "TARGET_CONVERSATION_ID2"]])

Node.js/Electron

TypeScriptconst list = await v2.localConversationService.getConversationListByIds(['conversation1', 'conversation2'])

HarmonyOS

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

更新会话的本地扩展信息

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

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

示例代码：

Android

JavaString conversationId = "cjl|1|cjl1";
//本地扩展字段
String localExtension = "localExtension";
NIMClient.getService(V2NIMLocalConversationService.class).updateConversationLocalExtension(conversationId, localExtension, new V2NIMSuccessCallback<Void>() {
  @Override
  public void onSuccess(Void result) {
   // 更新成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 更新失败
  }
});

iOS

Objective-CNSString *conversationId = @"cjl|1|cjl1";
// 本地扩展字段
NSString *localExtension = @"localExtension";
[[NIMSDK sharedSDK].v2LocalConversationService updateConversationLocalExtension:conversationId
                                                                 localExtension:localExtension
                                                                        success:^() {
    // 更新成功
} failure:^(V2NIMError *error) {
    // 更新失败
}];

macOS/Windows

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

Web/uni-app/小程序

TypeScriptawait nim.V2NIMLocalConversationService.updateConversationLocalExtension("CONVERSATION_ID", 'newLocalExtension!'})

Node.js/Electron

TypeScriptawait v2.localConversationService.updateConversationLocalExtension('conversation1', 'newExtension')

HarmonyOS

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

删除本地会话

删除指定单条本地会话

调用 deleteConversation 根据会话 ID 删除指定的本地会话，且支持指定是否删除会话内的历史消息。

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

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

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

示例代码：

Android

JavaString conversationId = "cjl|1|cjl1";
//是否清空消息记录
boolean clearMessage = true;
NIMClient.getService(V2NIMLocalConversationService.class).deleteConversation(conversationId, clearMessage, new V2NIMSuccessCallback<Void>() {
  @Override
  public void onSuccess(Void result) {
   // 删除成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 删除失败
  }
});

iOS

Objective-CNSString *conversationId = @"cjl|1|cjl1";
// 是否清空消息记录
BOOL clearMessage = YES;
[[NIMSDK sharedSDK].v2LocalConversationService deleteConversation:conversationId
                                                     clearMessage:clearMessage
                                                          success:^() {
    // 删除成功
} failure:^(V2NIMError *error) {
    // 删除失败
}];

macOS/Windows

C++auto conversationId = V2NIMConversationIdUtil::p2pConversationId("account1");
localConversationService.deleteConversation(
    conversationId,
    true,
    []() {
        // delete succeeded
    },
    [](V2NIMError error) {
        // delete failed, handle error
    });

Web/uni-app/小程序

TypeScriptawait nim.V2NIMLocalConversationService.deleteConversation("CONVERSATION_ID", true)

Node.js/Electron

TypeScriptawait v2.localConversationService.deleteConversation('conversation1', true)

HarmonyOS

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

批量删除指定本地会话列表

调用 deleteConversationListByIds 根据会话 ID 批量删除指定的本地会话列表，且支持指定是否删除会话内的历史消息。

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

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

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

示例代码：

Android

JavaList<String> conversationIds = new ArrayList<>();
conversationIds.add("cjl|1|cjl1");
conversationIds.add("cjl|2|43243253");
conversationIds.add("cjl|3|234323432");
//是否清空消息记录
boolean clearMessage = true;
NIMClient.getService(V2NIMLocalConversationService.class).deleteConversationListByIds(conversationIds, clearMessage, new V2NIMSuccessCallback<List<V2NIMLocalConversationOperationResult>>() {
  @Override
  public void onSuccess(List<V2NIMLocalConversationOperationResult> result) {
   // 删除成功,返回会话ID操作失败的列表
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 删除失败
  }
});

iOS

Objective-CNSMutableArray *conversationIds = [[NSMutableArray alloc] init];
[conversationIds addObject:@"cjl|1|cjl1"];
[conversationIds addObject:@"cjl|2|43243253"];
[conversationIds addObject:@"cjl|3|234323432"];
// 是否清空消息记录
BOOL clearMessage = YES;
[[NIMSDK sharedSDK].v2LocalConversationService deleteConversationListByIds:conversationIds 
                                                               clearMessage:clearMessage 
                                                                    success:^(NSArray<V2NIMLocalConversationOperationResult *> *result) {
    // 删除成功,返回会话ID操作失败的列表
} failure:^(V2NIMError *error) {
    // 删除失败
}];

macOS/Windows

C++auto conversationIds = nstd::vector<nstd::string>();
conversationIds.emplace_back(V2NIMConversationIdUtil::p2pConversationId("account1"));
conversationIds.emplace_back(V2NIMConversationIdUtil::p2pConversationId("account2"));
localConversationService.deleteConversationListByIds(
    conversationIds,
    true,
    [](nstd::vector<V2NIMLocalConversationOperationResult> failedList) {
        // delete succeeded
    },
    [](V2NIMError error) {
        // delete failed, handle error
    });

Web/uni-app/小程序

TypeScriptawait nim.V2NIMLocalConversationService.deleteConversationListByIds(["CONVERSATION_ID1", "CONVERSATION_ID2"], true)

Node.js/Electron

TypeScriptconst result = await v2.localConversationService.deleteConversationListByIds(['conversation1', 'conversation2'], true)

HarmonyOS

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

本地会话消息未读数

获取消息未读数

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

调用 getTotalUnreadCount 方法获取所有本地会话的消息总未读数。

当消息未读数有任何变更，都会触发 onTotalUnreadCountChanged 回调。

如果数据同步已开始（收到 onSyncStarted 回调），建议您在数据同步完成（收到 onSyncFinished 回调）后再进行该操作，否则可能查询不到完整数据或者查询到的是老数据。
该接口为同步接口。

示例代码：

Android

Javaint totalUnreadCount = NIMClient.getService(V2NIMLocalConversationService.class).getTotalUnreadCount();

iOS

Objective-CNSInteger totalUnreadCount = [[NIMSDK sharedSDK].v2LocalConversationService getTotalUnreadCount];

macOS/Windows

C++auto totalUnreadCount = localConversationService.getTotalUnreadCount();

Web/uni-app/小程序

TypeScriptconst count = nim.V2NIMLocalConversationService.getTotalUnreadCount()

Node.js/Electron

TypeScriptconst count = await v2.localConversationService.getTotalUnreadCount()

HarmonyOS

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

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

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

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

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

示例代码：

Android

JavaList<String> conversationIds = new ArrayList<>();
conversationIds.add("cjl|1|cjl1");
conversationIds.add("cjl|2|43243253");
NIMClient.getService(V2NIMLocalConversationService.class).getUnreadCountByIds(conversationIds, new V2NIMSuccessCallback<Integer>() {
  @Override
  public void onSuccess(Integer unreadCounts) {
   // 获取成功,返回总未读数为所有合法会话加和后的值
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   //获取失败
  }
});

iOS

Objective-CNSMutableArray *conversationIds = [[NSMutableArray alloc] init];
[conversationIds addObject:@"cjl|1|cjl1"];
[conversationIds addObject:@"cjl|2|43243253"];
[[NIMSDK sharedSDK].v2LocalConversationService getUnreadCountByIds:conversationIds 
                                                           success:^(NSInteger unreadCounts) {
    // 获取成功,返回总未读数为所有合法会话加和后的值
} failure:^(V2NIMError *error) {
    // 获取失败
}];

macOS/Windows

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

Web/uni-app/小程序

TypeScriptconst unreadCounts = await nim.V2NIMLocalConversationService.getUnreadCountByIds(["CONVERSATION_ID1,CONVERSATION_ID2"])

Node.js/Electron

TypeScriptconst count = await v2.localConversationService.getUnreadCountByIds(['conversation1', 'conversation2'])

HarmonyOS

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

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

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

示例代码：

Android

JavaList<V2NIMConversationType> conversationTypes = new ArrayList<>();
//是否忽略免打扰
boolean ignoreMuted = true;
V2NIMLocalConversationFilter filter = new V2NIMLocalConversationFilter(conversationTypes, ignoreMuted);
NIMClient.getService(V2NIMLocalConversationService.class).getUnreadCountByFilter(filter, new V2NIMSuccessCallback<Integer>() {
  @Override
  public void onSuccess(Integer unreadCounts) {
   // 获取成功,返回总未读数为所有合法会话加和后的值
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   //获取失败
  }
});

iOS

Objective-CNSMutableArray *conversationTypes = [[NSMutableArray alloc] init];
// 是否忽略免打扰
BOOL ignoreMuted = YES;
V2NIMLocalConversationFilter *filter = [[V2NIMLocalConversationFilter alloc] init];
filter.conversationTypes = conversationTypes;
filter.ignoreMuted = ignoreMuted;
[[NIMSDK sharedSDK].v2LocalConversationService getUnreadCountByFilter:filter
                                                              success:^(NSInteger unreadCounts) {
    // 获取成功,返回总未读数为所有合法会话加和后的值
} failure:^(V2NIMError *error) {
    // 获取失败
}];

macOS/Windows

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

Web/uni-app/小程序

TypeScriptconst unreadCounts = await nim.V2NIMLocalConversationService.getUnreadCountByFilter({ ignoreMuted: true })

Node.js/Electron

TypeScriptconst count = await v2.localConversationService.getUnreadCountByFilter({ conversationTypes: [1, 2] })

HarmonyOS

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

未读数清零

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

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

调用 clearTotalUnreadCount 将应用内所有本地会话的消息未读数清零。

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

示例代码：

Android

JavaNIMClient.getService(V2NIMLocalConversationService.class).clearTotalUnreadCount(new V2NIMSuccessCallback<Void>() {
  @Override
  public void onSuccess(Void unused) {
   // 清除成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 清除失败
  }
});

iOS

Objective-C[[NIMSDK sharedSDK].v2LocalConversationService clearTotalUnreadCount:^(void) {
        // 清除成功
    } failure:^(V2NIMError *error) {
        // 清除失败
    }];

macOS/Windows

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

Web/uni-app/小程序

TypeScriptawait nim.V2NIMLocalConversationService.clearTotalUnreadCount()

Node.js/Electron

TypeScriptawait v2.localConversationService.clearTotalUnreadCount()

HarmonyOS

TypeScripttry {
  await this.localConversationService.clearTotalUnreadCount()
  // success
} catch (e) {
  // fail
}

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

调用 clearUnreadCountByIds 方法根据会话 ID 批量将指定本地会话列表的消息未读数清零。

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

示例代码：

Android

JavaList<String> conversationIds = new ArrayList<>();
conversationIds.add("cjl|1|cjl1");
conversationIds.add("cjl|2|43243253");
NIMClient.getService(V2NIMLocalConversationService.class).clearUnreadCountByIds(conversationIds, new V2NIMSuccessCallback<List<V2NIMLocalConversationOperationResult>>() {
  @Override
  public void onSuccess(List<V2NIMLocalConversationOperationResult> result) {
   // 清除成功,返回会话ID操作失败的列表
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 清除失败
  }
});

iOS

Objective-CNSMutableArray *conversationIds = [[NSMutableArray alloc] init];
[conversationIds addObject:@"cjl|1|cjl1"];
[conversationIds addObject:@"cjl|2|43243253"];

[[NIMSDK sharedSDK].v2LocalConversationService clearUnreadCountByIds:conversationIds success:^(NSArray<V2NIMLocalConversationOperationResult *> *result) {
    // 清除成功,返回会话ID操作失败的列表
} failure:^(V2NIMError *error) {
    // 清除失败
}];

macOS/Windows

C++auto conversationIds = nstd::vector<nstd::string>();
conversationIds.emplace_back(V2NIMConversationIdUtil::p2pConversationId("account1"));
conversationIds.emplace_back(V2NIMConversationIdUtil::p2pConversationId("account2"));
localConversationService.clearUnreadCountByIds(
    conversationIds,
    [](nstd::vector<V2NIMLocalConversationOperationResult> failedList) {
        // clear unread count succeeded
    },
    [](V2NIMError error) {
        // clear unread count failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst results = await nim.V2NIMLocalConversationService.clearUnreadCountByIds(["CONVERSATION_ID1", "CONVERSATION_ID2"])

Node.js/Electron

TypeScriptconst result = await v2.localConversationService.clearUnreadCountByIds(['conversation1', 'conversation2'])

HarmonyOS

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

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

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

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

示例代码：

Android

JavaList<V2NIMConversationType> conversationTypes = new ArrayList<>();
conversationTypes.add(V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
NIMClient.getService(V2NIMLocalConversationService.class).clearUnreadCountByTypes(conversationTypes, new V2NIMSuccessCallback<Void>() {
  @Override
  public void onSuccess(Void unused) {
   // 清除成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 清除失败
  }
});

iOS

Objective-CNSMutableArray *conversationTypes = [[NSMutableArray alloc] init];
[conversationTypes addObject:@(V2NIMConversationTypeP2P)];

[[NIMSDK sharedSDK].v2LocalConversationService clearUnreadCountByTypes:conversationTypes success:^(id unused) {
    // 清除成功
} failure:^(V2NIMError *error) {
    // 清除失败
}];

macOS/Windows

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

Web/uni-app/小程序

TypeScriptawait nim.V2NIMLocalConversationService.clearUnreadCountByTypes([V2NIMConst.V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P])

Node.js/Electron

TypeScriptawait v2.localConversationService.clearUnreadCountByTypes([1, 2])

HarmonyOS

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

标记本地会话已读

标记本地会话已读

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

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

示例代码：

Android

JavaString conversationId = "cjl|1|cjl1";
NIMClient.getService(V2NIMLocalConversationService.class).markConversationRead(conversationId, new V2NIMSuccessCallback<Long>() {
  @Override
  public void onSuccess(Long result) {
   // 标记成功,返回会话已读时间戳，单位毫秒
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 标记失败
  }
});

iOS

Objective-CNSString *conversationId = @"cjl|1|cjl1";
[[NIMSDK sharedSDK].v2LocalConversationService markConversationRead:conversationId success:^(NSTimeInterval result) {
    // 标记成功,返回会话已读时间戳，单位毫秒
} failure:^(V2NIMError *error) {
    // 标记失败
}];

macOS/Windows

C++localConversationService.markConversationRead(
    "conversationId",
    []() {
        // mark conversation read succeeded
    },
    [](V2NIMError error) {
        // mark conversation read failed, handle error
    )};

Web/uni-app/小程序

TypeScriptconst readTime = await nim.V2NIMLocalConversationService.markConversationRead("CONVERSATION_ID")

Node.js/Electron

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

HarmonyOS

TypeScriptawait this.localConversationService.markConversationRead('me|1|you')

获取本地会话已读时间戳

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

示例代码：

Android

JavaString conversationId = "cjl|1|cjl1";
NIMClient.getService(V2NIMLocalConversationService.class).getConversationReadTime(conversationId, new V2NIMSuccessCallback<Long>() {
  @Override
  public void onSuccess(Long result) {
   // 获取成功,返回会话已读时间戳，单位毫秒
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {

  }
});

iOS

Objective-CNSString *conversationId = @"cjl|1|cjl1";
[[NIMSDK sharedSDK].v2LocalConversationService getConversationReadTime:conversationId success:^(NSTimeInterval result) {
    // 获取成功,返回会话已读时间戳，单位秒
} failure:^(V2NIMError *error) {
    
}];

macOS/Windows

C++localConversationService.getConversationReadTime(
    "conversationId",
    [](time_t readTime) {
        // get conversation read time succeeded
    },
    [](V2NIMError error) {
        // get conversation read time failed, handle error
    )};

Web/uni-app/小程序

TypeScriptconst readTime = await nim.V2NIMLocalConversationService.getConversationReadTime("CONVERSATION_ID")

Node.js/Electron

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

HarmonyOS

typeScriptawait this.localConversationService.getConversationReadTime('me|1|you')

本地会话置顶

调用 stickTopConversation 方法根据本地会话 ID 将指定会话添加为置顶状态。最多支持置顶 100 个本地会话。

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

使用会话置顶功能前，您需要已开通 IM 套餐包并在网易云信控制台 应用管理 > 产品功能 > IM 即时通讯 > 全局功能 开通会话指定功能。
置顶前请确保该本地会话已存在。
如果数据同步已开始（收到 onSyncStarted 回调），建议您在数据同步完成（收到 onSyncFinished 回调）后再进行该操作，否则可能查询不到完整数据或者查询到的是老数据。

示例代码：

Android

JavaString conversationId = "cjl|1|cjl1";
//是否置顶,true：置顶, false：取消置顶
boolean stickTop = true;
NIMClient.getService(V2NIMLocalConversationService.class).stickTopConversation(conversationId, stickTop, new V2NIMSuccessCallback<Void>() {
  @Override
  public void onSuccess(Void result) {
   // 置顶成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   // 置顶失败
  }
});

iOS

Objective-CNSString *conversationId = @"cjl|1|cjl1";
// 是否置顶,YES：置顶, NO：取消置顶
BOOL stickTop = YES;
[[NIMSDK sharedSDK].v2LocalConversationService stickTopConversation:conversationId 
                                                           stickTop:stickTop 
                                                            success:^(id result) {
    // 置顶成功
} failure:^(V2NIMError *error) {
    // 置顶失败
}];

macOS/Windows

C++auto conversationId = V2NIMConversationIdUtil::p2pConversationId("account1");
localConversationService.stickTopConversation(
    conversationId,
    true,
    []() {
        // stick top succeeded
    },
    [](V2NIMError error) {
        // stick top failed, handle error
    });

Web/uni-app/小程序

TypeScriptawait nim.V2NIMLocalConversationService.stickTopConversation("CONVERSATION_ID", true)

Node.js/Electron

TypeScriptawait v2.localConversationService.stickTopConversation('conversation1', true)

HarmonyOS

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

涉及接口

Android/iOS/macOS/Windows

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

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

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

此文档是否对你有帮助？

有帮助

去反馈

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

支持平台

技术原理

监听本地会话相关事件

监听

过滤监听

创建本地会话

获取本地会话

分页获取所有本地会话列表

获取指定单条本地会话

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

批量获取指定的本地会话列表

更新会话的本地扩展信息

删除本地会话

删除指定单条本地会话

批量删除指定本地会话列表

本地会话消息未读数

获取消息未读数

未读数清零

标记本地会话已读

本地会话置顶

相关信息

涉及接口