跳到主要内容

逐条消息已读功能

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

逐条消息已读功能支持对每条消息分别处理已读状态，并提供消息级别的已读明细查询能力。

发送消息时开启逐条消息已读功能​

如需支持逐条消息已读功能，发送前需将消息对象的 needReceipt 设置为 true。

示例代码​

提示

以下示例中，engine 是已初始化的 RCIMIWEngine 实例。关于如何初始化 SDK，请参考初始化文档。

Dart
final RCIMIWTextMessage? message = await engine.createTextMessage(
  RCIMIWConversationType.private,
  "targetId",
  null,
  "hello",
);
message?.needReceipt = true;

await engine.sendMessage(
  message!,
  callback: RCIMIWSendMessageCallback(
    onMessageSaved: (msg) {},
    onMessageSent: (code, msg) {},
  ),
);

消息对象新增属性​

参数类型说明
needReceiptbool是否支持发送已读回执（发送前配置）
sentReceiptbool是否已发送已读回执（SDK 内部维护）

发送已读回执​

消息接收方在阅读消息后，可调用 sendReadReceiptResponseV5 通知发送方已读。

方法​

Dart
Future<int> sendReadReceiptResponseV5(
  RCIMIWConversationType type,
  String targetId,
  String? channelId,
  List<String> messageUIds, {
  IRCIMIWSendReadReceiptResponseV5Callback? callback,
});

参数说明​

参数名参数类型描述
typeRCIMIWConversationType会话类型，仅支持单聊和群聊
targetIdString会话目标 ID
channelIdString?频道 ID，非超级群场景可传 null
messageUIdsList<String>消息 UID 列表，最多 100 条
callbackIRCIMIWSendReadReceiptResponseV5Callback结果回调（onSuccess / onError）

代码示例​

Dart
await engine.sendReadReceiptResponseV5(
  RCIMIWConversationType.group,
  "groupId",
  null,
  ["messageUId1"],
  callback: IRCIMIWSendReadReceiptResponseV5Callback(
    onSuccess: () {},
    onError: (code) {},
  ),
);

接收已读回执回调​

消息发送方可通过监听 onMessageReadReceiptV5Received 接收已读回执响应。

监听器​

Dart
Function(List<RCIMIWReadReceiptResponseV5>? responses)? onMessageReadReceiptV5Received;

回调对象说明（RCIMIWReadReceiptResponseV5）​

参数类型说明
conversationTypeRCIMIWConversationType?会话类型
targetIdString?会话目标 ID
channelIdString?频道 ID
messageUIdString?消息 UID
usersList<RCIMIWReadReceiptUser>?已读用户列表
readCountint?已读人数
unreadCountint?未读人数
totalCountint?总人数

示例代码​

提示

监听器应在 SDK 初始化完成后、连接成功前注册，以确保能够及时接收已读回执通知。

Dart
// 监听远端会话列表同步完成
engine.onMessageReadReceiptV5Received = (responses) {
  // 处理回执响应
};

获取消息已读信息（批量）​

消息发送方可调用 getMessageReadReceiptInfoV5 批量查询消息已读统计信息。

方法​

Dart
Future<int> getMessageReadReceiptInfoV5(
  RCIMIWConversationType type,
  String targetId,
  String? channelId,
  List<String> messageUIds, {
  IRCIMIWGetMessageReadReceiptInfoV5Callback? callback,
});

参数说明​

参数名参数类型描述
typeRCIMIWConversationType会话类型
targetIdString会话目标 ID
channelIdString?频道 ID
messageUIdsList<String>待查询消息 UID 列表，最多 100 条
callbackIRCIMIWGetMessageReadReceiptInfoV5Callback结果回调（onSuccess 返回 List<RCIMIWReadReceiptInfoV5>?）

结果对象说明（RCIMIWReadReceiptInfoV5）​

参数类型说明
messageUIdString?消息 UID
readCountint?已读数
unreadCountint?未读数
totalCountint?总人数

示例代码​

Dart
await engine.getMessageReadReceiptInfoV5(
  RCIMIWConversationType.group,
  "groupId",
  null,
  ["messageUId1", "messageUId2"],
  callback: IRCIMIWGetMessageReadReceiptInfoV5Callback(
    onSuccess: (infos) {},
    onError: (code) {},
  ),
);

按消息标识批量获取多会话已读信息​

消息发送方可调用 getMessageReadReceiptInfoV5ByIdentifiers，批量查询多会话消息的已读统计信息。

方法​

Dart
Future<int> getMessageReadReceiptInfoV5ByIdentifiers(
  List<RCIMIWMessageIdentifier> identifiers, {
  IRCIMIWGetMessageReadReceiptInfoV5Callback? callback,
});

参数说明​

参数名参数类型描述
identifiersList<RCIMIWMessageIdentifier>消息标识列表，最多 100 条
callbackIRCIMIWGetMessageReadReceiptInfoV5Callback结果回调（onSuccess 返回 List<RCIMIWReadReceiptInfoV5>?）

消息标识对象说明（RCIMIWMessageIdentifier）​

参数类型说明
conversationTypeRCIMIWConversationType?会话类型，仅支持单聊和群聊
targetIdString?会话目标 ID
channelIdString?频道 ID，非超级群场景可传 null
messageUIdString?消息 UID

示例代码​

Dart
final identifiers = <RCIMIWMessageIdentifier>[
  RCIMIWMessageIdentifier.create(
    conversationType: RCIMIWConversationType.private,
    targetId: "targetId1",
    channelId: null,
    messageUId: "messageUId1",
  ),
  RCIMIWMessageIdentifier.create(
    conversationType: RCIMIWConversationType.group,
    targetId: "groupId1",
    channelId: null,
    messageUId: "messageUId2",
  ),
];

await engine.getMessageReadReceiptInfoV5ByIdentifiers(
  identifiers,
  callback: IRCIMIWGetMessageReadReceiptInfoV5Callback(
    onSuccess: (infos) {},
    onError: (code) {},
  ),
);

分页获取消息已读用户​

消息发送方可调用 getMessagesReadReceiptUsersByPageV5 分页查询指定消息的已读/未读用户。

方法​

Dart
Future<int> getMessagesReadReceiptUsersByPageV5(
  RCIMIWConversationType type,
  String targetId,
  String? channelId,
  String messageUId,
  RCIMIWReadReceiptUsersOption option, {
  IRCIMIWGetMessagesReadReceiptUsersByPageV5Callback? callback,
});

参数说明​

参数名参数类型描述
typeRCIMIWConversationType会话类型
targetIdString会话目标 ID
channelIdString?频道 ID
messageUIdString消息 UID
optionRCIMIWReadReceiptUsersOption分页与筛选参数
callbackIRCIMIWGetMessagesReadReceiptUsersByPageV5Callback结果回调（onSuccess 返回 RCIMIWReadReceiptUsersResult?）

查询参数说明（RCIMIWReadReceiptUsersOption）​

参数类型说明
pageTokenString?分页标识，首次调用可传空
pageCountint?每页条数
orderRCIMIWReadReceiptOrder?排序方式：descending / ascending
readStatusRCIMIWReadReceiptStatus?状态筛选：read / unread

返回对象说明（RCIMIWReadReceiptUsersResult）​

参数类型说明
pageTokenString?下一页分页标识，空表示无更多数据
totalCountint?总用户数
usersList<RCIMIWReadReceiptUser>?当前页用户列表

用户对象说明（RCIMIWReadReceiptUser）​

参数类型说明
userIdString?用户 ID
timestampint?回执时间戳（毫秒）

示例代码​

Dart
await engine.getMessagesReadReceiptUsersByPageV5(
  RCIMIWConversationType.group,
  "groupId",
  null,
  "messageUId1",
  RCIMIWReadReceiptUsersOption.create(
    pageToken: "",
    pageCount: 20,
    order: RCIMIWReadReceiptOrder.descending,
    readStatus: RCIMIWReadReceiptStatus.read,
  ),
  callback: IRCIMIWGetMessagesReadReceiptUsersByPageV5Callback(
    onSuccess: (result) {},
    onError: (code) {},
  ),
);

获取指定用户的消息已读信息​

消息发送方可调用 getMessagesReadReceiptByUsersV5 查询指定用户在某条消息上的已读状态。

方法​

Dart
Future<int> getMessagesReadReceiptByUsersV5(
  RCIMIWConversationType type,
  String targetId,
  String? channelId,
  String messageUId,
  List<String> userIds, {
  IRCIMIWGetMessagesReadReceiptByUsersV5Callback? callback,
});

参数说明​

参数名参数类型描述
typeRCIMIWConversationType会话类型
targetIdString会话目标 ID
channelIdString?频道 ID
messageUIdString消息 UID
userIdsList<String>用户 ID 列表，最多 100 个
callbackIRCIMIWGetMessagesReadReceiptByUsersV5Callback结果回调（onSuccess 返回 RCIMIWReadReceiptUsersResult?）

返回对象 RCIMIWReadReceiptUsersResult 中：

  • users 为查询到的用户（RCIMIWReadReceiptUser）列表
  • pageToken 在本接口中不生效，可忽略
  • totalCount 在本接口中不生效，可忽略

代码示例​

Dart
await engine.getMessagesReadReceiptByUsersV5(
  RCIMIWConversationType.group,
  "groupId",
  null,
  "messageUId1",
  ["user1", "user2"],
  callback: IRCIMIWGetMessagesReadReceiptByUsersV5Callback(
    onSuccess: (result) {},
    onError: (code) {},
  ),
);