Per-Message Read Receipt Feature

tip

• The per-message read receipt feature (Message Read V5) is supported starting from SDK version 5.20.0.
• Before using this feature, submit a ticket to enable the per-message read receipt functionality. Once enabled, the One-to-One and Group Chat Read Receipt feature will be disabled.

The per-message read receipt feature (Message Read V5) supports setting read status for each received message individually and is compatible with both one-to-one and group chat conversation types.

Sending Messages

To support read receipts, set needReceipt to YES in the RCMessage object when sending a message.

    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.
    }];

New Message Object Properties

Parameter	Type	Description
needReceipt	BOOL	Whether to enable read receipts for the message
sentReceipt	BOOL	Whether the read receipt has been sent

Sending Read Receipts

After reading a message, the recipient must actively send a read receipt to the sender. Call the sendReadReceiptResponseV5:messageUIds:completion: method, passing the conversation identifier (identifier) and message unique IDs (messageUIds). You can specify the send time of the messages.

Parameter	Type	Description
identifier	RCConversationIdentifier	Conversation identifier for the message
messageUIds	NSArray	Array of message UIDs for which read receipts are being sent
completion	Block	Result callback

    RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] init];
    identifier.type = ConversationType_GROUP;
    identifier.targetId = @"tId";
    [[RCCoreClient sharedCoreClient] sendReadReceiptResponseV5:identifier
                                                   messageUIds:@[@"MessageUID"]
                                                    completion:^(RCErrorCode code) {
        // send result.
    }];

Receiving Read Receipt Callbacks

When a recipient sends a read receipt, the sender will receive a callback. Developers can register a read receipt listener using addReadReceiptV5Delegate and implement the didReceiveMessageReadReceiptResponses method to handle read receipt information.

Parameter	Type	Description
responses	NSArray	Array of RCReadReceiptResponseV5 objects containing read receipt responses

// Add read receipt listener
[[RCCoreClient sharedCoreClient] addReadReceiptV5Delegate:self];

// Handle read receipt information in the callback
- (void)didReceiveMessageReadReceiptResponses:(NSArray<RCReadReceiptResponseV5 *> *)responses {
    // receive responses.
}

Retrieving Message Read Receipt Information

Message senders can query read receipt information for specific messages using the getMessageReadReceiptInfoV5:messageUIds:completion: interface by providing the conversation identifier (identifier) and message UIDs (messageUIds).

Parameter	Type	Description
identifier	RCConversationIdentifier	Conversation identifier for the message
messageUIds	NSArray	Array of message UIDs to query
completion	Block	Result callback

In the result callback, infoList contains an array of RCReadReceiptInfoV5 objects with the following properties:

Parameter	Type	Description
messageUId	NSString	Message UID
unreadCount	NSInteger	Number of unread users
readCount	NSInteger	Number of users who have read
totalCount	NSInteger	Total number of users

    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.
    }];

Batch Retrieving Read Receipt Information for Multiple Conversations

Message senders can query read receipt information for multiple messages across conversations using the getMessageReadReceiptInfoV5ByIdentifiers:completion: interface.

Parameter Description

Parameter	Type	Description
identifiers	NSArray	Array of message identifiers [RCMessageIdentifier]
completion	Block	Result callback

In the result callback, infoList contains an array of RCReadReceiptInfoV5 objects with the following properties:

Parameter	Type	Description
messageUId	NSString	Message UID
unreadCount	NSInteger	Number of unread users
readCount	NSInteger	Number of users who have read
totalCount	NSInteger	Total number of users

Example Code

    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.
    }];

Paginated Retrieval of Read Receipt User List

Message senders can paginate through the list of users who have read a message using the getMessagesReadReceiptUsersByPageV5:messageUId:option:completion: interface.

Parameter	Type	Description
identifier	RCConversationIdentifier	Conversation identifier to which the message belongs
messageUId	NSString	Message unique ID
option	RCReadReceiptUsersOption	Pagination configuration
completion	Block	Result callback

In the paginated retrieval of read receipt user list, result encapsulates the query results as RCReadReceiptUsersResult with the following content:

Parameter	Type	Description
users	NSArray	List of queried users (RCReadReceiptUser)
pageToken	NSString	Pagination token - if empty, indicates no more pages
totalCount	NSInteger	Total user count

    RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] init];
    identifier.type = ConversationType_GROUP;
    identifier.targetId = @"tId";
    RCReadReceiptUsersOption *option = [[RCReadReceiptUsersOption alloc] init];
    // If empty, returns first page data with next page's pageToken in `RCReadReceiptUsersResult`
    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.
    }];


## Retrieving Read Receipt Information for Specified Users

Message senders can use the `getMessagesReadReceiptByUsersV5:messageUId:userIds:completion:` interface to retrieve read receipt information for specified users.

| Parameter | Type | Description |
| :-------- | :-------- | :--------- |
| identifier | RCConversationIdentifier | Conversation identifier to which the message belongs |
| messageUId | NSString | Message unique ID |
| userIds | NSArray | Array of user IDs |
| completion | Block | Result callback |

When retrieving read receipt information for specified users, `result` encapsulates the query results as `RCReadReceiptUsersResult` with the following content:

| Parameter | Type | Description |
| :-------- | :-------- | :--------- |
| users | NSArray | List of queried users (`RCReadReceiptUser`) |
| pageToken | NSString | Pagination token (not applicable for this interface, can be ignored) |
| totalCount | NSInteger | Total user count (not applicable for this interface, can be ignored) |

```objectivec
    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.
    }];