逐条消息已读功能
重要提示
- 需要开通单群聊消息云存储服务后，才能使用此功能。
- 逐条消息已读功能从 SDK 5.20.0 版本开始支持。
- 自 2025.11.25 起，新建的 AppKey 且 SDK 版本 ≥ 5.20.0 时，默认开启逐条消息已读功能，单群聊已读回执功能将失效。
- 如果您希望使用原来的单群聊已读回执功能，请提交工单申请切换。
- 逐条消息已读功能依赖历史消息云存储能力，使用前请确认当前 App Key 已开通单群聊消息云端存储服务。您可以在控制台 IM 服务的服务购买页面为当前使用的 App Key 开启服务。如果使用生产环境的 App Key，请注意仅 IM 旗舰版或 IM 尊享版可开通该服务。
- 群成员超过 3000 人时，不支持群聊逐条消息已读功能。
逐条消息已读功能支持逐条设置接收消息的已读状态，支持单聊和群聊会话类型。
发送消息
若需支持已读回执，发送消息时需要在 RCMessage 中将 needReceipt 设置为 YES。
Objective C
RCMessage *message = ...;
message.needReceipt = YES;
[[RCCoreClient sharedCoreClient] sendMessage:message
pushContent:nil
pushData:nil
attached:^(RCMessage * _Nullable message) {
// message save into db.
} successBlock:^(RCMessage * _Nonnull successMessage) {
// message send success.
} errorBlock:^(RCErrorCode nErrorCode, RCMessage * _Nonnull errorMessage) {
// message send failed.
}];
消息对象新增属性
| 参数 | 类型 | 说明 |
|---|---|---|
needReceipt | BOOL | 是否支持发送已读回执 |
sentReceipt | BOOL | 是否已经发送已读回执 |
发送已读回执
消息接收方在阅读过某条消息后，需要主动发送已读回执给发送方。调用sendReadReceiptResponseV5:messageUIds:completion:方法，需要传入会话标识（identifier）和消息唯一 ID。可以传入指定消息的发送时间（messageUIds）。
| 参数 | 类型 | 说明 |
|---|---|---|
identifier | RCConversationIdentifier | 消息所属的会话标识 |
messageUIds | NSArray | 发送已读回执的消息数组 |
completion | Block | 结果回调 |
Objective C
RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] init];
identifier.type = ConversationType_GROUP;
identifier.targetId = @"tId";
[[RCCoreClient sharedCoreClient] sendReadReceiptResponseV5:identifier
messageUIds:@[@"MessageUID"]
completion:^(RCErrorCode code) {
// send result.
}];
接收已读回执回调
消息接收方发送已读回执后，消息发送方会收到有人发送已读回执的回调。开发者可以注册已读回执监听 addReadReceiptV5Delegate，实现 didReceiveMessageReadReceiptResponses 方法，接收已读回执信息。
| 参数 | 类型 | 说明 |
|---|---|---|
responses | NSArray | 消息已读回 执的响应信息 RCReadReceiptResponseV5 数组 |
Objective C
// 添加已读回执监听。
[[RCCoreClient sharedCoreClient] addReadReceiptV5Delegate:self];
// 在监听回调中处理已读回执信息。
- (void)didReceiveMessageReadReceiptResponses:(NSArray<RCReadReceiptResponseV5 *> *)responses {
// receive responses.
}
获取消息已读回执信息
消息发送者可以通过 getMessageReadReceiptInfoV5:messageUIds:completion: 接口，传入会话标识（identifier）和消息的 UID (messageUIds) 查询对应消息的已读回执信息。
| 参数 | 类型 | 说明 |
|---|---|---|
identifier | RCConversationIdentifier | 消息所属的会话标识 |
messageUIds | NSArray | 查询已读回执的消息 UID 数组 |
completion | Block | 结果回调 |
在获取消息已读回执信息的结果回调中，，infoList 是 RCReadReceiptInfoV5 数组，RCReadReceiptInfoV5 的内容如下：
| 参数 | 类型 | 说明 |
|---|---|---|
messageUId | NSString | 消息 UID |
unreadCount | NSInteger | 未读数量 |
readCount | NSInteger | 已读数量 |
totalCount | NSInteger | 总人数 |
Objective C
RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] init];
identifier.type = ConversationType_GROUP;
identifier.targetId = @"tId";
[[RCCoreClient sharedCoreClient] getMessageReadReceiptInfoV5:identifier
messageUIds:@[@"MessageUId"]
completion:^(NSArray<RCReadReceiptInfoV5 *> * _Nullable infoList, RCErrorCode code) {
// get read receipt info.
}];
批量获取多会话消息已读回执信息
消息发送者可以通过 getMessageReadReceiptInfoV5ByIdentifiers:completion: 接口，查询对应消息的已读回执信息。
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
identifiers | NSArray | 消息标识 [RCMessageIdentifier][RCMessageIdentifier] 数组 |
completion | Block | 结果回调 |
在获取消息已读回执信息的结果回调中，，infoList 是 RCReadReceiptInfoV5 数组，RCReadReceiptInfoV5 的内容如下：
| 参数 | 类型 | 说明 |
|---|---|---|
messageUId | NSString | 消息 UID |
unreadCount | NSInteger | 未读数量 |
readCount | NSInteger | 已读数量 |
totalCount | NSInteger | 总人数 |
示例代码
Objective C
RCConversationIdentifier *conversationIdentifier = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"tId"];
RCMessageIdentifier *identifier = [[RCMessageIdentifier alloc] initWithConversationIdentifier:identifier messageUId:@"mUId"];
[[RCCoreClient sharedCoreClient] getMessageReadReceiptInfoV5ByIdentifiers:@[identifier]
completion:^(NSArray<RCReadReceiptInfoV5 *> * _Nullable infoList, RCErrorCode code) {
// get read receipt info.
}];
分页获取已读回执用户列表
消息发送者可以通过 getMessagesReadReceiptUsersByPageV5:messageUId:option:completion: 接口，分页获取消息的已读回执用户信息列表。
| 参数 | 类型 | 说明 |
|---|---|---|
identifier | RCConversationIdentifier | 消息所属的会话标识 |
messageUId | NSString | 消息唯一 ID |
option | RCReadReceiptUsersOption | 分页配置信息 |
completion | Block | 结果回调 |
在分页获取已读回执用户列表中，result 是查询结果的封装信息 RCReadReceiptUsersResult，其内容如下：
| 参数 | 类型 | 说明 |
|---|---|---|
users | NSArray | 查询到的用户（RCReadReceiptUser）列表 |
pageToken | NSString | 分页 Token，如果返回为空，表示没有下一页 |
totalCount | NSInteger | 用户总数 |
Objective C
RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] init];
identifier.type = ConversationType_GROUP;
identifier.targetId = @"tId";
RCReadReceiptUsersOption *option = [[RCReadReceiptUsersOption alloc] init];
// 如果为空，返回第一页数据，返回的 `RCReadReceiptUsersResult` 中带有下一页的 pageToken。
option.pageToken = @"page token";
option.pageCount = 20;
option.order = RCOrderDescending;
option.readReceiptStatus = RCReadReceiptStatusResponse;
[[RCCoreClient sharedCoreClient] getMessagesReadReceiptUsersByPageV5:identifier
messageUId:@"MessageUId"
option:option
completion:^(RCReadReceiptUsersResult * _Nullable result, RCErrorCode code) {
// get read receipt user list.
}];
获取指定用户的已读回执信息
消息发送者可以通过 getMessagesReadReceiptByUsersV5:messageUId:userIds:completion: 接口，获取指定用户的消息已读回执信息。
| 参数 | 类型 | 说明 |
|---|---|---|
identifier | RCConversationIdentifier | 消息所属的会话标识 |
messageUId | NSString | 消息唯一 ID |
userIds | NSArray | 用户 ID 数组 |
completion | Block | 结果回调 |
在获取指定用户的已读回执信息中，result 是查询结果的封装信息 RCReadReceiptUsersResult，其内容如下：
| 参数 | 类型 | 说明 |
|---|---|---|
users | NSArray | 查询到的用户（RCReadReceiptUser）列表 |
pageToken | NSString | 分页 Token，本接口中不生效，可忽略 |
totalCount | NSInteger | 用户总数，本接口中不生效，可忽略 |
Objective C
RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] init];
identifier.type = ConversationType_GROUP;
identifier.targetId = @"tId";
[[RCCoreClient sharedCoreClient] getMessagesReadReceiptByUsersV5:identifier
messageUId:@"MessageUId"
userIds:@[@"uId"]
completion:^(RCReadReceiptUsersResult * _Nullable result, RCErrorCode code) {
// get read receipt user list.
}];