跳到主要内容
版本：5.X

单聊消息回执

重要提示
  • 自 2025.11.25 起，新建的 App Key 且 SDK 版本 ≥ 5.20.0 时，默认开启逐条消息已读功能，本功能（单聊已读回执）将失效。
  • 如果 SDK 版本 < 5.20.0，默认使用本功能（单聊已读回执），因为该版本尚未支持逐条消息已读功能。
  • 如果 SDK 版本 ≥ 5.20.0 但需要使用本功能，请提交工单申请切换。

功能描述​

消息回执是一种通信机制，用于实时反馈消息的阅读状态。通过该功能，消息发送方可以确认接收方是否已实际查看消息内容，提升消息交互体验。

实现思路​

消息已读回执功能的实现方式在 Web 平台与 Electron 平台存在差异，具体流程如下：

Web

  1. 当用户查看某单聊会话内的未读消息后，调用 sendReadReceiptMessage 方法发送已读回执。
  2. 通过 addEventListener方法，设置消息回执监听器。
  3. SDK 在收到消息已读回执时，触发 READ_RECEIPT_RECEIVED 事件。需注意：Web 平台 SDK 不会持久化记录各会话及消息的已读状态，您需自行在 localStorage 中记录每个会话的已读时间。
  4. 在渲染消息列表时，根据 localStorage 中记录的已读时间与消息列表的 sentTime 比较，当 sentTime 小于已读时间时，表示已读，进而更新对应消息的界面状态。

Electron

  1. 当用户查看某单聊会话内的未读消息后，调用 sendReadReceiptMessage 方法发送已读回执。
  2. 通过 addEventListener方法，设置消息回执监听器。
  3. SDK 在收到消息已读回执时，触发 READ_RECEIPT_RECEIVED 事件。
  4. Electron 平台收到该事件通知后，需调用 electronExtension.setMessageStatusToRead 方法更新消息状态，并刷新对应消息界面。

发送回执​

通过 sendReadReceiptMessage方法，向指定会话中发送消息已读回执。

注意

调用 sendReadReceiptMessage 方法仅用于发送回执，不会同步清除未读消息数。如需清除未读数，请单独调用相应接口。

接口​

JavaScript
RongIMLib.sendReadReceiptMessage(targetId, messageUId, timestamp)

参数说明​

参数类型必填说明
targetIdstring是目标会话 ID
messageUIdstring是已读消息的唯一 ID
timestampnumber是当前会话内已读的最后一条消息的发送时间戳（即 message.sentTime）

示例代码​

JavaScript
const messageUId = 'BS4O-QEBR-VJM6-9GPP';
const timestamp = 1632728573423;

RongIMLib.sendReadReceiptMessage('targetId', messageUId, timestamp).then(res => {
  if (res.code === 0) {
    console.log(res.code, res.data)
  } else {
    console.log(res.code, res.msg)
  }
}).catch(error => {
  console.log(error)
})

设置消息回执监听器​

通过 addEventListener 方法设置消息回执监听器，用于接收回执通知。

示例代码​

JavaScript
const Events = RongIMLib.Events
function onReadReceiptReceived({conversation, messageUId, sentTime}) {
    console.log(conversation, messageUId, sentTime)
}
RongIMLib.addEventListener(Events.READ_RECEIPT_RECEIVED, onReadReceiptReceived);

移除消息回执监听​

应用生命周期结束时，建议通过 removeEventListener 方法移除已绑定的事件监听，避免内存泄漏。

示例代码​

JavaScript
RongIMLib.removeEventListener(Events.READ_RECEIPT_RECEIVED, onReadReceiptReceived);