Message receipts

After a user sends a message to another chat user or chat group, this user expects to know whether the message is delivered or read. The Chat SDK provides the message receipt feature, which enables you to send a receipt to the message sender once the message is delivered or read.

This page introduces how to use the Chat SDK to implement message receipt functionalities in one-to-one chats and chat groups.

The Chat SDK uses ChatManager to provide message receipt. Followings are the core methods:

• ChatOptions.setRequireAck: Enables message read receipt.
• ChatOptions.setRequireDeliveryAck: Enables message delivery receipt.
• ackConversationRead: Sends a conversation read receipt.
• ackMessageRead: Sends a message read receipt.
• ackGroupMessageRead: Sends a message read receipt for group chat.

The logic for implementing these receipts are as follows:

• Message delivery receipts

  1. The message sender enables delivery receipts by setting ChatOptions.setRequireDeliveryAck as true.
  2. After the recipient receives the message, the SDK automatically sends a delivery receipt to the sender.
  3. The sender receives the delivery receipt by listening for onMessageDelivered.

• Conversation and message read receipts

  1. The message sender enables read receipt by setting ChatOptions.setRequireAck as true.
  2. After reading the message, the recipient calls ackConversationRead or ackMessageRead to send a conversation or message read receipt.
  3. The sender receives the conversation or message receipt by listening for onConversationRead or onMessageRead.

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.

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

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

1. The message sender sets setRequireDeliveryAck in ChatOptions as true before sending the message:

   
   

   _1

   options.setRequireDeliveryAck(true);

   
   

2. Once the recipient receives the message, the SDK triggers onMessageDelivered on the message sender's client, notifying the message sender that the message has been delivered to the recipient.

   
   

   _11

   // Add a message listener to listen for the receipt message.

   _11

   MessageListener msgListener = new MessageListener() {

   _11

   // Occurs when the message is received.

   _11

   @Override

   _11

   public void onMessageReceived(List<ChatMessage> messages) {

   _11

   }

   _11

   // Occurs when the message deliery receipt is received

   _11

   @Override

   _11

   public void onMessageDelivered(List<ChatMessage> message) {

   _11

   }

   _11

   };

   
   

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.

In one-to-one chats, the SDK supports sending both the conversation read receipts and message read receipts. Agora recommends using conversation read receipts if the new message arrives when the message recipient has not entered the conversation UI.

• Conversation read receipts

  Follow the steps to implement conversation read receipts in one-to-one chats.

  1. When a user enters the conversation UI, check whether the conversation contains unread messages. If yes, call ackConversationRead to send a conversation read receipt.
  
  

  _7

  // The message receiver calls ackConversationRead to send the conversation read receipt.

  _7

  // This is an asynchronous method.

  _7

  try {

  _7

  ChatClient.getInstance().chatManager().ackConversationRead(conversationId);

  _7

  } catch (ChatException e) {

  _7

  e.printStackTrace();

  _7

  }

  
  
  2. The message sender listens for message events and receives the conversation read receipt in onConversationRead.
  
  

  _9

  // The message sender calls addConversationListener to listen for conversation events.

  _9

  ChatClient.getInstance().chatManager().addConversationListener(new ConversationListener() {

  _9

  ...

  _9

  @Override

  _9

  // Occurs when the all the messages in the conversation is read.

  _9

  public void onConversationRead(String from, String to) {

  _9

  // Add follow-up logics such as poping up a notification.

  _9

  }

  _9

  });

  
  
  In scenarios where a user is logged in multiple devices, if the user sends a conversation read receipt from one device, the server sets the count of unread messages in the conversation as 0, and all the other devices receive onConversationRead.

• Message read receipts

  To implement the message read receipt, take the following steps:

  1. Send a conversation read receipt when the recipient enters the conversation.
  
  

  _6

  // The message receiver calls ackMessageRead to send the conversation read receipt.

  _6

  try {

  _6

  ChatClient.getInstance().chatManager().ackMessageRead(conversationId);

  _6

  }catch (ChatException e) {

  _6

  e.printStackTrace();

  _6

  }

  
  
  2. When a new message arrives, send the message read receipt and add proper handling logics for the different message types.
  
  

  _31

  ChatClient.getInstance().chatManager().addMessageListener(new MessageListener() {

  _31

  ......

  _31

  _31

  @Override

  _31

  // Occurs when the specified message is received.

  _31

  public void onMessageReceived(List<ChatMessage> messages) {

  _31

  ......

  _31

  // Send the message read receipt.

  _31

  sendReadAck(message);

  _31

  ......

  _31

  }

  _31

  ......

  _31

  });

  _31

  // Send the message read receipt.

  _31

  public void sendReadAck(ChatMessage message) {

  _31

  // For messages in one-to-one chat

  _31

  if(message.direct() == ChatMessage.Direct.RECEIVE

  _31

  undefined message.getChatType() == ChatMessage.ChatType.Chat) {

  _31

  ChatMessage.Type type = message.getType();

  _31

  // For voice, video, and file messages, you need to send the receipt after clicking the files.

  _31

  if(type == ChatMessage.Type.VIDEO || type == ChatMessage.Type.VOICE || type == ChatMessage.Type.FILE) {

  _31

  return;

  _31

  }

  _31

  try {

  _31

  // Call ackMessageRead to send the message read receipt.

  _31

  ChatClient.getInstance().chatManager().ackMessageRead(message.getFrom(), message.getMsgId());

  _31

  } catch (ChatException e) {

  _31

  e.printStackTrace();

  _31

  }

  _31

  }

  _31

  }

  
  
  3. The message sender listens for the message receipt:
  
  

  _10

  // The message sender calls addMessageListener to listen for message events.

  _10

  ChatClient.getInstance().chatManager().addMessageListener(new MessageListener() {

  _10

  ......

  _10

  @Override

  _10

  // Occurs when the specified message is read.

  _10

  public void onMessageRead(List<ChatMessage> messages) {

  _10

  // Add follow-up logics such as poping up a notification.

  _10

  }

  _10

  ......

  _10

  });

  
  

In group chats, you can use message read receipts to notify the group owner or admins that the chat group message has been read. Ensure that each group member that has read the message should send a message read receipt.

Follow the steps to implement chat message read receipts.

1. For chat group messages, the group owner and admins can set to require the message read receipt when sending the message.

   
   

   _3

   // Set setIsNeedGroupAck as true when sending the group message

   _3

   ChatMessage message = ChatMessage.createTxtSendMessage(content, to);

   _3

   message.setIsNeedGroupAck(true);

   
   

2. After the group member reads the chat group message, call sendAckMessage from the group member's client to send a message read receipt:

   
   

   _27

   // Send the group message read receipt.

   _27

   public void sendAckMessage(ChatMessage message) {

   _27

   if (!validateMessage(message)) {

   _27

   return;

   _27

   }

   _27

   _27

   if (message.isAcked()) {

   _27

   return;

   _27

   }

   _27

   _27

   // May a user login from multiple devices, so do not need to send the ack msg.

   _27

   if (ChatClient.getInstance().getCurrentUser().equalsIgnoreCase(message.getFrom())) {

   _27

   return;

   _27

   }

   _27

   _27

   try {

   _27

   if (message.isNeedGroupAck() && !message.isUnread()) {

   _27

   String to = message.conversationId(); // do not use getFrom() here

   _27

   String msgId = message.getMsgId();

   _27

   ChatClient.getInstance().chatManager().ackGroupMessageRead(to, msgId, ((TextMessageBody)message.getBody()).getMessage());

   _27

   message.setUnread(false);

   _27

   EMLog.i(TAG, "Send the group ack cmd-type message.");

   _27

   }

   _27

   } catch (Exception e) {

   _27

   EMLog.d(TAG, e.getMessage());

   _27

   }

   _27

   }

   
   

3. The message sender listens for the message read receipt.

   
   

   _4

   // Occurs when the group message is read.

   _4

   void onGroupMessageRead(List<GroupReadAck> groupReadAcks) {

   _4

   // Add follow-up notifications

   _4

   }

   
   

4. The message sender can get the detailed informaiton of the read receipt using asyncFetchGroupReadAcks.

   
   

   _8

   /**

   _8

   * Fetches the details of the group message read receipt.

   _8

   * @param msgId The message ID.

   _8

   * @param pageSize The page size.

   _8

   * @param startAckId The receipt ID from which you want to fetch. If you set it as null, the SDK fetches from the latest receipt.

   _8

   * @return The message receipt list and a cursor.

   _8

   */

   _8

   public void asyncFetchGroupReadAcks(final String msgId, final int pageSize,final String startAckId, final ValueCallBack<CursorResult<GroupReadAck>> callBack) {}