Delivery & Read Receipts - CometChat Docs

Quick Reference for AI Agents & Developers

Mark delivered: CometChat.markAsDelivered(messageId:receiverId:receiverType:senderId:onSuccess:onError:)
Mark read: CometChat.markAsRead(messageId:receiverId:receiverType:senderId:onSuccess:onError:)
Listen for receipts: onMessagesDelivered(_:), onMessagesRead(_:) in message listener delegate
Related: Send Message · Receive Message · Messaging Overview

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 read using the markAsDelivered() method. This method takes the below parameters as input:

messageId	The ID of the message above which all the messages for a particular conversation are to be marked as read.
receiverId	In the case of one-to-one conversation, the sender’s sender `UID` will be the receipt’s receiver Id. In case of group conversation message’s receiver Id will be the receipt’s receiver Id.
receiverType	Type of the receiver. Could be either of the two values( user or group)
messageSender	The UID of the sender of the message.

Messages for both user conversation and group conversation can be marked as delivered 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:

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 ID of that message to the markAsDelivered() method.
When the user is on the chat window and a real-time message is received: In this case you need to obtain the message ID of the message and pass it to the markAsDelivered() method.

Swift (User)
Swift (Group)
Objective C (User)
Objective C (Group)

var messageId = 123
var receiverId = "cometchat-uid-2"
var senderId = "cometchat-uid-1"
CometChat.markAsDelivered(messageId: messageId, receiverId: receiverId, receiverType: .user, messageSender: senderId)

var messageId = 123
var receiverId = "cometchat-uid-2"
var senderId = "cometchat-uid-1"
CometChat.markAsDelivered(messageId: messageId, receiverId: receiverId, receiverType: .group, messageSender: senderId)

[CometChat markAsDeliveredWithMessageId:messageId receiverId:receiverId receiverType: ReceiverTypeUser messageSender:messageSender]

[CometChat markAsDeliveredWithMessageId:messageId receiverId:receiverId receiverType: ReceiverTypeUser messageSender:messageSender]

This method will mark all the messages before the messageId specified, for the conversation with receiverId and receiverType(user/group) as read. 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:

Swift (User)
Swift (Group)
Objective C (User)
Objective C (Group)

var messageId = 123
var receiverId = "cometchat-uid-2"
var senderId = "cometchat-uid-1"
CometChat.markAsDelivered(messageId: messageId, receiverId: receiverId, receiverType: .user, messageSender: senderId, onSuccess: {
    print("markAsDelivered Succces")
}, onError: {(error) in
  print("markAsDelivered error message",error?.errorDescription)
})

var messageId = 123
var receiverId = "cometchat-uid-2"
var senderId = "cometchat-uid-1"
CometChat.markAsDelivered(messageId: messageId, receiverId: receiverId, receiverType: .group, messageSender: senderId, onSuccess: {
    print("markAsDelivered Succces")
}, onError: {(error) in
  print("markAsDelivered error message",error?.errorDescription)
})

int messageId = 123;
NSString *receiverId = @"cometchat-uid-2";
NSString *senderId = @"cometchat-uid-1";
[CometChat markAsDeliveredWithMessageId:messageId receiverId:receiverId receiverType: ReceiverTypeUser messageSender:messageSender onSuccess:^{
    NSLog(@"markAsDelivered Success");
} onError:^(CometChatException *error){
  NSLog(@"markAsDelivered error message %@",[error errorDescription]);
}];

int messageId = 123;
NSString *receiverId = @"cometchat-uid-2";
NSString *senderId = @"cometchat-uid-1";
[CometChat markAsDeliveredWithMessageId:messageId receiverId:receiverId receiverType: ReceiverTypeGroup messageSender:messageSender onSuccess:^{
    NSLog(@"markAsDelivered Success");
} onError:^(CometChatException *error){
  NSLog(@"markAsDelivered error message %@",[error errorDescription]);
}];

Another option the CometChat SDK provides is to pass the entire message object to the markAsDelivered() method.

Swift
Objective C

CometChat.markAsDelivered(baseMessage : baseMessage)

[CometChat markAsDeliveredWithBaseMessage:baseMessage];

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:

Swift
Objective C

CometChat.markAsDelivered(baseMessage : baseMessage, onSuccess: {
    print("markAsDelivered Succces")
}, onError: {(error) in
  print("markAsDelivered error message",error?.errorDescription)
})

[CometChat markAsDeliveredWithBaseMessage:baseMessage onSuccess:^{
    NSLog(@"markAsDelivered Success");
} onError:^(CometChatException *error){
  NSLog(@"markAsDelivered error message %@",[error errorDescription]);
}];

Starting v3, the messages will not be marked delivered internally by the SDK. You will have to use the markAsDelivered() method. You will either have to use one of the above method signatures to mark the messages as delivered.

Sample Payloads - markAsDelivered

Request
Success Response
Error Response

// CometChat.markAsDelivered - REQUEST
messageId: 37799
messageSender: cometchat-uid-3
receiverId: cometchat-uid-3
receiverType: 0

// CometChat.markAsDelivered - SUCCESS
status: success

// CometChat.markAsDelivered - ERROR RESPONSE
// Object Type: CometChatException

errorCode: ERROR_INTERNET_UNAVAILABLE
errorDescription: No internet connection available. Please check your network settings.

Mark Conversation as Delivered

You can mark an entire conversation as delivered for a user or group using the markConversationAsDelivered method. This method takes the below parameters as input:

Parameter	Information
`conversationWith`	The ID of the user (UID) or group (GUID) for the conversation.
`conversationType`	Type of the conversation. Could be either `user` or `group`.
`onSuccess`	The callback listener that will be called on success.
`onError`	The callback listener that will be called on error.

This method will mark all messages in the conversation as delivered.

Swift (User)
Swift (Group)

CometChat.markConversationAsDelivered(conversationWithId: (conversation.conversationWith as? User)?.uid, receiverType: .user) { message in
  print(message)
} onError: { error in
  print(error.errorDescription)
}

CometChat.markConversationAsDelivered(conversationWithId: (conversation.conversationWith as? Group)?.guid, receiverType: .group) { message in
  print(message)
} onError: { error in
  print(error.errorDescription)
}

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 the below parameters as input:

Parameter	Information
messageId	The ID of the message above which all the messages for a particular conversation are to be marked as read.
receiverId	In case of one to one conversation message’s sender `UID` will be the receipt’s receiver Id. In case of group conversation message’s receiver Id will be the receipts’s receiver Id
receiverType	type of the receiver. Could be either of the two values( user or group)
messageSender	The UID of the sender of the message.

Messages for both user & group conversations can be marked as read using this method. Ideally, you would like to mark all the messages as read for any conversation when the user opens the chat window for that conversation. This includes two scenarios:

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 ID of that message to the markAsRead() method.
When the user is on the chat window and a real-time message is received: In this case you need to obtain the message ID of the message and pass it to the markAsRead() method

Swift (User)
Swift (Group)
Objective C (User)
Objective C (Group)

var messageId = 123
var receiverId = "abc"
var senderId = "xyz"

CometChat.markAsRead(messageId: messageId, receiverId: receiverId, receiverType: .user, messageSender: senderId)

var messageId = 123
var receiverId = "abc"

CometChat.markAsRead(messageId: messageId, receiverId: receiverId, receiverType: .group)

int messageId = 123;
NSString *receiverId = "abc";

[CometChat markAsReadWithMessageId:messageId receiverId:receiverId receiverType:ReceiverTypeUser];

int messageId = 123;
NSString *receiverId = "abc";

[CometChat markAsReadWithMessageId:messageId receiverId:receiverId receiverType:ReceiverTypeUser];

This method will mark all the messages before the messageId specified, for the conversation with receiverId and receiverType(user/group) as read. 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:

Swift (User)
Swift (Group)
Objective C (User)
Objective C (Group)

var messageId = 123
var receiverId = "cometchat-uid-2"
var senderId = "cometchat-uid-1"
CometChat.markAsRead(messageId: messageId, receiverId: receiverId, receiverType: .user, messageSender: senderId, onSuccess: {
    print("markAsRead Succces")
}, onError: {(error) in
  print("markAsRead error message",error?.errorDescription)
})

var messageId = 123
var receiverId = "cometchat-uid-2"
var senderId = "cometchat-uid-1"
CometChat.markAsRead(messageId: messageId, receiverId: receiverId, receiverType: .group, messageSender: senderId, onSuccess: {
    print("markAsRead Succces")
}, onError: {(error) in
  print("markAsRead error message",error?.errorDescription)
})

int messageId = 123;
NSString *receiverId = "abc";

[CometChat markAsReadWithMessageId:messageId receiverId:receiverId receiverType:ReceiverTypeUser onSuccess:^{
    NSLog(@"markAsRead Success");
} onError:^(CometChatException *error){
  NSLog(@"markAsRead error message %@",[error errorDescription]);
}];

int messageId = 123;
NSString *receiverId = "abc";

[CometChat markAsReadWithMessageId:messageId receiverId:receiverId receiverType:ReceiverTypeGroup onSuccess:^{
    NSLog(@"markAsRead Success");
} onError:^(CometChatException *error){
  NSLog(@"markAsRead error message %@",[error errorDescription]);
}];

Another option the CometChat SDK provides is to pass the entire message object to the markAsRead() method.

Swift
Objective C

CometChat.markAsRead(baseMessage : baseMessage)

[CometChat markAsReadWithBaseMessage: baseMessage];

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:

Swift
Objective C

var messageId = 123
var receiverId = "cometchat-uid-2"
var senderId = "cometchat-uid-1"
CometChat.markAsRead(baseMessage : baseMessage, onSuccess: {
    print("markAsRead Succces")
}, onError: {(error) in
  print("markAsRead error message",error?.errorDescription)
})

[CometChat markAsReadWithBaseMessage: baseMessage onSuccess:^{
    NSLog(@"markAsRead Success");
} onError:^(CometChatException *error){
  NSLog(@"markAsRead error message %@",[error errorDescription]);
}];

Starting v3, the markAsRead() method working with v2.x is deprecated and will not work. You will either have to use one of the above method signatures to mark the messages as read.

Sample Payloads - markAsRead

Request
Success Response
Error Response

// CometChat.markAsRead - REQUEST
messageId: 37799
messageSender: cometchat-uid-3
receiverId: cometchat-uid-3
receiverType: 0

// CometChat.markAsRead - SUCCESS
status: success

// CometChat.markAsRead - ERROR RESPONSE
// Object Type: CometChatException

errorCode: ERROR_INTERNET_UNAVAILABLE
errorDescription: No internet connection available. Please check your network settings.

Mark Conversation as Read

You can mark an entire conversation as read for a user or group using the markConversationAsRead method. This method takes the below parameters as input:

Parameter	Information
`conversationWith`	The ID of the user (UID) or group (GUID) for the conversation.
`conversationType`	Type of the conversation. Could be either `user` or `group`.
`onSuccess`	The callback listener that will be called on success.
`onError`	The callback listener that will be called on error.

This method will mark all messages in the conversation as read.

Swift (User)
Swift (Group)

CometChat.markConversationAsRead(conversationWithId: (conversation.conversationWith as? User)?.uid, receiverType: .user) { message in
  print(message)
} onError: { error in
  print(error.errorDescription)
}

CometChat.markConversationAsRead(conversationWithId: (conversation.conversationWith as? Group)?.guid, receiverType: .group) { message in
  print(message)
} onError: { error in
  print(error.errorDescription)
}

Mark Messages as Unread

The Mark message 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 a message as unread? You can mark the messages for a particular conversation as unread using the markMessageAsUnread method. This method takes the below parameters as input:

Parameter	Information
message	To mark a message as unread, pass a non-null `BaseMessage` instance to the `markMessageAsUnread` function. All messages below that message in the conversation will contribute to the unread messages count. Example: When User B sends User A a total of 10 messages, and User A invokes the `markMessageAsUnread(baseMessage: BaseMessage, receiverType: CometChat.ReceiverType, onSuccess: (Conversation) -> Void, onError: (CometChatException?) -> ())` 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.
onSuccess	The callback listener that will be called on success.
onError	The callback listener that will be called on error.

You cannot mark your own messages as unread. This method only works for messages received from other users.

Swift (User)
Swift (Group)

CometChat.markMessageAsUnread(baseMessage: message, receiverType: .user) { conversation in
  print(conversation)
  print(conversation.unreadMessageCount)
} onError: { error in
  print(error?.errorDescription)
}

CometChat.markMessageAsUnread(baseMessage: message, receiverType: .group) { conversation in
  print(conversation)
  print(conversation.unreadMessageCount)
} onError: { error in
  print(error?.errorDescription)
}

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

onMessagesDelivered() - This event is triggered when a message is delivered to a user.
onMessagesRead() - This event is triggered when a message is read by a user.
onMessagesDeliveredToAll() - This event is triggered when a group message is delivered to all members of the group. This event is only for Group conversations.
onMessagesReadByAll() - This event is triggered when a group message is read by all members of the group. This event is only for Group conversations.

Swift
Objective C

func onMessagesRead(receipt: MessageReceipt) {
   print("onMessagesRead \(receipt.stringValue())")
}
    
func onMessagesDelivered(receipt: MessageReceipt) {
  print("onMessagesDelivered \(receipt.stringValue())")
}

func onMessagesDeliveredToAll(receipt: MessageReceipt) {
  print("onMessagesDeliveredToAll \(receipt.stringValue())")
}

func onMessagesReadByAll(receipt: MessageReceipt) {
  print("onMessagesReadByAll \(receipt.stringValue())")
}

-(void)onMessagesDeliveredWithReceipt:(MessageReceipt *)receipt
{
   NSLog(@"onMessagesDeliveredWithReceipt %@",receipt.stringValue)
}
-(void)onMessagesReadWithReceipt:(MessageReceipt *)receipt
{
   NSLog(@"onMessagesReadWithReceipt %@",receipt.stringValue)
}

-(void)onMessagesDeliveredToAll:(MessageReceipt *)receipt
{
   NSLog(@"onMessagesDeliveredToAll %@",receipt.stringValue)
}
-(void)onMessagesReadByAll:(MessageReceipt *)receipt
{
   NSLog(@"onMessagesReadByAll %@",receipt.stringValue)
}

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

Parameter	Information
messageId	The Id of the message prior to which all the messages for that particular conversation have been marked as read.
sender	User object containing the details of the user who has marked the message as read. System User for `deliveredToAll` & `readByAll` events.
receiverId	Id of the receiver whose conversation has been marked as read.
receiverType	type of the receiver (user/group)
receiptType	Type of the receipt (read/delivered)
deliveredAt	The timestamp of the time when the message was delivered. This will only be present if the receiptType is delivered.
readAt	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.

Swift
Objective C

var messageId = 10101;

CometChat.getMessageReceipts(messageId, onSuccess: { (receipt) in
            
  print("getMessageReceipt \(receipt)")                                           
}) { (error) in
  print(error?.errorDescription)
}

int messageId =10101;

[CometChat getMessageReceipts:messageId onSuccess:^(NSArray<MessageReceipt *> * _Nonnull receipt) {
        
        NSLog(@"getMessageReceipts %@",receipt);
    } onError:^(CometChatException * _Nullable error) {
        
        NSLog(@"CometChatException %@",error.errorDescription);
    }];

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

Sample Payloads

Request
Success Response
Success Response (With Receipts)
Error Response

{
  "messageId": 37787
}

{
  "receipts": []
}

{
  "receipts": [
    {
      "messageId": 37787,
      "sender": {
        "uid": "cometchat-uid-2",
        "name": "George Alan"
      },
      "receiverId": "cometchat-uid-1",
      "receiverType": 0,
      "receiptType": "delivered",
      "deliveredAt": 1771586985,
      "readAt": 0
    },
    {
      "messageId": 37787,
      "sender": {
        "uid": "cometchat-uid-2",
        "name": "George Alan"
      },
      "receiverId": "cometchat-uid-1",
      "receiverType": 0,
      "receiptType": "read",
      "deliveredAt": 1771586985,
      "readAt": 1771586990
    }
  ]
}

{
  "errorCode": "ERR_MESSAGE_NOT_FOUND",
  "errorMessage": "The message with the specified ID does not exist."
}

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.
markAsUnread method.

Success & Failure Responses

Mark as Delivered Success Response

When messages are successfully marked as delivered:

Swift

CometChat.markAsDelivered(messageId: messageId, receiverId: receiverId, receiverType: .user, messageSender: senderId, onSuccess: {
    // Success - no return value
    print("Messages marked as delivered successfully")
}, onError: { (error) in
    // Handle error
})

Mark as Read Success Response

When messages are successfully marked as read:

Swift

CometChat.markAsRead(messageId: messageId, receiverId: receiverId, receiverType: .user, messageSender: senderId, onSuccess: {
    // Success - no return value
    print("Messages marked as read successfully")
}, onError: { (error) in
    // Handle error
})

Mark Conversation as Read/Delivered Success Response

Swift

CometChat.markConversationAsRead(conversationWithId: uid, receiverType: .user, onSuccess: { (message) in
    // message: String - Success confirmation
    print("Response: \(message)")
}, onError: { (error) in
    print("Error: \(error.errorDescription)")
})

Mark as Unread Success Response

Swift

CometChat.markMessageAsUnread(baseMessage: message, receiverType: .user, onSuccess: { (conversation) in
    // conversation: Conversation - Updated conversation object
    print("Conversation: \(conversation)")
    print("Unread Count: \(conversation.unreadMessageCount)")
}, onError: { (error) in
    print("Error: \(error?.errorDescription ?? "")")
})

Get Message Receipts Success Response

Swift

CometChat.getMessageReceipts(messageId, onSuccess: { (receipts) in
    // receipts: [MessageReceipt] - Array of receipt objects
    for receipt in receipts {
        print("Message ID: \(receipt.messageId)")
        print("Sender: \(receipt.sender?.name ?? "")")
        print("Receiver ID: \(receipt.receiverId)")
        print("Receipt Type: \(receipt.receiptType)")  // .delivered or .read
        print("Delivered At: \(receipt.deliveredAt)")
        print("Read At: \(receipt.readAt)")
    }
}, onError: { (error) in
    print("Error: \(error?.errorDescription ?? "")")
})

Failure Response

Swift

CometChat.markAsRead(messageId: messageId, receiverId: receiverId, receiverType: .user, messageSender: senderId, onSuccess: {
    // Success
}, onError: { (error) in
    print("Error Code: \(error?.errorCode ?? "")")
    print("Error Description: \(error?.errorDescription ?? "")")
    
    // Handle specific errors
    switch error?.errorCode {
    case "ERR_MESSAGE_NOT_FOUND":
        // Message does not exist
        break
    case "ERR_UID_NOT_FOUND":
        // User does not exist
        break
    case "ERR_INVALID_MESSAGE_ID":
        // Invalid message ID provided
        break
    default:
        break
    }
})

MessageReceipt Object Properties

Property	Type	Description
`messageId`	`Int`	ID of the message
`sender`	`User?`	User who sent the receipt
`receiverId`	`String`	ID of the receiver
`receiverType`	`ReceiverType`	`.user` or `.group`
`receiptType`	`ReceiptType`	`.delivered` or `.read`
`deliveredAt`	`Double`	Unix timestamp when delivered
`readAt`	`Double`	Unix timestamp when read

Common Error Codes

Error Code	Description	Resolution
`ERR_MESSAGE_NOT_FOUND`	Message with specified ID does not exist	Verify the message ID
`ERR_UID_NOT_FOUND`	User with specified UID does not exist	Verify the user UID
`ERR_INVALID_MESSAGE_ID`	Invalid message ID provided	Provide a valid message ID
`ERR_CANNOT_MARK_OWN_MESSAGE`	Cannot mark own message as unread	Only received messages can be marked unread

​Mark Messages as Delivered

​Mark Conversation as Delivered

​Mark Messages as Read

​Mark Conversation as Read

​Mark Messages as Unread

​Receive Delivery & Read Receipts

​Real-time Events

​Missed Receipts

​Receipt History for a Single Message

​Success & Failure Responses

​Mark as Delivered Success Response

​Mark as Read Success Response

​Mark Conversation as Read/Delivered Success Response

​Mark as Unread Success Response

​Get Message Receipts Success Response

​Failure Response

​MessageReceipt Object Properties

​Common Error Codes

Mark Messages as Delivered

Mark Conversation as Delivered

Mark Messages as Read

Mark Conversation as Read

Mark Messages as Unread

Receive Delivery & Read Receipts

Real-time Events

Missed Receipts

Receipt History for a Single Message

Success & Failure Responses

Mark as Delivered Success Response

Mark as Read Success Response

Mark Conversation as Read/Delivered Success Response

Mark as Unread Success Response

Get Message Receipts Success Response

Failure Response

MessageReceipt Object Properties

Common Error Codes