Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Message receipts

Updated

Introduces how to use the Agora Chat SDK to implement message receipt functionalities in one-to-one chats and chat groups.

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

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

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.
  • You understand the API call frequency limits as described in Limitations.
  • Message read receipts for chat groups are not enabled by default. To use this feature, contact support@agora.io.

Implementation

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

Message delivery receipts

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.

    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.

    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

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

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

  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.

    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.

    chatClient.addEventHandler("handlerId", {
  onChannelMessage: (message) => {},
});
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.

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.

      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.

      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.

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

Group chat

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.

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 RestrictionDefaultDescriptionError
Enabling the functionDisabledTo use this feature, contact 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.
PermissionAll group membersBy default, all group members can request read receipts when sending a message. You can contact 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 sent3 daysThe 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 size200 membersThis 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.
View the number of read receipts returned for a group messageMessage senderBy 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.

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.

    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.

    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.

      // 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.

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

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved