Delivery & Read Receipts

Mark messages as delivered, read, or unread and receive real-time receipt events using the CometChat Flutter SDK.

AI Integration Quick Reference

Field	Value
Key Classes	MessageReceipt, BaseMessage, Conversation
Key Methods	CometChat.markAsDelivered(), CometChat.markAsRead(), CometChat.markMessageAsUnread(), CometChat.getMessageReceipts()
Listener Events	onMessagesDelivered, onMessagesRead, onMessagesDeliveredToAll, onMessagesReadByAll
Prerequisites	SDK initialized, user logged in

// Mark message as delivered
CometChat.markAsDelivered(message, onSuccess: (String unused) {
  debugPrint("Marked as delivered");
}, onError: (CometChatException e) {
  debugPrint("Error: ${e.message}");
});

// Mark message as read
CometChat.markAsRead(message, onSuccess: (String unused) {
  debugPrint("Marked as read");
}, onError: (CometChatException e) {
  debugPrint("Error: ${e.message}");
});

// Mark message as unread
CometChat.markMessageAsUnread(message, onSuccess: (Conversation conversation) {
  debugPrint("Marked as unread");
}, onError: (CometChatException e) {
  debugPrint("Error: ${e.message}");
});

// Listen for receipts
CometChat.addMessageListener("receipts_listener", MessageListener(
  onMessagesDelivered: (MessageReceipt receipt) { },
  onMessagesRead: (MessageReceipt receipt) { },
  onMessagesDeliveredToAll: (MessageReceipt receipt) { },
  onMessagesReadByAll: (MessageReceipt receipt) { },
));

// Remove listener when done
CometChat.removeMessageListener("receipts_listener");

Delivery and read receipts allow you to track when messages have been delivered to and read by recipients, providing real-time feedback on message status.

Available via: SDK | REST API | UI Kits

Mark Messages as Delivered

In other words, as a recipient, how do I inform the sender that I’ve received a message?

You can mark the messages for a particular conversation as delivered using the markAsDelivered() method. This method takes a BaseMessage object as input.

Parameter	Type	Description
message	BaseMessage	The message object to mark as delivered. All messages before this message in the conversation will be marked as delivered.
onSuccess	Function(String)	Callback triggered on success with a confirmation string.
onError	Function(CometChatException)	Callback triggered on error with exception details.

Messages for both user & group conversations can be marked as delivered using this method.

Ideally, you would like to mark all the messages as delivered for any conversation when the user opens the chat window for that conversation. This includes two scenarios:

1. When the list of messages for the conversation is fetched: In this case you need to obtain the last message in the list of messages and pass the message to the markAsDelivered() method.
2. When the user is on the chat window and a real-time message is received: In this case you need to obtain the message and pass it to the markAsDelivered() method.

This method will mark all the messages before the message specified, for the conversation with receiverId and receiverType (user/group) as delivered.

In case you would like to be notified of an error if the receipts fail to go through you can use markAsDelivered() method with the callbacks as shown below:

Dart

CometChat.markAsDelivered(message, onSuccess: (String unused) {
  debugPrint("markAsDelivered : $unused ");
}, onError: (CometChatException e) {
  debugPrint("markAsDelivered unsuccessful : ${e.message} ");
});

Response

On Success — A String message confirming the message has been marked as delivered:

Parameter	Type	Description	Sample Value
message	String	Success confirmation message	"markAsDelivered success"

Error

Parameter	Type	Description	Sample Value
code	String	Error code identifier	"ERR_CHAT_API_FAILURE"
message	String	Human-readable error message	"Failed to mark the message as delivered."
details	String	Additional technical details	"An unexpected error occurred while processing the request."

Mark Messages as Read

In other words, as a recipient, how do I inform the sender I’ve read a message?

You can mark the messages for a particular conversation as read using the markAsRead() method. This method takes a BaseMessage object as input.

Parameter	Type	Description
baseMessage	BaseMessage	The message object to mark as read. All messages before this message in the conversation will be marked as read.
onSuccess	Function(String)	Callback triggered on success with a confirmation string.
onError	Function(CometChatException)	Callback triggered on error with exception details.

Messages for both user and group conversations can be marked as read using this method.

Ideally, you should mark all the messages as read for any conversation when the user opens the chat window for that conversation. This includes two scenarios:

1. When the list of messages for the conversation is fetched: In this case you need to obtain the last message in the list of messages and pass the message to the markAsRead() method.
2. When the user is on the chat window and a real-time message is received: In this case you need to obtain the message and pass it to the markAsRead() method

This method will mark all the messages before the message specified, for the conversation with receiverId and receiverType (user/group) as read.

Another option the CometChat SDK provides is to pass the entire message object to the markAsRead() method. If the message object is the last message, the entire conversation will be marked as read.

Dart

CometChat.markAsRead(message)

In case you would like to be notified of an error if the receipts fail to go through you can use the markAsRead() method with the callbacks as shown below:

Dart

CometChat.markAsRead(message, onSuccess: (String unused) {
    debugPrint("markAsRead : $unused ");
    reinitiateList();
  }, onError: (CometChatException e) {
    debugPrint("markAsRead unsuccessfull : ${e.message} ");
  }); 

Response

On Success — A String message confirming the message has been marked as read:

Parameter	Type	Description	Sample Value
message	String	Success confirmation message	"markAsRead success"

Error

Parameter	Type	Description	Sample Value
code	String	Error code identifier	"ERR_CHAT_API_FAILURE"
message	String	Human-readable error message	"Failed to mark the message as read."
details	String	Additional technical details	"An unexpected error occurred while processing the request."

Mark Messages as Unread

The Mark as Unread feature allows users to designate specific messages or conversations as unread, even if they have been previously viewed.

This feature is valuable for users who want to revisit and respond to important messages or conversations later, ensuring they don’t forget or overlook them.

In other words, how I can mark message as unread?

You can mark the messages for a particular conversation as unread using the markMessageAsUnread() method.

Parameter	Type	Description
baseMessage	BaseMessage	To mark a message as unread, pass a non-null BaseMessage instance. All messages below that message in the conversation will contribute to the unread messages count.
onSuccess	Function(Conversation)	Callback triggered on success with the updated Conversation object containing the new unread count.
onError	Function(CometChatException)	Callback triggered on error with exception details.

Example: When User B sends User A a total of 10 messages, and User A invokes the markMessageAsUnread() method on the fifth message, all messages located below the fifth message within the conversation list will be designated as unread. This results in a notification indicating there are 5 unread messages in the conversation list.

Dart

CometChat.markMessageAsUnread(
  message,
  onSuccess: (Conversation conversation) {
    debugPrint("markMessageAsUnread : $conversation");
  },
  onError: (CometChatException error) {
    debugPrint("markMessageAsUnread unsuccessful : $error");
  },
);

Response

On Success — A Conversation object with the updated unread message count:

Parameter	Type	Description	Sample Value
conversationId	String	Unique identifier for the conversation	"user_superhero1"
conversationType	String	Type of conversation	"user" or "group"
unreadMessageCount	int	Updated unread message count	5
lastMessage	BaseMessage	The last message in the conversation	Message object

Error

Parameter	Type	Description	Sample Value
code	String	Error code identifier	"ERR_CHAT_API_FAILURE"
message	String	Human-readable error message	"Failed to mark the message as unread."
details	String	Additional technical details	"An unexpected error occurred while processing the request."

Receive Delivery & Read Receipts

In other words, as a recipient, how do I know when a message I sent has been delivered or read by someone?

Real-time Events

Register a MessageListener to receive delivery and read receipt events.

Callback	Description
onMessagesDelivered	Message delivered to a user
onMessagesRead	Message read by a user
onMessagesDeliveredToAll	Group message delivered to all members
onMessagesReadByAll	Group message read by all members

Dart

class Class_Name  with MessageListener {

//CometChat.addMessageListener("listenerId", this);
@override
void onMessagesDelivered(MessageReceipt messageReceipt) {
  // TODO: implement onMessagesDelivered
}

@override
void onMessagesRead(MessageReceipt messageReceipt) {
 // TODO: implement onMessagesRead
}

@override
void onMessagesDeliveredToAll(MessageReceipt messageReceipt) {
  // TODO: implement onMessagesDeliveredToAll
}

@override
void onMessagesReadByAll(MessageReceipt messageReceipt) {
 // TODO: implement onMessagesReadByAll
}

}

Always remove listeners when they’re no longer needed (e.g., in the dispose() method). Failing to remove listeners can cause memory leaks and duplicate event handling.

@override
void dispose() {
  CometChat.removeMessageListener("listenerId");
  super.dispose();
}

You will receive events in the form of MessageReceipt objects. The message receipt contains the following parameters:

Parameter	Type	Description
messageId	int	The ID of the message prior to which all the messages for that particular conversation have been marked as read.
sender	User	User object containing the details of the user who has marked the message as read.
receiverId	String	Id of the receiver whose conversation has been marked as read.
receiverType	String	Type of the receiver (user/group)
receiptType	String	Type of the receipt (read/delivered)
deliveredAt	DateTime	The timestamp of the time when the message was delivered. This will only be present if the receiptType is delivered.
readAt	DateTime	The timestamp of the time when the message was read. This will only be present when the receiptType is read.

Missed Receipts

You will receive message receipts when you load offline messages. While fetching messages in bulk, the message object will have two fields i.e. deliveredAt and readAt which hold the timestamp for the time the message was delivered and read respectively. Using these two variables, the delivery and read status for a message can be obtained.

However, for a group message, if you wish to fetch the deliveredAt and readAt fields of individual member of the group you can use the below-described method.

Receipt History for a Single Message

To fetch the message receipts, you can use the getMessageReceipts() method. This is useful for group messages to see which members have received/read the message.

Parameter	Type	Description
messageId	int	The ID of the message for which receipts are to be fetched.
onSuccess	Function(List<MessageReceipt>)	Callback triggered on success with a list of MessageReceipt objects.
onError	Function(CometChatException)	Callback triggered on error with exception details.

Dart

int messageId = 10101;

CometChat.getMessageReceipts(messageId, onSuccess: (List<MessageReceipt> messageReceipts) {
  debugPrint("Message receipts fetched: $messageReceipts");
}, onError: (CometChatException e) {
  debugPrint("Error fetching receipts: ${e.message}");
});

Response

On Success — A List<MessageReceipt> containing receipt details for each group member:

Parameter	Type	Description	Sample Value
messageId	int	The ID of the message	10101
sender	User	User who triggered the receipt	User object
receiverId	String	ID of the receiver	"superhero1"
receiverType	String	Type of receiver	"user" or "group"
receiptType	String	Type of receipt	"delivered" or "read"
deliveredAt	DateTime	Timestamp when delivered	DateTime object
readAt	DateTime	Timestamp when read	DateTime object

Error

Parameter	Type	Description	Sample Value
code	String	Error code identifier	"ERR_CHAT_API_FAILURE"
message	String	Human-readable error message	"Failed to fetch message receipts."
details	String	Additional technical details	"An unexpected error occurred while processing the request."

You will receive a list of MessageReceipt objects in the onSuccess() callback.

The following features will be available only if the Enhanced Messaging Status feature is enabled for your app.

• onMessagesDeliveredToAll event,
• onMessagesReadByAll event,
• deliveredAt field in a group message,
• readAt field in a group message.
• markMessageAsUnread method.

---

Next Steps

Receive Messages

Handle incoming messages in real-time

Typing Indicators

Show when users are typing

Retrieve Conversations

Fetch conversation list with unread counts

All Real-Time Listeners

Complete reference for all SDK event listeners