# Message receipts (/en/realtime-media/im/build/build-core-messaging/messages/message-receipts/web)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

The Chat SDK provides the message read receipt feature that allows the user, after sending a message, to know whether the message is read. The feature is available to both one-to-one chats and group chats.

    * Message delivery receipt: Available only to one-to-one chats.
    * Message read receipt: Available to both one-to-one chats and group chats.

    ## Understand the tech [#understand-the-tech-2]

    The message delivery receipts and read receipts are implemented as follows:

    * Message delivery receipt for one-to-one chats

      1. The message sender enables delivery receipts by setting `delivery` as `true` when creating the `connection` object during SDK initialization.
      2. A user sends a message.
      3. After the recipient receives the message, the SDK automatically sends a delivery receipt to the sender.
      4. The sender receives the delivery receipt by listening for `onDeliveredMessage`.

    * Conversation and message read receipts for one-to-one chats

      1. A user sends a message.
      2. After reading the message, the recipient calls `send` to send a conversation or message read receipt.
      3. The sender receives the conversation or message receipt by listening for `onChannelMessage` or `onReadMessage`.

    * Message read receipt for group chats

      1. A group member sends a message with `allowGroupAck` set to `true` to request message read receipts.
      2. After reading the message, the recipient calls `send` to send a read receipt.
      3. The sender receives the message read receipt by listening for `onReadMessage` when online or `onStatisticsMessage` when offline.
      4. The sender can know which group members have read the message by calling `getGroupMsgReadUser`.

    ## Prerequisites [#prerequisites-2]

    Before proceeding, ensure that you meet the following requirements:

    * You have integrated the Chat SDK, initialized the SDK and implemented the functionality of registering accounts and login. For details, see [Chat SDK quickstart](../../../../get-started-sdk).
    * You understand the API call frequency limits as described in [Limitations](../../limitations).
    * Message read receipts for chat groups are not enabled by default. To use this feature, contact [support@agora.io](mailto\:support@agora.io).

    ## Implementation [#implementation-2]

    This section introduces how to implement message delivery and read receipts in your chat app.

    ### Message delivery receipts [#message-delivery-receipts-2]

    To send a message delivery receipt, take the following steps:

    1. The message sender sets `delivery` in `options` as `true` when initializing the `connection` object.

       ```javascript
       const chatClient = new AgoraChat.connection({
         appKey: "your appKey",
         delivery: true,
       });
       ```

    2. Once the recipient receives the message, the SDK triggers `onDeliveredMessage` on the message sender's client, notifying that the message has been delivered to the recipient.
       ```javascript
       chatClient.addEventHandler("handlerId", {
         onReceivedMessage: function (message) {}, // Received a receipt for message delivery to the server.
         onDeliveredMessage: function (message) {}, // Received a receipt for message delivery to the client.
       });
       ```

    ### Conversation and message read receipts [#conversation-and-message-read-receipts-2]

    In both one-to-one chats and group chats, you can use message read receipts to notify the message sender that the message has been read. To minimize the method call for message read receipts, the SDK also supports conversation read receipts in one-to-one chats.

    #### One-to-one chat [#one-to-one-chat]

    The one-to-one chats support both conversation read receipts and message read receipts. We recommend you use both types of read receipts together to reduce the number of message read receipts:

    * If several messages are received when the chat page is not opened yet, send a conversation read receipt when the chat page is opened.
    * If a message is received on an open chat page, send a message read receipt.

    ##### Conversation read receipts [#conversation-read-receipts]

    1. The message recipient sends a conversation read receipt.

       The message recipient opens the conversation page to check whether there are unread messages. If yes, call `send` to send a conversation read receipt.

       ```javascript
       const options = {
         chatType: "singleChat", // The chat type: singleChat for one-to-one.
         type: "channel", // The type of read receipt: channel indicates the conversation read receipt.
         to: "userId", // The user ID of the message recipient.
       };
       const msg = AgoraChat.message.create(options);
       chatClient.send(msg);
       ```

    2. The message sender receives the conversation read receipt in the `onChannelMessage` callback.

       ```javascript
       chatClient.addEventHandler("handlerId", {
         onChannelMessage: (message) => {},
       });
       ```

    ##### Message read receipts [#message-read-receipts]

    For one-to-one chats, message read receipts are stored as long as messages on the Chat server. Specifically, message read receipts can be sent whenever the messages are available on the Chat server. The message storage period on the Chat server depends on your product plan. For details, see the [pricing plan details](../../../reference/pricing-plan-details#message).

    Refer to the following steps to implement message read receipt in one-to-one chats:

    1. The message recipient sends a message read receipt.

       * If there are several unread messages in the conversation, to minimize the number of sent message read receipts, we recommend that a conversation read receipt be sent when the message recipient enters the conversation.

         ```javascript
         const options = {
           chatType: "singleChat", // The chat type: singleChat for one-to-one chat.
           type: "channel", // The type of read receipt: channel indicates the conversation read receipt.
           to: "userId", // The user ID of the message receipt.
         };
         const msg = AgoraChat.message.create(options);
         chatClient.send(msg);
         ```

       * If there is only one unread message in the conversation, after reading it, call `send` from the recipient's client to send the message read receipt.

         ```javascript
         const options = {
           type: "read", // The message read receipt.
           chatType: "singleChat", // The chat type: singleChat for one-to-one chat.
           to: "userId", // The user ID of the message receipt.
           id: "id", // The ID of the message that requires the read receipt.
         };
         const msg = AgoraChat.message.create(options);
         chatClient.send(msg);
         ```

    2. The message sender listens for `onReadMessage` to receive the message read receipt.

       ```javascript
       chatClient.addEventHandler("handlerId", {
         onReadMessage: (message) => {},
       });
       ```

    #### Group chat [#group-chat]

    <CalloutContainer type="success">
      <CalloutDescription>
        For group chats, the conversation read receipt is only used to clear the
        unread message count of the group chat on the server. The message sender
        will not receive the conversation read receipt via the `onChannelMessage`
        callback.
      </CalloutDescription>
    </CalloutContainer>

    For a group chat, group members can determine whether to require message read receipts when sending a message. If yes, after a group member reads the message, the SDK sends a read receipt. In a group chat, the number of message read receipts that are sent for the message refers to the number of group members that have read this message.

    | Feature Restriction                                                              | Default           | Description                                                                                                                                                                                                                                                                              | Error                                                                                                                                                                                                      |
    | :------------------------------------------------------------------------------- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Enabling the function                                                            | Disabled          | To use this feature, contact [support@agora.io](mailto\:support@agora.io) to enable it.                                                                                                                                                                                                  | The error 503 "group ack not open" is returned if you fail to enable this feature before using it.                                                                                                         |
    | Permission                                                                       | All group members | By default, all group members can request read receipts when sending a message. You can contact [support@agora.io](mailto\:support@agora.io) to grant the permission only to the group owner and administrators.                                                                         | If you only allow the group owner and administrators to send read receipts, the error "group ack msg permission denied" is returned if regular group members request read receipts when sending a message. |
    | Number of days before read receipts cannot be returned after the message is sent | 3 days            | The server no longer records the group members that read the message three days after it is sent, nor sends the read receipts.                                                                                                                                                           | The error "group ack msg not found" is returned if read receipts are sent three days after the message is sent.                                                                                            |
    | Chat group size                                                                  | 200 members       | This feature is available only to groups with up to 200 members. If the upper limit is exceeded, no read receipts are returned for the message sent within the group. To increase the upper limit of group member count, you can contact [support@agora.io](mailto\:support@agora.io).   |                                                                                                                                                                                                            |
    | View the number of read receipts returned for a group message                    | Message sender    | By default, only the message sender can view the number of read receipts returned for a group message (or the number of group members that have returned the read receipts). To allow all group members to view the count, you can contact [support@agora.io](mailto\:support@agora.io). |                                                                                                                                                                                                            |

    Follow the steps to implement read receipts for a chat group message:

    1. When sending a message, a group member can set whether to require a message read receipt by setting `allowGroupAck` to `true`.

       ```javascript
       sendGroupReadMsg = () => {
          const options = {
              type: 'txt',            // Message type.
              chatType: 'groupChat',  // Conversation type: groupChat for group chat.
              to: 'groupId',          // The message recipient: group ID.
              msg: 'message content'  // Message content.
              msgConfig: { allowGroupAck: true } // Setting that this message requires a read receipt.
          }

         const msg = AgoraChat.message.create(options);
         chatClient.send(msg).then((res) => {
             console.log('send message success');
         }).catch((e) => {
             console.log("send message error");
         })
       }
       ```

    2. After reading the group message, the recipient calls `send` to send the message read receipt.

       ```javascript
       sendReadMsg = () => {
         const options = {
           type: "read", // Whether the message has been read.
           chatType: "groupChat", // Conversation type: groupChat means group chat.
           id: "msgId", // The message ID for which the read receipt is sent.
           to: "groupId", // Group ID.
           ackContent: JSON.stringify({}), // The content of the message read receipt.
         };
         const msg = AgoraChat.message.create(options);
         chatClient.send(msg);
       };
       ```

    3. The message sender receives the message read receipt by listening for either of the following callbacks:

       * `onReadMessage`, when the message sender is online.
       * `onStatisticsMessage`, when the message sender is offline.

         ```javascript
         // You can listen in onReadMessage when online.
         chatClient.addEventHandler("handlerId", {
           onReadMessage: (message) => {
             let { mid } = message;
             let msg = {
               id: mid,
             };
             if (message.groupReadCount) {
               // The message has been read.
               msg.groupReadCount = message.groupReadCount[message.mid];
             }
           },
           // You can listen for onStatisticMessage upon login when the read receipt is received when you are offline.
           onStatisticMessage: (message) => {
             let statisticMsg = message.location && JSON.parse(message.location);
             let groupAck = statisticMsg.group_ack || [];
           },
         });
         ```

    4. After receiving the read receipt, the message sender can retrieve the detailed information of the group members that have read the message.

       ```javascript
       chatClient
         .getGroupMsgReadUser({
           msgId: "messageId", // Message ID.
           groupId: "groupId", // Group ID.
         })
         .then((res) => {
           console.log(res);
         });
       ```