Docs Overview/
Chat/
SDK/
JavaScript/
消息/
已读回执/

已读回执

功能描述

消息已读回执指的是，发送端往会话中发送消息，如果他想知道哪些人读过/还没读过这条消息，那么他就需要开启消息已读回执功能。 开启后，发送端发送消息时可以设置消息是否需要已读回执。如果设置为“需要”，接收端查看消息后才会发送自己已读回执给发送端。
群消息已读回执，高效沟通必备功能。作为一种强反馈工具，支持查看已读/未读已发送消息的人数和成员，尤其在商务、办公场景下，可帮助团队构建更加及时、高效的沟通氛围。
说明：
1. 该功能仅对进阶版客户开放，购买进阶版后可使用。
2. 社群和直播群不支持群消息已读回执。


消息已读回执

设置支持已读回执的群类型
如果是群消息已读回执，需要先在 Chat Console > Configuration > Group Configuration > Read receipts for group messages 中设置支持已读回执消息的群类型。
发送端设置消息需要已读回执
发送端创建消息，设置 needReadReceipt: true，然后发送消息。
示例
// 发送 C2C 消息
let message = chat.createTextMessage({
  to: 'user1',
  conversationType: TencentCloudChat.TYPES.CONV_C2C,
  payload: {
    text: 'Hello world!'
  },
  // 如果您发消息需要已读回执，需购买旗舰版套餐，并且创建消息时将 needReadReceipt 设置为 true
  needReadReceipt: true
});
// 2. 发送消息
let promise = chat.sendMessage(message);
promise.then(function(imResponse) {
  // 发送成功
  console.log(imResponse);
}).catch(function(imError) {
  // 发送失败
  console.warn('sendMessage error:', imError);
});
// 发送群消息
let message = chat.createTextMessage({
  to: 'test',
  conversationType: TencentCloudChat.TYPES.CONV_GROUP,
  payload: {
    text: 'Hello world!'
  },
  // 如果您发消息需要已读回执，需购买旗舰版套餐，并且创建消息时将 needReadReceipt 设置为 true
  needReadReceipt: true
});
// 发送消息
let promise = chat.sendMessage(message);
promise.then(function(imResponse) {
  // 发送成功
  console.log(imResponse);
}).catch(function(imError) {
  // 发送失败
  console.warn('sendMessage error:', imError);
});

接收端发送消息已读回执

接收端收到消息后，可以通过消息对象 Message 的 needReadReceipt 字段判断消息是否需要已读回执，如果需要已读回执，当用户查看消息后，调用 sendMessageReadReceipt 接口发送消息已读回执。
说明：
1. messageList 里的消息必须在同一个 C2C 或 Group 会话中。
2. 调用该接口成功后，会话未读数不会变化，消息发送者会收到 TencentCloudChat.TYPES.MESSAGE_READ_RECEIPT_RECEIVED 事件，回调里面会携带消息的最新已读信息。
3. 使用该接口需要您购买进阶版套餐。
4. 社群和直播群不支持群消息已读回执。
5. C2C 消息调用此接口成功后，消息发送方的 message.readReceiptInfo.isPeerRead 属性会更新为 true，此属性可用于 C2C 已读回执消息状态渲染，调用此接口不会更新消息的 isPeerRead 属性。
接口
chat.sendMessageReadReceipt(messageList);
参数
Name
Type
Description
messageList
Array
同一群会话的消息列表，最大长度为30。
返回值
Promise
示例
// 拉取群消息列表
let messageList = null;
chat.getMessageList({conversationID: 'GROUPtest'}).then(function(imResponse) {
  messageList = imResponse.data.messageList; // 消息列表
  chat.sendMessageReadReceipt(messageList).then(function() {
    // 发送群消息已读回执成功
  }).catch(function(imError) {
    // 发送群消息已读回执失败
  });
});
// 拉取C2C消息列表
let messageList = null;
chat.getMessageList({conversationID: 'C2Ctest'}).then(function(imResponse) {
  messageList = imResponse.data.messageList; // 消息列表
  chat.sendMessageReadReceipt(messageList).then(function() {
    // 发送群消息已读回执成功
  }).catch(function(imError) {
    // 发送群消息已读回执失败
  });
});

发送端监听消息已读回执通知

接收端发送消息已读回执后，发送端可以通过监听消息已读回执通知，在通知中更新 UI，例如更新为 “2 人已读”。
示例
let onMessageReadReceiptReceived = function(event) {
  // event.data - 存储消息已读回执信息的数组
  const readReceiptInfoList = event.data;
  readReceiptInfoList.forEach((item) => {
    const { groupID, userID, messageID, readCount, unreadCount, isPeerRead, timestamp } = item;
    // messageID - 消息 ID
    // userID - C2C 消息接收方
    // isPeerRead - C2C 消息对端是否已读
    // timestamp - C2C 消息对端发送已读回执时间，单位：秒
    // groupID - 群组 ID
    // readCount - 群消息已读人数
    // unreadCount - 群消息未读人数
    const message = chat.findMessage(messageID);
    if (message) {
     if (message.conversationType === TencentCloudChat.TYPES.CONV_C2C) {
       if (message.readReceiptInfo.isPeerRead === true) {
         // 对端已读
       }
     } else if (message.conversationType === TencentCloudChat.TYPES.CONV_GROUP) {
      if (message.readReceiptInfo.unreadCount === 0) {
        // 全部已读
      } else {
        // message.readReceiptInfo.readCount - 消息最新的已读数
        // 如果想要查询哪些群成员已读了此消息，请使用 [getGroupMessageReadMemberList] 接口
      }
     }
    }
  });
}
chat.on(TencentCloudChat.EVENT.MESSAGE_READ_RECEIPT_RECEIVED, onMessageReadReceiptReceived);

发送端主动拉取消息已读回执信息

发送端从其他界面进入消息列表后，先拉取历史消息，再调用 getMessageReadReceipt 接口拉取消息已读回执信息。
说明：
1. messageList 里的消息必须在同一个 C2C 或 Group 会话中。
2. 社群和直播群不支持群消息已读回执。
接口
chat.getMessageReadReceiptList(messageList);
参数
Name
Type
Description
messageList
Array
同一群会话的消息列表。
返回值
Promise
示例
// 拉取群消息列表
let messageList = null;
chat.getMessageList({conversationID: 'GROUPtest'}).then(function(imResponse) {
  messageList = imResponse.data.messageList; // 消息列表
  chat.getMessageReadReceiptList(messageList).then(function(imResponse) {
    messageList = imResponse.data.messageList; // 消息列表
    // 成功后，Message.readReceiptInfo 包含消息的已读回执信息
    // Message.readReceiptInfo.readCount - 
    // 消息的已读数，如果想要查询哪些群成员已读了此消息，请使用 [getGroupMessageReadMemberList] 接口
    // Message.readReceiptInfo.unreadCount - 消息的未读数，当为0的时候，表示“全部已读”。
  }).catch(function(imError) {
    // 拉取已读回执列表失败
  });
});
// 拉取 C2C 消息列表
let messageList = null;
chat.getMessageList({conversationID: 'C2Ctest'}).then(function(imResponse) {
  messageList = imResponse.data.messageList; // 消息列表
  chat.getMessageReadReceiptList(messageList).then(function(imResponse) {
    messageList = imResponse.data.messageList; // 消息列表
    // 成功后，Message.readReceiptInfo 包含消息的已读回执信息
    // Message.readReceiptInfo.isPeerRead - 对端是否已发送已读回执
  }).catch(function(imError) {
    // 拉取已读回执列表失败
  });
});

发送端主动拉取群消息已读或未读成员列表

发送端在需要查看群消息已读或未读成员列表时，可以调用 getGroupMessageReadMemberList 接口分页拉取消息已读或未读群成员列表。
接口
chat.getGroupMessageReadMemberList(options);
参数
参数 options为 Object类型，包含的属性值如下：
名称
类型
描述
message
Message
消息实例。
cursor
String
分页拉取的游标，第一次拉取传''
filter
Number
指定拉取已读或未读群成员列表。
0 - 拉取已读成员列表
1 - 拉取未读成员列表
count
Number
分页拉取的个数，最大支持 100 个。
返回值
Promise
示例
// 拉取群消息已读成员列表
let promise = chat.getGroupMessageReadMemberList({
  message,
  filter: 0,
  cursor: '', // 第一次拉取传''
  count: 30,
});
promise.then(function(imResponse) {
  const { isCompleted, cursor, messageID, readUserIDList } = imResponse.data;
  // isCompleted - true，拉取完成；false 未完成
  // cursor - 当 isCompleted 为 false 的时候用于续拉
  // messageID - 群消息的 ID
  // readUserIDList - 
  // 已读的群成员 userID 列表。接入侧可调用 getGroupMemberProfile 接口查询群成员的资料，如群名片、头像、昵称等
}).catch(function(imError) {
  // 拉取群消息已读群成员列表失败
});
// 拉取群消息未读成员列表
let promise = chat.getGroupMessageReadMemberList({
  message,
  filter: 1,
  cursor: '', // 第一次拉取传''
  count: 30,
});
promise.then(function(imResponse) {
  const { isCompleted, cursor, messageID, readUserIDList } = imResponse.data;
  // isCompleted - true，拉取完成；false 未完成
  // cursor - 当 isCompleted 为 false 的时候用于续拉
  // messageID - 群消息的 ID
  // unreadUserIDList - 
  // 未读的群成员 userID 列表。接入侧可调用 getGroupMemberProfile 接口查询群成员的资料，如群名片、头像、昵称等
}).catch(function(imError) {
  // 拉取群消息未读群成员列表失败
  // 10062 - 找不到群消息的已读回执信息
});