Read receipts
Overview
Message reading receipt helps users know whether other users have read the messages they sent in a session. This feature applies to enterprise office businesses and other scenarios in which the message reading status needs to be known in real time.
This document describes how to use APIs of the In-app Chat SDK to send messages that require a reading receipt, query the receipt status of messages, and set messages as read.
The In-app Chat SDK supports reading receipts for one-to-one messages and group messages (only common messages and rich media messages) and does not support reading receipts for in-room messages.
Implementation process
The sender sends a message through the In-app Chat SDK and sets the hasReceipt
field of ZIMMessageSendConfig to identify whether a reading receipt is required for the message. Based on the receiptStatus
field, the receiver determines whether a reading receipt is required for the message or whether the message is read or unread to render different UI effects. The message receiver can use different reading methods based on the scenario.
Send a message that requires a reading receipt
When Client A wants to send a message that requires a reading receipt to Client B:
- Client A and Client B log in to the In-app Chat service.
- Client A calls the sendMessage or sendMediaMessage API to send a message (common message or rich media message in one-to-one or group chats) to Client B and sets the
hasReceipt
field of ZIMMessageSendConfig to true. - By listening for related callback (onReceivePeerMessage or onReceiveGroupMessage), Client B receives a message whose
receiptStatus
is set toPROCESSING
.
Set the reading receipt status as read
In this operation, set a message as read
and set a session as read
are both supported.
Set a message as read
The receiver can set a message that requires a reading receipt from the sender as read. Then, the sender will receive a message read notification.
-
A single message or a batch of messages are supported. The sender and receiver must be in the same session. Cross-session operations are not supported.
-
To perform operations on the historical messages of the conversation, you need to get the historical messages and determine the receipt status of the historical messages. For details, see Get message history.
- Through related callback (onReceivePeerMessage or onReceiveGroupMessage), Client B receives a message that requires a reading receipt from Client A.
- Based on the
receiptStatus
field of the callback, Client B determines the receipt status of the message. If this field is set toPROCESSING
, the message is unread. Developers can call the sendMessageReceiptsRead API to set the message as read based on the service logic. - Client B determines whether the setting is successful based on ZIMMessageReceiptsReadSentCallback.
- Based on onMessageReceiptChanged of ZIMEventHandler, Client A receives a callback notification, indicating that the message is set as read. Developers can implement the service logic of setting the message as read on Client A based on this callback.
Set a session as read
The receiver can set all messages received from the sender in a specified session as read.
-
The In-app Chat SDK supports this feature only in one-to-one chats.
-
This feature takes effect only on messages received before setting the feature.
-
It is recommended that this feature be used when a user switches from the session list page to a session. It is not recommended that this feature be used together with the sendMessageReceiptsRead API on a message chat page.
-
To perform operations on the historical messages of the conversation, you need to get the historical messages and determine the receipt status of the historical messages. For details, see Get message history.
- Based on the
receiptStatus
field of the onReceivePeerMessage callback, Client B determines the receipt status of the message. If this field is set toPROCESSING
, the message is unread. Developers can call the sendConversationMessageReceiptRead API to set all messages sent by Client A in the session as read based on the service logic. - Client B determines whether the setting is successful based on ZIMConversationMessageReceiptReadSentResult .
- Based on onConversationMessageReceiptChanged of ZIMEventHandler , Client A receives a callback notification, indicating that all messages in the session are set as read. Developers can implement the logic of setting all messages sent from the sender in the session as read based on this callback. Developers can implement the service logic of knowing all sent messages in a session are set as read by Client B on Client A based on this callback.
More features
Batch query the message receipt status, number of users who have read the message, and number of users who have not read the message
To query the message receipt status, the number of users who have read the message, and the number of users who have not read the message of a message or a batch of messages, call the queryMessageReceiptsInfo API. Call ZIMMessageReceiptsInfoQueriedResult to obtain related information.
-
If messages sent by other users are queried, the number of users who have read the message and the number of users who have not read the message are 0.
-
To perform operations on the historical messages of the conversation, you need to get the historical messages and determine the receipt status of the historical messages. For details, see Get message history.
Query the list of members who have or have not read a group message
The In-app Chat SDK supports querying the list of members who have or have not read a group message.
Query the list of members who have read a group message
To query the list of members who have read a group message, call the queryGroupMessageReceiptReadMemberList API.
To perform operations on the historical messages of the conversation, you need to get the historical messages and determine the receipt status of the historical messages. For details, see Get message history.
Query the list of members who have not read a group message
To query the list of members who have not read a group message, call the queryGroupMessageReceiptUnreadMemberList API.
-
If the SDK version is older than 2.16.0, when the number of group members is greater than 100, this API will not return the list of members who have not read a group message. To use this feature, contact ZEGOCLOUD technical support.
-
To perform operations on the historical messages of the conversation, you need to get the historical messages and determine the receipt status of the historical messages. For details, see Get message history.
Sample code
// 1. Create an In-app Chat object and introduce the appID, appSign, and Application in Android.
ZIMAppConfig appConfig = ZIMAppConfig();
appConfig.appID = 12345; // Enter the appID you applied for from the ZEGOCLOUD Admin Console.
appConfig.appSign = "appSign"; // Enter the appSign you applied for from the ZEGOCLOUD Admin Console.
zim = ZIM.create(appConfig);
// 2. Log in to the In-app Chat service.
try{
ZIMLoginConfig loginConfig = ZIMLoginConfig();
// The user's nickname, leave it blank if you don't want to modify the nickname
loginConfig.userName = 'userName';
// If using token as the login authentication method, please fill in this parameter, otherwise no need to fill in
loginConfig.token = '';
// Whether this login is an offline login, please refer to the offline login related documentation for details
loginConfig.isOfflineLogin = false;
await ZIM.getInstance()?.login('zego', loginConfig);
// Login successful, write the business logic for successful login
} on PlatformException catch(onError){
// Login failed
// Error code for login failure, please refer to the error code table in the integration documentation to handle
onError.code;
// Error message for login failure
onError.message;
}
ZIMEventHandler.onReceivePeerMessage = (zim, messageList, fromUserID) {
// Receive private chat messages
};
ZIMEventHandler.onMessageReceiptChanged = (zim, infos) {
// The other party has set the message read receipt
= };
ZIMEventHandler.onConversationMessageReceiptChanged = (zim, infos) {
// The other party has set the conversation read receipt
};
String conversationID = "xxx" ; // The conversation ID
// 3. User A sends a message that requires a reading receipt. A text one-to-one message is used as an example.
ZIMTextMessage message = ZIMTextMessage(message: "test");
ZIMMessageSendConfig sendConfig = ZIMMessageSendConfig();
sendConfig.hasReceipt = true; // Set that the messages require a reading receipt.
ZIM
.getInstance()!
.sendMessage(
message, conversationID, ZIMConversationType.peer, sendConfig)
.then((result) {
// This indicates that the message is sent successfully. receiptStatus of the message is set to PROCESSING. The service layer can display the logic that a message is unread based on this flag.
})
.catchError((onError) {
});
// 4. User B receives the message that requires a reading receipt and sets the message as read by calling any of the following APIs.
// 4.1 Set a message as read
List<ZIMMessage> messages = [];
ZIM
.getInstance()!
.sendMessageReceiptsRead(
messages, conversationID, ZIMConversationType.peer)
.then((result) {
// Callback for setting a message as read.
})
.catchError((onError) {
});
// 4.2 Set a session as read
ZIM
.getInstance()!
.sendConversationMessageReceiptRead(
conversationID, ZIMConversationType.peer)
.then((value) {
// A session is read. Developers can listen for this callback to set all messages sent by the sender in this session as read.
})
.catchError((onError) {
});
// 5. (Optional) Batch query the message receipt status, number of users who have read the message, and number of users who have not read the message.
List<ZIMMessage> messages = [];
ZIM
.getInstance()!
.queryMessageReceiptsInfo(
messages, conversationID, ZIMConversationType.peer)
.then((value) {
// The status and quantity of this batch of messages are queried, and the corresponding message ID and count are obtained by traversing the information.
})
.catchError((onError) {});
// 6. (Optional) Query the list of members who have or have not read a group message.
// 6.1 The list of members who have read a group message
ZIMGroupMessageReceiptMemberQueryConfig config =
ZIMGroupMessageReceiptMemberQueryConfig();
config.nextFlag = 0; // The query flag. It is set to 0 in the first query. In subsequent queries, it is set to the flag returned in the callback.
config.count = 10; // The user quantity to be queried.
ZIM
.getInstance()!
.queryGroupMessageReceiptReadMemberList(message, groupID, config)
.then((result) {
// The corresponding member list is queried.
})
.catchError((onError) {
});
// 6.2 The list of members who have not read a group message
ZIMGroupMessageReceiptMemberQueryConfig config = ZIMGroupMessageReceiptMemberQueryConfig();
config.nextFlag = 0; // The query flag. It is set to 0 in the first query. In subsequent queries, it is set to the flag returned in the callback.
config.count = 10; // The user quantity to be queried.
ZIM
.getInstance()!
.queryGroupMessageReceiptUnreadMemberList(message, groupID, config)
.then((result) {
// The corresponding member list is queried.
})
.catchError((onError) {
});