> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete A Message
> Delete messages and handle real-time deletion events using the CometChat Flutter SDK.
| Field | Value |
| - | - |
| Key Classes | `BaseMessage`, `CometChatException` |
| Key Methods | `CometChat.deleteMessage()` |
| Listener Events | `onMessageDeleted` |
| Prerequisites | SDK initialized, user logged in |
```dart theme={null}
// Delete a message by ID
int messageId = 1234;
await CometChat.deleteMessage(messageId,
onSuccess: (BaseMessage message) {
debugPrint("Message deleted at: ${message.deletedAt}");
},
onError: (CometChatException e) {
debugPrint("Delete failed: ${e.message}");
},
);
// Listen for deleted messages
CometChat.addMessageListener("listener_id", MessageListener(
onMessageDeleted: (BaseMessage message) {
debugPrint("Message ${message.id} was deleted");
},
));
// Remove listener when done
CometChat.removeMessageListener("listener_id");
```
**Who can delete:** Message sender, Group admin, Group moderator
**Deleted fields:** `deletedAt` (timestamp), `deletedBy` (user who deleted)
This operation is irreversible. Deleted messages cannot be recovered.
While [deleting a message](/sdk/flutter/delete-message#delete-a-message) is straightforward, receiving events for deleted messages with CometChat has two parts:
1. Adding a listener to receive [real-time message deletes](/sdk/flutter/delete-message#real-time-message-delete-events) when your app is running.
2. Calling a method to retrieve [missed message delete events](/sdk/flutter/delete-message#missed-message-delete-events) when your app was not running.
**Available via:** SDK | [REST API](https://api-explorer.cometchat.com) | [UI Kits](/ui-kit/flutter/overview)
## Delete a Message
*In other words, as a sender, how do I delete a message?*
Use `deleteMessage()` with the message ID of the message to be deleted.
| Parameter | Type | Description |
| - | - | - |
| `messageId` | `int` | The ID of the message to delete. |
| `onSuccess` | `Function(BaseMessage)` | Callback triggered on success with the deleted message object. |
| `onError` | `Function(CometChatException)` | Callback triggered on error with exception details. |
```dart theme={null}
int messageId=1234;
await CometChat.deleteMessage(messageId,
onSuccess: (BaseMessage message){
debugPrint("Message deleted successfully at : $message");
}, onError: (CometChatException e){
debugPrint("Message deletion failed : ${e.message}");
}
);
```
**On Success** — A `BaseMessage` object with `deletedAt` and `deletedBy` fields set:
**BaseMessage Object:**
| Parameter | Type | Description | Sample Value |
| - | - | - | - |
| `id` | number | Unique message ID | `1234` |
| `metadata` | object | Custom metadata attached to the message | `{}` |
| `receiver` | object | Receiver user object | [See below ↓](#delete-message-receiver-object) |
| `editedBy` | string | UID of the user who edited the message | `null` |
| `conversationId` | string | Unique conversation identifier | `"cometchat-uid-1_user_cometchat-uid-2"` |
| `sentAt` | number | Epoch timestamp when the message was sent | `1745554729` |
| `receiverUid` | string | UID of the receiver | `"cometchat-uid-2"` |
| `type` | string | Type of the message | `"text"` |
| `readAt` | number | Epoch timestamp when the message was read | `0` |
| `deletedBy` | string | UID of the user who deleted the message | `"cometchat-uid-1"` |
| `deliveredAt` | number | Epoch timestamp when the message was delivered | `1745554750` |
| `deletedAt` | number | Epoch timestamp when the message was deleted | `1745554800` |
| `replyCount` | number | Number of replies to this message | `0` |
| `sender` | object | Sender user object | [See below ↓](#delete-message-sender-object) |
| `receiverType` | string | Type of the receiver | `"user"` |
| `editedAt` | number | Epoch timestamp when the message was edited | `0` |
| `parentMessageId` | number | ID of the parent message (for threads) | `0` |
| `readByMeAt` | number | Epoch timestamp when read by the current user | `0` |
| `category` | string | Message category | `"message"` |
| `deliveredToMeAt` | number | Epoch timestamp when delivered to the current user | `0` |
| `updatedAt` | number | Epoch timestamp when the message was last updated | `1745554800` |
| `unreadRepliesCount` | number | Count of unread replies | `0` |
| `quotedMessageId` | number | ID of the quoted message | `null` |
***
**`sender` Object:**
| Parameter | Type | Description | Sample Value |
| - | - | - | - |
| `uid` | string | Unique identifier of the sender | `"cometchat-uid-1"` |
| `name` | string | Display name of the sender | `"Andrew Joseph"` |
| `link` | string | Profile link | `null` |
| `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` |
| `metadata` | object | Custom metadata | `{}` |
| `status` | string | Online status | `"online"` |
| `role` | string | User role | `"default"` |
| `statusMessage` | string | Status message | `null` |
| `tags` | array | User tags | `[]` |
| `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
| `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
| `lastActiveAt` | number | Epoch timestamp of last activity | `1745554700` |
***
**`receiver` Object:**
| Parameter | Type | Description | Sample Value |
| - | - | - | - |
| `uid` | string | Unique identifier of the receiver | `"cometchat-uid-2"` |
| `name` | string | Display name of the receiver | `"George Alan"` |
| `link` | string | Profile link | `null` |
| `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"` |
| `metadata` | object | Custom metadata | `{}` |
| `status` | string | Online status | `"offline"` |
| `role` | string | User role | `"default"` |
| `statusMessage` | string | Status message | `null` |
| `tags` | array | User tags | `[]` |
| `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
| `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
| `lastActiveAt` | number | Epoch timestamp of last activity | `1745550000` |
| Parameter | Type | Description | Sample Value |
| - | - | - | - |
| `code` | string | Error code identifier | `"ERR_CHAT_API_FAILURE"` |
| `message` | string | Human-readable error message | `"The message could not be deleted."` |
| `details` | string | Additional technical details | `"Ensure the message ID is valid and you have permission to delete this message."` |
The deleted message object is returned with `deletedAt` (timestamp) and `deletedBy` (UID of deleter) fields set.
Relevant fields to access on the returned message:
| Field | Property | Return Type | Description |
| - | - | - | - |
| deletedAt | `deletedAt` | `int` | Timestamp when the message was deleted |
| deletedBy | `deletedBy` | `String` | UID of the user who deleted the message |
By default, CometChat allows certain roles to delete a message.
| User Role | Conversation Type | Deletion Capabilities |
| - | - | - |
| Message Sender | One-on-one Conversation | Messages they've sent |
| Message Sender | Group Conversation | Messages they've sent |
| Group Admin | Group Conversation | All messages in the group |
| Group Moderator | Group Conversation | All messages in the group |
## Real-time Message Delete Events
*In other words, as a recipient, how do I know when someone deletes a message when my app is running?*
Use `onMessageDeleted` in `MessageListener` to receive real-time delete events.
```dart theme={null}
class Class_Name with MessageListener {
//CometChat.addMessageListener("listenerId", this);
@override
void onMessageDeleted(BaseMessage message) {
// TODO implement onMessageDeleted
}
}
```
Always remove message 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.
```dart theme={null}
@override
void dispose() {
CometChat.removeMessageListener("listenerId");
super.dispose();
}
```
The `onMessageDeleted` callback receives a [`BaseMessage`](/sdk/reference/messages#basemessage) object with the `deletedAt` and `deletedBy` fields set.
Relevant fields to access on the returned message:
| Field | Property | Return Type | Description |
| - | - | - | - |
| deletedAt | `deletedAt` | `int` | Timestamp when the message was deleted |
| deletedBy | `deletedBy` | `String` | UID of the user who deleted the message |
## Missed Message Delete Events
*In other words, as a recipient, how do I know if someone deleted a message when my app was not running?*
When you retrieve the list of previous messages, for the messages that were deleted, the `deletedAt` and the `deletedBy` fields will be set. Also, for example, if the total number of messages for a conversation are 100, and the message with message ID 50 was deleted. Now the message with ID 50 will have the `deletedAt` and the `deletedBy` fields set whenever it is pulled from the history. Also, the 101st message will be an `Action` message informing you that the message with ID 50 has been deleted.
For the message deleted event, in the `Action` object received, the following fields can help you get the relevant information-
1. `action` - `deleted`
2. `actionOn` - Updated message object which was deleted.
3. `actionBy` - User object containing the details of the user who has deleted the message.
4. `actionFor` - User/group object having the details of the receiver to which the message was sent.
You must be the message sender or a group admin/moderator to delete a message.
***
## Next Steps
Modify sent messages before deletion
Send text, media, and custom messages
Handle incoming messages in real-time
Report inappropriate messages
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.