Skip to main content

One-to-One and Group Chat Read Receipts

The read receipt feature allows message senders to know whether their messages have been read by recipients.

  • In one-to-one chat scenarios, when the recipient reads a message, they can actively send a read receipt to the sender, who receives the read notification by listening for read receipt messages.
  • In group chat scenarios, after the sender sends a message to the group, they can actively initiate a read receipt request. Other group members who read the message can respond to this request. The sender learns which group members have read the message by monitoring read receipt response results.

The SDK provides different event handling mechanisms for read receipt-related events in one-to-one and group chats:

One-to-One Chat Read Receipts​

The one-to-one chat read receipt feature requires the message recipient to pass the message reading timestamp to the sender, who uses this timestamp to track reading progress. The IMLib SDK defines RCSentStatus to record whether a message in a one-to-one conversation has been read by the recipient. You can query the specific read status by checking the sentStatus property of messages sent by the local user.

Sending One-to-One Chat Read Receipts​

After reading a message, the recipient must call the sendReadReceiptMessage:targetId:time:success:error: method with a timestamp to actively send a read receipt to the sender. You can pass either the sending time of a specific message (message.sentTime) or the sending time of the last message in the conversation (conversation.sentTime). The one-to-one chat read receipt is essentially a read notification message constructed and sent internally by the SDK.

[[RCCoreClient sharedCoreClient]
    sendReadReceiptMessage:ConversationType_PRIVATE
    targetId:@"targetId"
    time:sentTime
    success::^{
            
} error:^(RCErrorCode nErrorCode) {
            
}];

Receiving One-to-One Chat Read Receipts​

When the IMLib SDK receives a one-to-one chat message read receipt, it extracts the included timestamp and updates the sentStatus property of all messages in the local message database that were sent before this timestamp to SentStatus_READ. Simultaneously, the IMLib SDK distributes an RCLibDispatchReadReceiptNotification. Applications must register as observers for this notification to receive it.

This code registers the current object (self) as an observer for RCLibDispatchReadReceiptNotification notifications. When this notification is received, the didReceiveReadReceiptNotification: method is called.

[[NSNotificationCenter defaultCenter]
    addObserver:self
    selector:@selector(didReceiveReadReceiptNotification:)
    name:RCLibDispatchReadReceiptNotification
    object:nil];

The didReceiveReadReceiptNotification: method is called when a read receipt notification is received. It takes an NSNotification object as a parameter, which can be used to obtain read receipt notification information.

- (void)didReceiveReadReceiptNotification:(NSNotification *)notification {

    RCConversationType conversationType = (RCConversationType)[notification.userInfo[@"cType"] integerValue];
    long long readTime = [notification.userInfo[@"messageTime"] longLongValue];
    NSString *targetId = notification.userInfo[@"tId"];
    NSString *senderUserId = notification.userInfo[@"fId"];
}

This code extracts the following information from the notification's userInfo dictionary:

  • Conversation type (conversationType)
  • Read time (readTime)
  • Conversation targetId (targetId)
  • Sender userId (senderUserId)

The readTime here is the timestamp carried in the one-to-one chat read receipt message. At this point, the sending status property (sentStatus) of all messages in the message database with a sending time earlier than or equal to readTime has been updated to "read by recipient" (SentStatus_READ). When displaying sent messages in the UI, applications can show all messages sent before this timestamp as "read by recipient."

Group Chat Read Receipts​

The group chat read receipt feature is based on messages' globally unique IDs (messageUId). By passing a message's messageUId in a group conversation, the sender can obtain the reading progress and list of users who have read a specific message. The SDK defines RCReadReceiptInfo to record group chat read receipt data for a message. Applications can query specific statuses by checking the readReceiptInfo property of messages sent by the local user.

The group chat read receipt workflow is as follows:

  1. Group member Alice sends a message to the group. After the message reaches the server, it is delivered to the target group.
  2. Alice wants to know which group members have read the message. As the sender, she can initiate a group message read receipt request for this message.
  3. Other group members monitor Alice's group message read receipt request.
  4. Group member Bob reads Alice's group message and responds to Alice's read receipt request in the group.
  5. As the message sender, Alice can monitor read receipt responses for this message. After receiving Bob's response in the group, she can update the message's read count.

Initiating Group Chat Read Receipt Requests​

After sending a message to a group, the sender must actively initiate a read receipt request to obtain active responses from group members and track the message's read status. In a group conversation, only the message sender can initiate group chat read receipt requests.

After sending a message, the sender uses the sendReadReceiptRequest:success:error: method with the sent RCMessage object to initiate a read receipt request for this message. The IMLib SDK internally constructs and sends a group chat read receipt request message.

[[RCCoreClient sharedCoreClient] sendReadReceiptRequest:message
                                                success:^{
                                                 }error:^(RCErrorCode nErrorCode) {
}];

Receiving Group Chat Read Receipt Requests​

The IMLib SDK defines delegate methods related to group chat read receipts in the RCIMClientReceiveMessageDelegate message receiving protocol.

You can set multiple message receiving delegates using the addReceiveMessageDelegate method after initializing the IMLib SDK but before connecting to IM.

[[RCCoreClient sharedCoreClient] addReceiveMessageDelegate:self];

When any group member initiates a read receipt request, other group members receive it through the onMessageReceiptRequest delegate method in RCIMClientReceiveMessageDelegate.

/*!
 Request message read receipt (receives a request requiring a read receipt response. After receiving this request, when the message corresponding to this messageUId is displayed in the conversation UI or when calling getHistoryMessages to retrieve messages containing this messageUId, you need to call sendMessageReadReceiptResponse to send a message read receipt)

 @param messageUId       Message ID requesting read receipt
 @param conversationType conversationType
 @param targetId         targetId
 */
- (void)onMessageReceiptRequest:(RCConversationType)conversationType
                       targetId:(NSString *)targetId
                     messageUId:(NSString *)messageUId;

The onMessageReceiptRequest method returns the message's messageUId. You can retrieve the message object using the getMessageByUId:completion: method for subsequent read receipt responses. For batch message retrieval, use the getBatchLocalMessages:targetId:channelId:messageUIDs:success:error: method under RCChannelClient.

Responding to Group Chat Read Receipt Requests​

Message recipients can respond to read receipt requests based on the user's reading progress. If multiple requests are received simultaneously, you can batch respond to read receipt requests, but only for requests within the same conversation.

Recipients can use the sendReadReceiptResponse:targetId:messageList:success:error: method with the conversation type, group targetId, and RCMessage object list to initiate a read receipt response. Note that the conversation type must be ConversationType_GROUP.

[[RCCoreClient sharedCoreClient] sendReadReceiptResponse:ConversationType_GROUP
                            targetId:@"targetId"
                            messageList:msgList
                            success:^{

                            }
                            error:^(RCErrorCode nErrorCode){

                            }];

When a group member successfully responds, the requester will receive a notification and response result through the onMessageReceiptResponse method of RCIMClientReceiveMessageDelegate. Note that only the requester can receive the response.

/*!
 Message read receipt response (receiving read receipt responses allows updating message read counts based on messageUId)
 @param messageUId       The message ID for which read receipt was requested
 @param conversationType RCConversationType
 @param targetId         targetId
 @param userIdList List of users who have read the message, in dictionary format key:userId,value:readTime, e.g.: {"uid100001":1683708891523}
 */


- (void)onMessageReceiptResponse:(RCConversationType)conversationType
                        targetId:(NSString *)targetId
                      messageUId:(NSString *)messageUId
                      readerList:(NSMutableDictionary *)userIdList;

The message sender can obtain the message's messageUId and the list of all responding users from the onMessageReceiptResponse method. When displaying this sent message in the UI, you can show the number of readers and the specific list of users who have read it. The IMLib SDK stores the read receipt data for this group message in the message's readReceiptInf property.

Last updated on