群聊消息回执

重要提示

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

功能描述

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

注意

在群聊场景中，建议由用户根据需要手动发起已读回执请求，避免对每条消息自动请求，减少已读回执消息量，避免影响用户体验。

实现思路

1. 群成员 A 向群组发送一条消息，消息首先到达融云服务端，再由服务端转发至目标群组内的其他成员。

2. 消息发送后，建议在 UI 上为发件人提供一个“查看已读状态”按钮（建议展示 1～2 分钟）。发件人点击按钮，即发起群消息已读回执请求（sendReadReceiptRequest）。

3. 群组内其他成员监听到该回执请求事件（MESSAGE_RECEIPT_REQUEST），在查看该消息后，主动发送回执响应（sendReadReceiptResponseV2）。

4. 发件人监听群内回执响应事件，实时更新已读信息展示：

• 5.9.3 及之前版本：需在本地维护消息回执数据，例如：

  JavaScript

    user_targetId_type: {
      'messageUid': ['userId1', 'userId2']
    }

  在展示历史消息时，根据缓存匹配已读人数及详情。

• 5.9.4 及之后版本：

  1. SDK 内部自动维护已读回执请求记录，历史消息数据中包含 readReceiptInfo 字段。
  2. Web 平台：SDK 会缓存每个群会话的最新 30 条回执请求（按发送时间排序），缓存有效期 24 小时。发送回执响应时无需传递 messageList，SDK 会自动整理对应消息后上报。
  3. Electron 平台：需先拉取历史消息，筛选 message.messageDirection = MessageDirection.RECEIVE 且 readReceiptInfo.isReceiptRequestMessage = true 且 readReceiptInfo.hasRespond = false 的消息，组织成 messageList 参数，发送回执响应。

群聊已读回执时序图

发起已读回执请求

当群成员希望获取已发送消息的阅读状态数据时，可调用 sendReadReceiptRequest 方法发起回执请求。

接口

JavaScript

RongIMLib.sendReadReceiptRequest(targetId, messageUId)

参数说明

参数	类型	必填	说明
targetId	string	是	目标会话 ID
messageUId	string	是	需要查询阅读状态的消息 messageUId

示例代码

JavaScript

RongIMLib.sendReadReceiptRequest('targetId', 'BS4S-U34I-T4G6-9GPP')
  .then((res) => {
    if (res.code === 0) {
      console.log(res.code, res.data)
    } else {
      console.log(res.code, res.msg)
    }
  })
  .catch((error) => {
    console.log(error)
  })

响应已读回执请求

提示

自 5.1.1 版本起，废弃 sendReadReceiptResponse() 方法，新增 sendReadReceiptResponseV2 方法。

群内其他成员监听到回执请求事件后，需在阅读消息后，调用 sendReadReceiptResponseV2 方法发送已读回执响应，可以一次响应同一会话中多个用户的多条消息。

接口

JavaScript

RongIMLib.sendReadReceiptResponseV2(targetId, messageList, channelId)

参数说明

参数	类型	必填	说明
targetId	string	是	目标会话 ID
messageList	{ [senderUserId: string]: string[] }	否	需发送回执的消息列表。自 5.9.4 起，Web 平台无需传此参数
channelId	string	否	频道 ID

示例代码

JavaScript

const messageList = {
  '<用户Id1>': ['messageUId1', 'messageUId2'],
  '<用户Id2>': ['messageUId3', 'messageUId4']
};

RongIMLib.sendReadReceiptResponseV2('<targetId>', messageList).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 onMessageReceiptRequest({conversation, messageUId, senderUserId}) {
    // conversation 群组会话
    // messageUId 需要回执的消息UId
    // senderUserId 消息发送者Id
    console.log(conversation, messageUId, senderUserId)
}
RongIMLib.addEventListener(
  Events.MESSAGE_RECEIPT_REQUEST,
  onMessageReceiptRequest
)

监听消息回执响应事件

通过 addEventListener 方法，设置针对消息回执响应的监听器，用于接收消息回执。

示例代码

JavaScript

const Events = RongIMLib.Events
function onMessageReceiptResponse({conversation, receivedUserId, messageUIdList}) {
    // conversation 群组会话
    // receivedUserId 为消息接收者，即谁响应了之前发送的消息回执请求
    // messageUIdList 为 消息接收者已查看了的消息UId列表
    console.log(conversation, receivedUserId, messageUIdList)
}
RongIMLib.addEventListener(
  Events.MESSAGE_RECEIPT_RESPONSE,
  onMessageReceiptResponse
)