• UIKit
  • SDK
  • 服务端 API
Chat/
SDK/
Web/
会话/
SDK
  • 集成 SDK
  • 初始化
  • 登录登出
  • 接口列表
  • 更新日志
  • 消息
    • 介绍
    • 发送消息
    • 接收消息
    • 历史消息
    • 转发消息
    • 修改消息
    • 删除消息
    • 清空消息
    • 撤回消息
    • 在线消息
    • 已读回执
    • 查询消息
    • 群定向消息
    • 消息免打扰
    • 消息扩展
    • 消息翻译
  • 会话
    • 介绍
    • 会话列表
    • 获取会话
    • 会话未读数
    • 置顶会话
    • 删除会话
    • 会话标记
    • 会话分组
  • 群组
    • 介绍
    • 管理群组
    • 群资料
    • 管理群成员
    • 群成员资料
    • 自定义属性
    • 群计数器
  • 社群话题
    • 管理社群
  • 用户
    • 用户资料
    • 用户状态
    • 管理好友
    • 好友列表
    • 黑名单
  • 开发指引
  • 控制台指南
    • 创建和升级应用
    • 基本配置
    • 功能配置
    • 账号管理
    • 群组管理
    • 回调配置
  • 产品介绍
    • 消息管理
      • 单聊消息
      • 消息存储
      • 离线推送
      • 群消息
      • 消息格式
    • 账号系统
      • 登陆验证
      • 在线状态管理
    • 群相关
      • 群组系统
      • 群组管理
    • 用户资料和关系链
      • 资料管理
      • 关系链管理
  • 购买指南
    • 计费概述
    • 价格中心
  • 错误码

会话未读数

功能描述

用户的会话列表中一般会有若干个会话,如果某个会话收到了新消息,通常需要在列表的 cell 中以小红点或者数字角标的方式,向用户展示该会话的未读消息数,提醒用户尚未阅读。 用户点击进入该会话后退回到会话列表,未读消息数被清空,小红点消失。部分应用还会统计所有会话的未读消息总数之和,将其展示在会话列表的底部 tab 上。

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

通常情况下,如果想得到所有会话的未读消息总数,可以遍历会话列表得到每个会话的信息 Conversation,然后再把所有的 ConversationunreadCount 相加起来,展示在 UI 上。 SDK 现在为您提供了直接查询所有会话未读消息总数的 API getTotalUnreadMessageCount。 当会话未读总数发生变更时,SDK 会通过 TencentCloudChat.EVENT.TOTAL_UNREAD_MESSAGE_COUNT_UPDATED 事件将最新的未读总数通知出来。
说明
1. 仅适用于好友工作群(Work)、陌生人社交群(Public)、社群(Community)和临时会议群(Meeting),直播群(AVChatRoom)暂不支持。

获取未读总数

接口
chat.getTotalUnreadMessageCount();
返回值
Number
示例
// 获取单聊和群聊会话的未读总数
let totalUnreadCount = chat.getTotalUnreadMessageCount();

会话未读总数变更通知

您可以通过监听 TencentCloudChat.EVENT.TOTAL_UNREAD_MESSAGE_COUNT_UPDATED 事件来接收消息未读总数变更的通知。
示例
let onTotalUnreadMessageCountUpdated = function(event) {
console.log(event.data); // 当前单聊和群聊会话的未读总数
};
chat.on(TencentCloudChat.EVENT.TOTAL_UNREAD_MESSAGE_COUNT_UPDATED, onTotalUnreadMessageCountUpdated);

清空会话未读消息数

接口
chat.setMessageRead(options);
参数 options 为 Object 类型,包含的属性值如下:
参数
Name
Type
Description
conversationID
String
会话 ID。会话 ID 组成方式:
C2C${userID}(单聊)
GROUP{groupID}(群聊)
GROUP${topicID}(话题)
@TIM#SYSTEM(系统通知会话)
返回值
Promise
示例
// 将某会话下所有未读消息已读上报
let promise = chat.setMessageRead({conversationID: 'C2Cexample'});
promise.then(function(imResponse) {
// 已读上报成功,指定 ID 的会话的 unreadCount 属性值被置为0
}).catch(function(imError) {
// 已读上报失败
console.warn('setMessageRead error:', imError);
});

清空所有会话未读消息数

chat.setAllMessageRead(options);
参数 options 为 Object 类型,包含的属性值如下:
参数
Name
Type
Description
scope
String | undefined
设置消息处理的范围。详细类型如下:
TencentCloudChat.TYPES.READ_ALL_C2C_MSG (设置所有 C2C 会话未读消息为已读)
TencentCloudChat.TYPES.READ_ALL_GROUP_MSG (设置所有群会话未读消息为已读)
TencentCloudChat.TYPES.READ_ALL_MSG (默认值,设置所有 C2C 和群会话未读消息为已读)
返回值
Promise
示例
// 将所有会话的未读消息全部设置为已读
let promise = chat.setAllMessageRead(); // 等同于 chat.setAllMessageRead({scope: TIM.TYPES.READ_ALL_MSG})
promise.then(function(imResponse) {
// 已读上报成功,所有会话的 unreadCount 属性值被置为0
}).catch(function(imError) {
// 已读上报失败
console.warn('setAllMessageRead error:', imError);
});
// 将所有 C2C 会话的未读消息全部设置为已读
let promise = chat.setAllMessageRead({scope: TencentCloudChat.TYPES.READ_ALL_C2C_MSG});
promise.then(function(imResponse) {
// 已读上报成功,所有 C2C 会话的 unreadCount 属性值被置为0
}).catch(function(imError) {
// 已读上报失败
console.warn('setAllMessageRead error:', imError);
});
// 将所有群会话的未读消息全部设置为已读
let promise = chat.setAllMessageRead({scope: TencentCloudChat.TYPES.READ_ALL_GROUP_MSG});
promise.then(function(imResponse) {
// 已读上报成功,所有 C2C 会话的 unreadCount 属性值被置为0
}).catch(function(imError) {
// 已读上报失败
console.warn('setAllMessageRead error:', imError);
});

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

正常情况下,无论是发送单聊消息还是群消息,都会计入未读消息数(会话对象 Conversation 的 unreadCount 属性,表示一个会话的未读消息数)。 当您希望发送一些不计入未读计数的消息时,例如提示类或者控制类的消息,可以参考以下示例代码。
示例
chat.sendMessage(message, {
messageControlInfo: {
excludedFromUnreadCount: true, // 消息不更新会话 unreadCount(消息存漫游)
excludedFromLastMessage: true // 消息不更新会话 lastMessage(消息存漫游)
}
});