logo
On this page

Read receipts


Note

This document is applicable to the following platforms of Unity framework: iOS, Android, macOS, and Windows.

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.

Warning

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:

  1. Client A and Client B log in to the In-app Chat service.
  2. 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.
  3. By listening for related callback (onReceivePeerMessage or onReceiveGroupMessage), Client B receives a message whose receiptStatus is set to PROCESSING.

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.

Warning
  • 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.

  1. Through related callback (onReceivePeerMessage or onReceiveGroupMessage), Client B receives a message that requires a reading receipt from Client A.
  2. Based on the receiptStatus field of the callback, Client B determines the receipt status of the message. If this field is set to PROCESSING, the message is unread. Developers can call the sendMessageReceiptsRead API to set the message as read based on the service logic.
  3. Client B determines whether the setting is successful based on ZIMMessageReceiptsReadSentCallback.
  4. 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.

Warning
  • 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.

  1. Based on the receiptStatus field of the onReceivePeerMessage callback, Client B determines the receipt status of the message. If this field is set to PROCESSING, 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.
  2. Client B determines whether the setting is successful based on ZIMConversationMessageReceiptReadSentCallback .
  3. 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 ZIMMessageReceiptsInfoQueriedCallback to obtain related information.

Warning
  • 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.

Warning

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.

Warning
  • 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

Untitled
// 1. Create a ZIM object and pass in the appID and appSign
ZIMAppConfig appConfig = new ZIMAppConfig();
appConfig.appID = 12345;  // Replace with the AppID you obtained from the ZEGO Console
appConfig.appSign = "appSign";   // Replace with the AppSign you obtained from the ZEGO Console
ZIM.Create(appConfig);

// 2. Log in
ZIMUserInfo zimUserInfo = new ZIMUserInfo();
zimUserInfo.userID = "xxxx";
zimUserInfo.userName = "xxxx";
ZIM.GetInstance().Login(zimUserInfo, (ZIMError errorInfo) =>
{
    // Developers can use ZIMError to determine if the login is successful.
});

ZIM.GetInstance().onMessageReceiptChanged = (ZIM zim, List<ZIMMessageReceiptInfo> infos) =>
{
    // Group message receipt status changed
};

ZIM.GetInstance().onConversationMessageReceiptChanged = (ZIM zim, List<ZIMMessageReceiptInfo> infos) =>
{
    // Conversation message receipt status changed
};

string conversationID = "xxx"; // Conversation ID

// 3. User A sends a message with receipt, taking a peer-to-peer text message as an example

ZIMTextMessage message = new ZIMTextMessage("test");
ZIMMessageSendConfig sendConfig = new ZIMMessageSendConfig();
sendConfig.hasReceipt = true;    // Set the message with receipt
ZIMMessageSendNotification notification = new ZIMMessageSendNotification();
ZIM.GetInstance().SendMessage(message, "conversationID", ZIMConversationType.Peer, sendConfig, notification,
    (ZIMMessage message, ZIMError errorInfo) => { });

// 4. User B receives the receipt and marks it as read, choose one of the following interfaces

// 4.1 Message read

List<ZIMMessage> messages = new List<ZIMMessage>();
messages.Add(message);
ZIM.GetInstance().SendMessageReceiptsRead(messages, "conversationID", ZIMConversationType.Peer, (string conversationID, ZIMConversationType conversationType,
                   List<long> errorMessageIDs, ZIMError errorInfo) =>
{
    // Callback for sending message read
});

// 4.2 Conversation read

ZIM.GetInstance().SendConversationMessageReceiptRead("conversationID", ZIMConversationType.Peer, (string conversationID, ZIMConversationType conversationType,
                           ZIMError errorInfo) =>
{
    // Callback for sending conversation message read
});

// 5. (Optional) Query the receipt status, unread user count, and read user count for a batch of messages

List<ZIMMessage> queryMessages = new List<ZIMMessage>();
queryMessages.Add(message);
ZIM.GetInstance().QueryMessageReceiptsInfo(queryMessages, "conversationID", ZIMConversationType.Peer, (List<ZIMMessageReceiptInfo> infos, List<long> errorMessageIDs,
                           ZIMError errorInfo) =>
{ });

// 6. (Optional) Query the list of read group members and unread group members for a specific group message

// 6.1 List of read users
ZIMGroupMessageReceiptMemberQueryConfig config = new ZIMGroupMessageReceiptMemberQueryConfig();
config.nextFlag = 0;    // The flag for querying, fill in 0 initially, and then fill in the flag returned from the callback.
config.count = 10;    // The number of users to query.

ZIM.GetInstance().QueryGroupMessageReceiptReadMemberList(message, "groupID", config, (string groupID, List<ZIMGroupMemberInfo> userList,
                           uint nextFlag, ZIMError errorInfo) =>
{ });

// 6.2 List of unread users
ZIMGroupMessageReceiptMemberQueryConfig groupMessageReceiptMemberQueryConfig = new ZIMGroupMessageReceiptMemberQueryConfig();
groupMessageReceiptMemberQueryConfig.nextFlag = 0;    // The flag for querying, fill in 0 initially, and then fill in the flag returned from the callback.
groupMessageReceiptMemberQueryConfig.count = 10;    // The number of users to query.

ZIM.GetInstance().QueryGroupMessageReceiptUnreadMemberList(message, "groupID", groupMessageReceiptMemberQueryConfig, (string groupID, List<ZIMGroupMemberInfo> userList,
                           uint nextFlag, ZIMError errorInfo) => { });
1
Copied!

Previous

Recall messages

Next

Set message extension field