即时通信 IM Android&iOS&Windows&Mac（会话未读数）

二、效果展示

你使用这篇的接口，可以实现如下所示的效果：

三、接口说明

四、获取所有会话的未读消息总数

通常情况下，如果你想得到所有会话的未读消息总数，可以遍历会话列表得到每个会话的信息 V2TIMConversation，然后再把所有的 V2TIMConversation 的 unreadCount 相加起来，展示在 UI 上。
但 IM SDK 为你提供了直接查询所有会话未读消息总数的接口 getTotalUnreadMessageCount。
当会话的未读总数发生变更时，SDK 还会主动通过回调 onTotalUnreadMessageCountChanged，将最新的未读总数通知出来。

注意：说明：

具体的操作步骤如下文所示。

五、获取所有会话的未读总数

你可以调用 getTotalUnreadMessageCount（Java / Swift / Objective-C / C++）获取所有会话的未读消息总数，获取成功后可以使用其更新 UI。

示例代码如下：

JavaSwiftObjective-CC++V2TIMManager.getConversationManager().getTotalUnreadMessageCount(new V2TIMValueCallback<Long>() { @Override public void onSuccess(Long aLong) { Log.i("imsdk", "success"); } @Override public void onError(int code, String desc) { Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});V2TIMManager.shared.getTotalUnreadMessageCount { totalCount in print("getTotalUnreadMessageCount succ, \\(totalCount)")} fail: { code, desc in print("getTotalUnreadMessageCount fail, \\(code), \\(desc)")}[[V2TIMManager sharedInstance] getTotalUnreadMessageCount:^(UInt64 totalCount) { // 获取成功，totalCount 为所有会话的未读消息总数 // 更新 UI 上的未读数} fail:^(int code, NSString *desc) { // 获取失败}];template <class T>class ValueCallback final : public V2TIMValueCallback<T> {public: using SuccessCallback = std::function<void(const T&)>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; ValueCallback() = default; ~ValueCallback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess(const T& value) override { if (success_callback_) { success_callback_(value); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};auto callback = new ValueCallback<uint64_t>{};callback->SetCallback( [=](const uint64_t& count) { // 获取所有会话的未读总数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 获取所有会话的未读总数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->GetTotalUnreadMessageCount(callback);

六、所有会话的未读总数变更通知

你可以调用 addConversationListener（Java / Swift / Objective-C / C++）添加会话监听器。添加监听器后，只需要调用过一次 getTotalUnreadMessageCount 接口，才能接收到所有会话的未读总数变更通知。

你可以在 V2TIMConversationListener 中的 onTotalUnreadMessageCountChanged（Java / Swift / Objective-C / C++）中，获取到变更后的未读总数。

示例代码如下：

JavaSwiftObjective-CC++public void onTotalUnreadMessageCountChanged(long totalUnreadCount) { // 收到所有会话的未读总数变更通知 Log.i("imsdk", "onTotalUnreadMessageCountChanged");}V2TIMManager.shared.addConversationListener(listener: self) func onTotalUnreadMessageCountChanged(totalUnreadCount: UInt) { // 会话未读总数变化 print("\\(totalUnreadCount)")}// 添加会话监听器[[V2TIMManager sharedInstance] addConversationListener:self];// 收到所有会话的未读总数变更通知- (void)onTotalUnreadMessageCountChanged:(UInt64)totalUnreadCount { // totalUnreadCount 为未读消息总数}class ConversationListener final : public V2TIMConversationListener {public: /** * 会话所有会话的未读总数变更通知（5.3.425 及以上版本支持） * * @note * – 未读总数会减去设置为免打扰的会话的未读数，即消息接收选项设置为 * V2TIM_NOT_RECEIVE_MESSAGE or V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE 的会话。 */ void OnTotalUnreadMessageCountChanged(uint64_t totalUnreadCount) override { // 收到所有会话的未读总数变更通知 } // 其他成员函数 …};// 添加会话事件监听器，注意在移除监听器之前需要保持 conversationListener 的生命期，以免接收不到事件回调ConversationListener conversationListener;V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);

七、根据过滤条件获取部分会话的未读消息总数

IM SDK 为你提供了根据过滤条件查询部分会话未读消息总数的接口 getUnreadMessageCountByFilter。
如果你需要监听指定过滤条件下的会话未读消息总数变更，可以调用 subscribeUnreadMessageCountByFilter 注册监听，当该过滤条件下的会话未读消息总数发生变更时，SDK 还会主动通过回调 onUnreadMessageCountChangedByFilter，将最新的未读总数通知出来。

注意：说明：

你可以调用 getUnreadMessageCountByFilter（Java / Swift / Objective-C / C++ ）获取部分会话的未读消息总数，获取成功后可以使用其更新 UI。其中过滤条件 V2TIMConversationListFilter 详解如下：

八、获取单聊或群聊会话的未读总数

JavaSwiftObjective-CC++V2TIMConversationListFilter filter = new V2TIMConversationListFilter();filter.setConversationType(V2TIMConversation.V2TIM_C2C); //拉取单聊会话// filter.setConversationType(V2TIMConversation.V2TIM_GROUP); //拉取群聊会话V2TIMManager.getConversationManager().getUnreadMessageCountByFilter(filter, new V2TIMValueCallback<Long>() { @Override public void onSuccess(Long totalUnreadCount) { tvLog.setText("getUnreadMessageCountByFilter success, totalUnreadCount:" + totalUnreadCount); } @Override public void onError(int code, String desc) { tvLog.setText("getUnreadMessageCountByFilter failed"); }});let filter = V2TIMConversationListFilter()filter.type = .V2TIM_C2C; //拉取单聊会话// filter.type = .V2TIM_GROUP; //拉取群聊会话V2TIMManager.shared.getUnreadMessageCountByFilter(filter: filter) { totalCount in print("getTotalUnreadMessageCount succ, \\(totalCount)")} fail: { code, desc in print("getTotalUnreadMessageCount fail, \\(code), \\(desc)")}V2TIMConversationListFilter *filter = [[V2TIMConversationListFilter alloc] init];filter.type = V2TIM_C2C; //拉取单聊会话// filter.type = V2TIM_GROUP; //拉取群聊会话[[V2TIMManager sharedInstance] getUnreadMessageCountByFilter:filter succ:^(UInt64 totalUnreadCount) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter success totalUnreadCount:%llu", totalUnreadCount]];} fail:^(int code, NSString *desc) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter failed"]];}];template <class T>class ValueCallback final : public V2TIMValueCallback<T> {public: using SuccessCallback = std::function<void(const T&)>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; ValueCallback() = default; ~ValueCallback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess(const T& value) override { if (success_callback_) { success_callback_(value); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMConversationListFilter filter;filter.type = V2TIM_C2C; // 拉取单聊会话// filter.type = V2TIM_GROUP; // 拉取群聊会话auto callback = new ValueCallback<uint64_t>{};callback->SetCallback( [=](const uint64_t& count) { // 获取部分会话的未读总数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 获取部分会话的未读总数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->GetUnreadMessageCountByFilter(filter, callback);

九、获取指定分组会话的未读总数

JavaSwiftObjective-CC++V2TIMConversationListFilter filter = new V2TIMConversationListFilter();filter.setConversationGroup("conversation_group");V2TIMManager.getConversationManager().getUnreadMessageCountByFilter(filter, new V2TIMValueCallback<Long>() { @Override public void onSuccess(Long totalUnreadCount) { tvLog.setText("getUnreadMessageCountByFilter success, totalUnreadCount:" + totalUnreadCount); } @Override public void onError(int code, String desc) { tvLog.setText("getUnreadMessageCountByFilter failed"); }});let filter = V2TIMConversationListFilter()filter.conversationGroup = "swift conv group"V2TIMManager.shared.getUnreadMessageCountByFilter(filter: filter) { totalCount in print("getTotalUnreadMessageCount succ, \\(totalCount)")} fail: { code, desc in print("getTotalUnreadMessageCount fail, \\(code), \\(desc)")}V2TIMConversationListFilter *filter = [[V2TIMConversationListFilter alloc] init];filter.conversationGroup = @"conversation_group";[[V2TIMManager sharedInstance] getUnreadMessageCountByFilter:filter succ:^(UInt64 totalUnreadCount) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter success totalUnreadCount:%llu", totalUnreadCount]];} fail:^(int code, NSString *desc) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter failed"]];}];template <class T>class ValueCallback final : public V2TIMValueCallback<T> {public: using SuccessCallback = std::function<void(const T&)>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; ValueCallback() = default; ~ValueCallback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess(const T& value) override { if (success_callback_) { success_callback_(value); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMConversationListFilter filter;filter.conversationGroup = "conversation_group";auto callback = new ValueCallback<uint64_t>{};callback->SetCallback( [=](const uint64_t& count) { // 获取部分会话的未读总数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 获取部分会话的未读总数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->GetUnreadMessageCountByFilter(filter, callback);

十、获取指定标记会话的未读总数

JavaSwiftObjective-CC++V2TIMConversationListFilter filter = new V2TIMConversationListFilter();filter.setMarkType(V2TIMConversation.V2TIM_CONVERSATION_MARK_TYPE_STAR);V2TIMManager.getConversationManager().getUnreadMessageCountByFilter(filter, new V2TIMValueCallback<Long>() { @Override public void onSuccess(Long totalUnreadCount) { tvLog.setText("getUnreadMessageCountByFilter success, totalUnreadCount:" + totalUnreadCount); } @Override public void onError(int code, String desc) { tvLog.setText("getUnreadMessageCountByFilter failed"); }});let filter = V2TIMConversationListFilter()filter.markType = .V2TIM_CONVERSATION_MARK_TYPE_STAR;V2TIMManager.shared.getUnreadMessageCountByFilter(filter: filter) { totalCount in print("getTotalUnreadMessageCount succ, \\(totalCount)")} fail: { code, desc in print("getTotalUnreadMessageCount fail, \\(code), \\(desc)")}V2TIMConversationListFilter *filter = [[V2TIMConversationListFilter alloc] init];filter.markType = V2TIM_CONVERSATION_MARK_TYPE_STAR;[[V2TIMManager sharedInstance] getUnreadMessageCountByFilter:filter succ:^(UInt64 totalUnreadCount) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter success totalUnreadCount:%llu", totalUnreadCount]];} fail:^(int code, NSString *desc) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter failed"]];}];template <class T>class ValueCallback final : public V2TIMValueCallback<T> {public: using SuccessCallback = std::function<void(const T&)>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; ValueCallback() = default; ~ValueCallback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess(const T& value) override { if (success_callback_) { success_callback_(value); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMConversationListFilter filter;filter.markType = V2TIM_CONVERSATION_MARK_TYPE_STAR;auto callback = new ValueCallback<uint64_t>{};callback->SetCallback( [=](const uint64_t& count) { // 获取部分会话的未读总数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 获取部分会话的未读总数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->GetUnreadMessageCountByFilter(filter, callback);

十一、获取含有未读数会话的未读总数

JavaSwiftObjective-CC++V2TIMConversationListFilter filter = new V2TIMConversationListFilter();filter.setHasUnreadCount(true);V2TIMManager.getConversationManager().getUnreadMessageCountByFilter(filter, new V2TIMValueCallback<Long>() { @Override public void onSuccess(Long totalUnreadCount) { tvLog.setText("getUnreadMessageCountByFilter success, totalUnreadCount:" + totalUnreadCount); } @Override public void onError(int code, String desc) { tvLog.setText("getUnreadMessageCountByFilter failed"); }});let filter = V2TIMConversationListFilter()filter.hasUnreadCount = trueV2TIMManager.shared.getUnreadMessageCountByFilter(filter: filter) { totalCount in print("getUnreadMessageCountByFilter succ, \\(totalCount)")} fail: { code, desc in print("getUnreadMessageCountByFilter fail, \\(code), \\(desc)")}V2TIMConversationListFilter *filter = [[V2TIMConversationListFilter alloc] init];filter.hasUnreadCount = YES;[[V2TIMManager sharedInstance] getUnreadMessageCountByFilter:filter succ:^(UInt64 totalUnreadCount) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter success totalUnreadCount:%llu", totalUnreadCount]];} fail:^(int code, NSString *desc) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter failed"]];}];template <class T>class ValueCallback final : public V2TIMValueCallback<T> {public: using SuccessCallback = std::function<void(const T&)>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; ValueCallback() = default; ~ValueCallback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess(const T& value) override { if (success_callback_) { success_callback_(value); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMConversationListFilter filter;filter.hasUnreadCount = true;auto callback = new ValueCallback<uint64_t>{};callback->SetCallback( [=](const uint64_t& count) { // 获取部分会话的未读总数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 获取部分会话的未读总数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->GetUnreadMessageCountByFilter(filter, callback);

十二、获取含有群 @ 消息会话的未读数

JavaSwiftObjective-CC++V2TIMConversationListFilter filter = new V2TIMConversationListFilter();filter.setHasGroupAtInfo(true);V2TIMManager.getConversationManager().getUnreadMessageCountByFilter(filter, new V2TIMValueCallback<Long>() { @Override public void onSuccess(Long totalUnreadCount) { tvLog.setText("getUnreadMessageCountByFilter success, totalUnreadCount:" + totalUnreadCount); } @Override public void onError(int code, String desc) { tvLog.setText("getUnreadMessageCountByFilter failed"); }});let filter = V2TIMConversationListFilter()filter.hasGroupAtInfo = trueV2TIMManager.shared.getUnreadMessageCountByFilter(filter: filter) { totalCount in print("getUnreadMessageCountByFilter succ, \\(totalCount)")} fail: { code, desc in print("getUnreadMessageCountByFilter fail, \\(code), \\(desc)")}V2TIMConversationListFilter *filter = [[V2TIMConversationListFilter alloc] init];filter.hasGroupAtInfo = YES;[[V2TIMManager sharedInstance] getUnreadMessageCountByFilter:filter succ:^(UInt64 totalUnreadCount) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter success totalUnreadCount:%llu", totalUnreadCount]];} fail:^(int code, NSString *desc) { [self appendString:[NSString stringWithFormat:@"getUnreadMessageCountByFilter failed"]];}];template <class T>class ValueCallback final : public V2TIMValueCallback<T> {public: using SuccessCallback = std::function<void(const T&)>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; ValueCallback() = default; ~ValueCallback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess(const T& value) override { if (success_callback_) { success_callback_(value); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMConversationListFilter filter;filter.hasGroupAtInfo = true;auto callback = new ValueCallback<uint64_t>{};callback->SetCallback( [=](const uint64_t& count) { // 获取部分会话的未读总数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 获取部分会话的未读总数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->GetUnreadMessageCountByFilter(filter, callback);

十四、注册监听部分会话的未读消息总数变更

你可以调用 addConversationListener（Java / Swift / Objective-C / C++）添加会话监听器。添加监听器后，需要你调用 subscribeUnreadMessageCountByFilter（Java / Swift / Objective-C / C++）接口，注册监听指定过滤条件下的未读消息总数变更。

你可以在 V2TIMConversationListener 中的 onUnreadMessageCountChangedByFilter（Java / Swift / Objective-C / C++）中，获取到变更后的未读总数。

你可以注册监听多个不同过滤条件下的未读总数变更，onUnreadMessageCountChangedByFilter 回调的 filter 参数就是调用 subscribeUnreadMessageCountByFilter 时指定的 filter，该 filter 携带了 conversationType、conversationGroup 和 markType 三个字段，通过判断这三字段是不是都相同，来区分出不同的过滤条件。

示例代码如下：

JavaSwiftObjective-CC++// 添加会话监听器V2TIMManager.getConversationManager().addConversationListener(conversationListener);// 注册监听指定过滤条件下的未读消息总数变更V2TIMConversationListFilter filter = new V2TIMConversationListFilter();filter.setConversationType(V2TIMConversation.V2TIM_GROUP);filter.setConversationGroup("conversation_group");filter.setMarkType(V2TIMConversation.V2TIM_CONVERSATION_MARK_TYPE_STAR);V2TIMManager.getConversationManager().subscribeUnreadMessageCountByFilter(filter);// 指定过滤条件下的未读消息总数变更通知public void onUnreadMessageCountChangedByFilter(V2TIMConversationListFilter filter, long totalUnreadCount) { // filter 是过滤条件，totalUnreadCount 是未读消息总数 Log.i(TAG, "onUnreadMessageCountChangedByFilter:" + totalUnreadCount + "\\n");}// 添加会话监听器V2TIMManager.shared.addConversationListener(listener: self)// 注册监听指定过滤条件下的未读消息总数变更let filter = V2TIMConversationListFilter()filter.type = .V2TIM_GROUP;filter.conversationGroup = "swift conv group"filter.markType = .V2TIM_CONVERSATION_MARK_TYPE_STAR;V2TIMManager.shared.unsubscribeUnreadMessageCountByFilter(filter: filter)// 指定过滤条件下的未读消息总数变更通知func onUnreadMessageCountChangedByFilter(filter: V2TIMConversationListFilter, totalUnreadCount: UInt) { // 过滤条件下的会话未读总数变化 print("\\(filter), count:\\(totalUnreadCount)")}// 添加会话监听器[[V2TIMManager sharedInstance] addConversationListener:self];// 注册监听指定过滤条件下的未读消息总数变更V2TIMConversationListFilter *filter = [[V2TIMConversationListFilter alloc] init];filter.type = V2TIM_GROUP;filter.conversationGroup = @"conversation_group";filter.markType = V2TIM_CONVERSATION_MARK_TYPE_STAR;[[V2TIMManager sharedInstance] subscribeUnreadMessageCountByFilter:filter];// 指定过滤条件下的未读消息总数变更通知- (void)onUnreadMessageCountChangedByFilter:(V2TIMConversationListFilter *)filter totalUnreadCount:(UInt64)totalUnreadCount { // filter 是过滤条件，totalUnreadCount 是未读消息总数}class ConversationListener final : public V2TIMConversationListener {public: // 指定过滤条件下的未读消息总数变更通知 void OnUnreadMessageCountChangedByFilter(const V2TIMConversationListFilter &filter, uint64_t totalUnreadCount) override { // filter 是过滤条件，totalUnreadCount 是未读消息总数 } // 其他成员函数 …};// 添加会话事件监听器，注意在移除监听器之前需要保持 conversationListener 的生命期，以免接收不到事件回调ConversationListener conversationListener;V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);// 注册监听指定过滤条件下的未读消息总数变更V2TIMConversationListFilter filter;filter.type = V2TIM_GROUP;filter.conversationGroup = "conversation_group";filter.markType = V2TIM_CONVERSATION_MARK_TYPE_STAR;V2TIMManager::GetInstance()->GetConversationManager()->SubscribeUnreadMessageCountByFilter(filter);

十五、取消监听部分会话的未读消息总数变更

你可以调用 unsubscribeUnreadMessageCountByFilter（Java / Swift / Objective-C / C++）接口，取消监听指定过滤条件下的未读消息总数变更。

示例代码如下：

JavaSwiftObjective-CC++// 取消监听指定过滤条件下的未读消息总数变更V2TIMConversationListFilter filter = new V2TIMConversationListFilter();filter.setConversationType(V2TIMConversation.V2TIM_GROUP);filter.setConversationGroup("conversation_group");filter.setMarkType(V2TIMConversation.V2TIM_CONVERSATION_MARK_TYPE_STAR);V2TIMManager.getConversationManager().unsubscribeUnreadMessageCountByFilter(filter);let filter = V2TIMConversationListFilter()filter.type = .V2TIM_GROUP;filter.conversationGroup = "swift conv group"filter.markType = .V2TIM_CONVERSATION_MARK_TYPE_STAR;V2TIMManager.shared.unsubscribeUnreadMessageCountByFilter(filter: filter)// 取消监听指定过滤条件下的未读消息总数变更V2TIMConversationListFilter *filter = [[V2TIMConversationListFilter alloc] init];filter.type = V2TIM_GROUP;filter.conversationGroup = @"conversation_group";filter.markType = V2TIM_CONVERSATION_MARK_TYPE_STAR;[[V2TIMManager sharedInstance] unsubscribeUnreadMessageCountByFilter:filter];// 取消监听指定过滤条件下的未读消息总数变更V2TIMConversationListFilter filter;filter.type = V2TIM_GROUP;filter.conversationGroup = "conversation_group";filter.markType = V2TIM_CONVERSATION_MARK_TYPE_STAR;V2TIMManager::GetInstance()->GetConversationManager()->UnsubscribeUnreadMessageCountByFilter(filter);

十六、清理会话未读消息数

用户点击进入会话后，再退回到会话列表，需要清理未读消息数。若未读数被清零 ，则会话列表的小红点或数字角标需要随之消失。

你可以调用 cleanConversationUnreadMessageCount（Java / Swift / Objective-C / C++）来清理指定会话未读消息数，通过传入特定格式的参数可以分别完成对指定单聊会话、全部单聊会话、指定群聊会话、全部群聊会话以及全部会话未读消息数的清理，具体的操作步骤如下文所示。

注意：说明：

注意：清理会话未读消息数功能仅增强版 7.1.3925 及以上版本支持。

接口说明如下：

JavaSwiftObjective-CC++// V2TIMConversationManagerpublic abstract void cleanConversationUnreadMessageCount(String conversationID, long cleanTimestamp, long cleanSequence, V2TIMCallback callback); public func cleanConversationUnreadMessageCount(conversationID: String?, cleanTimestamp: UInt64, cleanSequence: UInt64, succ: V2TIMSucc?, fail: V2TIMFail?) // V2TIMManager+Conversation.h- (void)cleanConversationUnreadMessageCount:(NSString *)conversationID cleanTimestamp:(uint64_t)cleanTimestamp cleanSequence:(uint64_t)cleanSequence succ:(V2TIMSucc)succ fail:(V2TIMFail)fail; // V2TIMConversationManagervirtual void CleanConversationUnreadMessageCount( const V2TIMString& conversationID, uint64_t cleanTimestamp, uint64_t cleanSequence, V2TIMCallback* callback);

参数说明：

注意：说明：

十七、清理指定单聊会话的未读数

你可以通过传入带有 "c2c_" 前缀的 conversationID 来清理指定单聊会话未读消息数，同时还可以通过传入 cleanTimestamp 来清理指定时间戳及其之前的未读消息数。如果传入的 cleanTimestamp 为 0，则将指定单聊会话的未读数清 0。

示例代码如下：

JavaSwiftObjective-CC++String conversationID = "c2c_userID";V2TIMManager.getConversationManager().cleanConversationUnreadMessageCount(conversationID, 123456, 0, new V2TIMCallback() { @Override public void onSuccess() { Log.i("imsdk", "success"); } @Override public void onError(int code, String desc) { Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});V2TIMManager.shared.cleanConversationUnreadMessageCount(conversationID: "c2c_userID", cleanTimestamp: 123456, cleanSequence: 0, succ: { // 清理指定单聊会话未读数成功}) { code, desc in // 清理指定单聊会话未读数失败}[[V2TIMManager sharedInstance] cleanConversationUnreadMessageCount:@"c2c_userID" cleanTimestamp:123456 cleanSequence:0 succ:^{ // 清理指定单聊会话未读数成功} fail:^(int code, NSString *msg) { // 清理指定单聊会话未读数失败}];class Callback final : public V2TIMCallback {public: using SuccessCallback = std::function<void()>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; Callback() = default; ~Callback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess() override { if (success_callback_) { success_callback_(); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMString conversationID = u8"c2c_userID";auto callback = new Callback;callback->SetCallback( [=]() { // 清理指定单聊会话未读数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 清理指定单聊会话未读数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->CleanConversationUnreadMessageCount(conversationID, 123456, 0, callback);

当本端调用 cleanConversationUnreadMessageCount 成功后，如果调用者事先调用 addConversationListener 添加了会话监听器，会收到 onConversationChanged 回调，该回调中携带了对应会话的最新未读消息数，可以在此回调中更新 UI。

示例代码如下：

JavaSwiftObjective-CC++public void onConversationChanged(List<V2TIMConversation> conversationList) { // 调用者收到会话信息变更通知 Log.i("imsdk", "onConversationChanged");}// 添加会话监听器V2TIMManager.shared.addConversationListener(listener: self)// 调用者收到会话信息变更通知func onConversationChanged(conversationList: Array<V2TIMConversation>) { // 收到会话变更通知，conversationList 中为变更后的会话对象 conversationList.forEach { item in print(item.description) }}// 添加会话监听器[[V2TIMManager sharedInstance] addConversationListener:self];// 调用者收到会话信息变更通知- (void)onConversationChanged:(NSArray<V2TIMConversation*> *)conversationList { // 根据 conversationList 中的 V2TIMConversation 更新对应 UI}class ConversationListener final : public V2TIMConversationListener {public: /** * 某些会话的关键信息发生变化（未读计数发生变化、最后一条消息被更新等等），可以根据会话的 * lastMessage -> timestamp 重新对会话列表做排序 * * @param conversationList 会话列表 */ void OnConversationChanged(const V2TIMConversationVector& conversationList) override {} // 其他成员 …};// 添加会话事件监听器，注意在移除监听器之前需要保持 conversationListener 的生命期，以免接收不到事件回调ConversationListener conversationListener;V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);

十八、清空所有单聊会话的未读数

你可以传入 "c2c" 作为 conversationID，表示将所有单聊会话的未读数全部清 0，请注意此时 cleanTimestamp 将不再生效。

示例代码如下：

JavaSwiftObjective-CC++String conversationID = "c2c";V2TIMManager.getConversationManager().cleanConversationUnreadMessageCount(conversationID, 0, 0, new V2TIMCallback() { @Override public void onSuccess() { Log.i("imsdk", "success"); } @Override public void onError(int code, String desc) { Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});V2TIMManager.shared.cleanConversationUnreadMessageCount(conversationID: "c2c", cleanTimestamp: 0, cleanSequence: 0, succ: { // 清空所有单聊会话未读消息数成功}) { code, desc in // 清空所有单聊会话未读消息数失败}[[V2TIMManager sharedInstance] cleanConversationUnreadMessageCount:@"c2c" cleanTimestamp:0 cleanSequence:0 succ:^{ // 清空所有单聊会话未读消息数成功} fail:^(int code, NSString *msg) { // 清空所有单聊会话未读消息数失败}];class Callback final : public V2TIMCallback {public: using SuccessCallback = std::function<void()>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; Callback() = default; ~Callback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess() override { if (success_callback_) { success_callback_(); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMString conversationID = u8"c2c";auto callback = new Callback;callback->SetCallback( [=]() { // 清空所有单聊会话未读消息数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 清空所有单聊会话未读消息数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->CleanConversationUnreadMessageCount(conversationID, 0, 0, callback);

当本端调用 cleanConversationUnreadMessageCount 成功后，如果调用者事先调用 addConversationListener 添加了会话监听器，会收到 onConversationChanged 回调，该回调中携带了对应会话的最新未读消息数，可以在此回调中更新 UI。

示例代码如下：

JavaSwiftObjective-CC++public void onConversationChanged(List<V2TIMConversation> conversationList) { // 调用者收到会话信息变更通知 Log.i("imsdk", "onConversationChanged");}// 添加会话监听器V2TIMManager.shared.addConversationListener(listener: self)func onConversationChanged(conversationList: Array<V2TIMConversation>) { // 收到会话变更通知，conversationList 中为变更后的会话对象 conversationList.forEach { item in print(item.description) }}// 添加会话监听器[[V2TIMManager sharedInstance] addConversationListener:self];// 调用者收到会话信息变更通知- (void)onConversationChanged:(NSArray<V2TIMConversation*> *)conversationList { // 根据 conversationList 中的 V2TIMConversation 更新对应 UI，例如清除掉单聊会话 cell 小红点}class ConversationListener final : public V2TIMConversationListener {public: /** * 某些会话的关键信息发生变化（未读计数发生变化、最后一条消息被更新等等），可以根据会话的 * lastMessage -> timestamp 重新对会话列表做排序 * * @param conversationList 会话列表 */ void OnConversationChanged(const V2TIMConversationVector& conversationList) override {} // 其他成员 …};// 添加会话事件监听器，注意在移除监听器之前需要保持 conversationListener 的生命期，以免接收不到事件回调ConversationListener conversationListener;V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);

十九、清理指定群聊会话的未读数

你可以通过传入带有 "group_" 前缀的 conversationID 来清理指定群聊会话未读消息数，同时还可以通过传入 cleanSequence 来清理指定 sequence 及其之前的未读消息数。如果传入的 cleanSequence 为 0，则将指定群聊会话的未读数清 0。

示例代码如下：

JavaSwiftObjective-CC++String conversationID = "group_groupID";V2TIMManager.getConversationManager().cleanConversationUnreadMessageCount(conversationID, 0, 123, new V2TIMCallback() { @Override public void onSuccess() { Log.i("imsdk", "success"); } @Override public void onError(int code, String desc) { Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});V2TIMManager.shared.cleanConversationUnreadMessageCount(conversationID: "group_groupID", cleanTimestamp: 123456, cleanSequence: 0, succ: { // 清理指定群聊会话未读消息数成功 }) { code, desc in // 清理指定群聊会话未读消息数失败}[[V2TIMManager sharedInstance] cleanConversationUnreadMessageCount:@"group_groupID" cleanTimestamp:0 cleanSequence:123 succ:^{ // 清理指定群聊会话未读消息数成功} fail:^(int code, NSString *msg) { // 清理指定群聊会话未读消息数失败}];class Callback final : public V2TIMCallback {public: using SuccessCallback = std::function<void()>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; Callback() = default; ~Callback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess() override { if (success_callback_) { success_callback_(); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMString conversationID = u8"group_groupID";auto callback = new Callback;callback->SetCallback( [=]() { // 清理指定群聊会话未读消息数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 清理指定群聊会话未读消息数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->CleanConversationUnreadMessageCount(conversationID, 0, 123, callback);

当 cleanConversationUnreadMessageCount 调用成功后，如果调用者事先调用 addConversationListener 添加了会话监听器，会收到 onConversationChanged 回调，该回调中携带了对应会话的最新未读消息数，可以在此回调中更新 UI。

示例代码如下：

JavaSwiftObjective-CC++public void onConversationChanged(List<V2TIMConversation> conversationList) { // 调用者收到会话信息变更通知 Log.i("imsdk", "onConversationChanged");}// 添加会话监听器V2TIMManager.shared.addConversationListener(listener: self)// 调用者收到会话信息变更通知func onConversationChanged(conversationList: Array<V2TIMConversation>) { // 根据 conversationList 中的 V2TIMConversation 更新对应 UI conversationList.forEach { item in print(item.description) }}// 添加会话监听器[[V2TIMManager sharedInstance] addConversationListener:self];// 调用者收到会话信息变更通知- (void)onConversationChanged:(NSArray<V2TIMConversation*> *)conversationList { // 根据 conversationList 中的 V2TIMConversation 更新对应 UI}class ConversationListener final : public V2TIMConversationListener {public: void OnConversationChanged(const V2TIMConversationVector& conversationList) override {} // 调用者收到会话信息变更通知};// 添加会话事件监听器，注意在移除监听器之前需要保持 conversationListener 的生命期，以免接收不到事件回调ConversationListener conversationListener;V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);

20、清空所有群聊会话的未读数

你可以传入 "group" 作为 conversationID，表示将所有群聊会话的未读数全部清 0，请注意此时 cleanSequence 将不再生效。

JavaSwiftObjective-CC++String conversationID = "group";V2TIMManager.getConversationManager().cleanConversationUnreadMessageCount(conversationID, 0, 0, new V2TIMCallback() { @Override public void onSuccess() { Log.i("imsdk", "success"); } @Override public void onError(int code, String desc) { Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});V2TIMManager.shared.cleanConversationUnreadMessageCount(conversationID: "group", cleanTimestamp: 0, cleanSequence: 0, succ: { // 清空所有群聊会话未读消息数成功}) { code, desc in // 清空所有群聊会话未读消息数失败}[[V2TIMManager sharedInstance] cleanConversationUnreadMessageCount:@"group" cleanTimestamp:0 cleanSequence:0 succ:^{ // 清空所有群聊会话未读消息数成功} fail:^(int code, NSString *msg) { // 清空所有群聊会话未读消息数失败}];class Callback final : public V2TIMCallback {public: using SuccessCallback = std::function<void()>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; Callback() = default; ~Callback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess() override { if (success_callback_) { success_callback_(); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMString conversationID = u8"group";auto callback = new Callback;callback->SetCallback( [=]() { // 清空所有群聊会话未读消息数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 清空所有群聊会话未读消息数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->CleanConversationUnreadMessageCount(conversationID, 0, 0, callback);

当 cleanConversationUnreadMessageCount 调用成功后，如果调用者事先调用 addConversationListener 添加了会话监听器，会收到 onConversationChanged 回调，该回调中携带了对应会话的最新未读消息数，可以在此回调中更新 UI。

示例代码如下：

JavaSwiftObjective-CC++public void onConversationChanged(List<V2TIMConversation> conversationList) { // 调用者收到会话信息变更通知 Log.i("imsdk", "onConversationChanged");}V2TIMManager.shared.addConversationListener(listener: self)func onConversationChanged(conversationList: Array<V2TIMConversation>) { // 收到会话变更通知，conversationList 中为变更后的会话对象 conversationList.forEach { item in print(item.description) }}// 添加会话监听器[[V2TIMManager sharedInstance] addConversationListener:self];// 调用者收到会话信息变更通知- (void)onConversationChanged:(NSArray<V2TIMConversation*> *)conversationList { // 根据 conversationList 中的 V2TIMConversation 更新对应 UI，例如清除掉群聊会话 cell 小红点}class ConversationListener final : public V2TIMConversationListener {public: void OnConversationChanged(const V2TIMConversationVector& conversationList) override {} // 调用者收到会话信息变更通知};// 添加会话事件监听器，注意在移除监听器之前需要保持 conversationListener 的生命期，以免接收不到事件回调ConversationListener conversationListener;V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);

21、清空所有会话的未读数

你可以传入空字符串 "" 作为 conversationID，表示将所有会话的未读消息数全部清 0，请注意此时 cleanTimestamp 和 cleanSequence 都不再生效。

示例代码如下：

JavaSwiftObjective-CC++String conversationID = "";V2TIMManager.getConversationManager().cleanConversationUnreadMessageCount(conversationID, 0, 0, new V2TIMCallback() { @Override public void onSuccess() { Log.i("imsdk", "success"); } @Override public void onError(int code, String desc) { Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});V2TIMManager.shared.cleanConversationUnreadMessageCount(conversationID: "", cleanTimestamp: 0, cleanSequence: 0, succ: { // 清空所有会话未读消息数成功 }) { code, desc in // 清空所有会话未读消息数失败}[[V2TIMManager sharedInstance] cleanConversationUnreadMessageCount:@"" cleanTimestamp:0 cleanSequence:0 succ:^{ // 清空所有会话未读消息数成功} fail:^(int code, NSString *desc) { // 清空所有会话未读消息数失败}];class Callback final : public V2TIMCallback {public: using SuccessCallback = std::function<void()>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; Callback() = default; ~Callback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess() override { if (success_callback_) { success_callback_(); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMString conversationID = u8"";auto callback = new Callback;callback->SetCallback( [=]() { // 清空所有会话未读消息数成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 清空所有会话未读消息数失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->CleanConversationUnreadMessageCount(conversationID, 0, 0, callback);

当 cleanConversationUnreadMessageCount 调用成功后，如果调用者事先调用 addConversationListener 添加了会话监听器，会收到 onConversationChanged 回调，该回调中携带了对应会话的最新未读消息数，可以在此回调中更新 UI。

示例代码如下：

JavaSwiftObjective-CC++public void onConversationChanged(List<V2TIMConversation> conversationList) { // 收到会话信息变更通知 Log.i("imsdk", "onConversationChanged");}// 添加会话监听器V2TIMManager.shared.addConversationListener(listener: self)// 调用者收到会话信息变更通知func onConversationChanged(conversationList: Array<V2TIMConversation>) { // 收到会话变更通知，conversationList 中为变更后的会话对象 conversationList.forEach { item in print(item.description) }}// 添加会话监听器[[V2TIMManager sharedInstance] addConversationListener:self];// 调用者收到会话信息变更通知- (void)onConversationChanged:(NSArray<V2TIMConversation*> *)conversationList { // 更新 UI，例如清除掉会话列表底部 tab 小红点}class ConversationListener final : public V2TIMConversationListener {public: void OnConversationChanged(const V2TIMConversationVector& conversationList) override {} // 调用者收到会话信息变更通知};// 添加会话事件监听器，注意在移除监听器之前需要保持 conversationListener 的生命期，以免接收不到事件回调ConversationListener conversationListener;V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);

22、发送不计入会话未读数的消息

正常情况下，无论是发送单聊消息还是群聊消息，都会计入未读消息数（通过会话对象 V2TIMConversation 的 unreadCount 接口，可以拿到一个会话的未读消息数）。
当你希望发送一些不计入未读计数的消息，例如提示类或者控制类的消息，可以在调用 sendMessage 时：

·对于 Java 而言，调用 setExcludedFromUnreadCount 方法，设置为 true。

·对于 Objective-C / Swift / C++ 而言，设置消息对象的 isExcludedFromUnreadCount 为 YES/true。

发送消息 sendMessage 的使用参考：发送消息。

注意：说明：

注意：setExcludedFromUnreadCount 或 isExcludedFromUnreadCount 参数仅增强版 5.3.425 及以上版本支持。

示例代码如下：

JavaSwiftObjective-CC++// 创建消息对象V2TIMMessage v2TIMMessage = V2TIMManager.getMessageManager().createTextMessage(content);// 设置不更新会话 lastMessagev2TIMMessage.setExcludedFromUnreadCount(true);// 发送消息V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, "userID", null, V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, null, new V2TIMSendCallback<V2TIMMessage>() { @Override public void onSuccess(V2TIMMessage v2TIMMessage) { Log.i("imsdk", "success"); } @Override public void onProgress(int progress) { Log.i("imsdk", "progress:" + progress); } @Override public void onError(int code, String desc) { Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});if let message = V2TIMManager.shared.createTextMessage(text: "这是一个信令消息") { // 设置不计入未读消息总数的标记 message.isExcludedFromUnreadCount = true // 发送消息 V2TIMManager.shared.sendMessage(message: message, receiver: "userA", groupID: nil, priority: .V2TIM_PRIORITY_DEFAULT, onlineUserOnly: true, offlinePushInfo: nil, progress: nil, succ: { // 消息发送成功 print("消息发送成功") }, fail: { code, msg in // 消息发送失败 print("消息发送失败，code: \\(code), msg: \\(msg)") })}// 创建消息对象V2TIMMessage *message = [[V2TIMManager sharedInstance] createTextMessage:@"这是一个信令消息"];// 设置不计入未读消息总数的标记message.isExcludedFromUnreadCount = YES;// 发送消息[[V2TIMManager sharedInstance] sendMessage:msg receiver:@"userA" groupID:nilpriority:V2TIM_PRIORITY_DEFAULT onlineUserOnly:YES offlinePushInfo:nil progress:^(uint32_t progress) {} succ:^{ // 消息发送成功} fail:^(int code, NSString *msg) { // 消息发送失败}];class SendCallback final : public V2TIMSendCallback {public: using SuccessCallback = std::function<void(const V2TIMMessage&)>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; using ProgressCallback = std::function<void(uint32_t)>; SendCallback() = default; ~SendCallback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback, ProgressCallback progress_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); progress_callback_ = std::move(progress_callback); } void OnSuccess(const V2TIMMessage& message) override { if (success_callback_) { success_callback_(message); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } } void OnProgress(uint32_t progress) override { if (progress_callback_) { progress_callback_(progress); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_; ProgressCallback progress_callback_;};// 创建消息对象V2TIMMessage message = V2TIMManager::GetInstance()->GetMessageManager()->CreateTextMessage(u8"content");// 设置不更新会话 lastMessagemessage.isExcludedFromUnreadCount = true;auto callback = new SendCallback{};callback->SetCallback([=](const V2TIMMessage& message) { delete callback; }, [=](int error_code, const V2TIMString& error_message) { delete callback; }, [=](uint32_t progress) {});V2TIMManager::GetInstance()->GetMessageManager()->SendMessage( message, u8"userID", {}, V2TIMMessagePriority::V2TIM_PRIORITY_NORMAL, false, {}, callback);