逐条消息已读功能

重要提示

• 需要开通单群聊消息云存储服务后，才能使用此功能。
• 逐条消息已读功能从 SDK 1.5.0 版本开始支持。
• 自 2025.11.25 起，新建的 AppKey 且 SDK 版本 ≥ 1.5.0 时，默认开启逐条消息已读功能，单群聊已读回执功能将失效。
• 如果您希望使用原来的单群聊已读回执功能，请提交工单申请切换。
• 逐条消息已读功能依赖历史消息云存储能力，使用前请确认当前 App Key 已开通单群聊消息云端存储服务。您可以在控制台 IM 服务的服务购买页面为当前使用的 App Key 开启服务。如果使用生产环境的 App Key，请注意仅 IM 旗舰版或 IM 尊享版可开通该服务。
• 群成员超过 3000 人时，不支持群聊逐条消息已读功能。

逐条消息已读功能支持逐条设置接收消息的已读状态，支持单聊和群聊会话类型。

发送消息

在发送消息时，如果需要支持已读回执，那么，需要在 Message 中设置 needReceipt 为 true。

消息对象新增属性

参数	类型	说明
needReceipt	boolean	是否支持发送已读回执
sentReceipt	boolean	是否已经发送已读回执

示例代码

TypeScript

    let textMsg = new TextMessage();
    textMsg.content = "hello，逐条消息已读功能";
    let msg = new Message(conId, textMsg);
    msg.needReceipt = true;
    let option: ISendMsgOption = {};
    IMEngine.getInstance().sendMessage(msg, option, (msg: Message) => {

    }).then(result => {
      if (EngineError.Success !== result.code) {
        // 发送消息失败
      } else {
        // 发送消息成功
      }
    })

发送已读回执

消息接收方在阅读过某条消息后，需要主动发送已读回执给发送方。调用sendReadReceiptResponseV5方法，需要传入会话标识（conId）和要发送回执的消息UId数组。

参数说明

参数	类型	说明
conId	ConversationIdentifier	消息所属的会话标识
messageUidArray	Array<string>	发送已读回执的消息数组

示例代码

TypeScript

    let conId = new ConversationIdentifier();
    conId.conversationType = ConversationType.Group;
    conId.targetId = "TestTargetId";

    let msgUidArray = new Array<String>();
    let messageUid1 = "MessageUid1"; // 按需填写实际的 MessageUid
    let messageUid2 = "MessageUid2"; // 按需填写实际的 MessageUid
    msgUidArray.push(messageUid1);
    msgUidArray.push(messageUid2);

    IMEngine.getInstance().sendReadReceiptResponseV5(conId, msgUidArray).then(result2 => {
      if (result2.code == EngineError.Success) {
        // 发送逐条消息已读功能的回执成功
      } else {
        // 发送逐条消息已读功能的回执失败
      }
    })

接收已读回执回调

消息接收方发送已读回执后，消息发送方会收到有人发送已读回执的回调。开发者可以注册已读回执监听 addMessageReadReceiptV5Listener，实现 onMessageReceiptResponse 方法，接收已读回执信息。

参数说明

参数	类型	说明
readReceiptNotifyArray	Array<ReadReceiptResponseV5>	消息已读回执的响应信息 ReadReceiptResponseV5 数组

示例代码

Objective C

class MyReadReceiptListener implements MessageReadReceiptV5Listener {
  onMessageReceiptResponse(
    readReceiptNotifyArray: Array<ReadReceiptResponseV5>
  ): void {
    // 接收到逐条消息已读功能的回执响应
  }
}

IMEngine.getInstance().addMessageReadReceiptV5Listener(listener);

获取消息已读回信息

消息发送者可以通过 getMessageReadReceiptInfoV5 接口，传入会话标识（conId）和消息的 UID 查询对应消息的已读回执信息。

参数说明

参数	类型	说明
conId	ConversationIdentifier	消息所属的会话标识
messageUidArray	Array<string>	获取已读回执的消息数组

示例代码

TypeScript

    let conId = new ConversationIdentifier();
    conId.conversationType = ConversationType.Group;
    conId.targetId = "TestTargetId";

    let msgUidArray = new Array<String>();
    let messageUid1 = "MessageUid1"; // 按需填写实际的 MessageUid
    let messageUid2 = "MessageUid2"; // 按需填写实际的 MessageUid
    msgUidArray.push(messageUid1);
    msgUidArray.push(messageUid2);

    IMEngine.getInstance().getMessageReadReceiptInfoV5(conId, msgUidArray).then(result => {
      if (result.code == EngineError.Success) {
        // 批量获取消息已读信息成功
      } else {
        // 批量获取消息已读信息失败
      }
    });

分页获取已读回执用户列表

消息发送者可以通过 getMessagesReadReceiptUsersByPageV5 接口，分页获取消息的已读回执用户信息列表。

参数说明

参数	类型	说明
conId	ConversationIdentifier	消息所属的会话标识
msgUid	string	消息唯一 ID
option	ReadReceiptUsersOption	分页配置信息

示例代码

TypeScript

    let conId = new ConversationIdentifier();
    conId.conversationType = ConversationType.Group;
    conId.targetId = "TestTargetId";

    let messageUid = "MessageUid"; // 按需填写实际的 MessageUid
    let pageToken = "";
    let count = 10;
    let readStatus = ReadReceiptStatus.Read;
    let order = Order.Descending;

    let option : ReadReceiptUsersOption = new ReadReceiptUsersOption();
    option.pageToken = pageToken;
    option.count = count;
    option.readStatus = readStatus;
    option.order = order;

    IMEngine.getInstance().getMessagesReadReceiptUsersByPageV5(
      conId,
      msgUid,
      option
    ).then(result => {
      if (result.code == EngineError.Success) {
        // 分页获取消息已读成员列表成功
      } else {
        // 分页获取消息已读成员列表失败
      }
    });

获取指定用户的已读回执信息

消息发送者可以通过 getMessagesReadReceiptByUsersV5 接口，获取指定用户的消息已读回执信息。

参数说明

参数	类型	说明
conId	ConversationIdentifier	消息所属的会话标识
msgUid	string	消息唯一 ID
userArray	Array<string>	用户 ID 数组

示例代码

TypeScript

    let conId = new ConversationIdentifier();
    conId.conversationType = ConversationType.Group;
    conId.targetId = "TestTargetId";

    let msgUid = "MessageUid"; // 按需填写实际的 MessageUid

    let userArray = new Array<String>();
    let user1 = "user1"; // 按需填写实际的 user
    let user2 = "user2"; // 按需填写实际的 user
    userArray.push(user1);
    userArray.push(user2);

    IMEngine.getInstance().getMessagesReadReceiptByUsersV5(
      conId,
      msgUid,
      userArray
    ).then(result => {
      if (result.code == EngineError.Success) {
        // 批量获取用户指定群组消息是否已读状态成功
      } else {
        // 批量获取用户指定群组消息是否已读状态失败
      }
    });