> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-angular-v5-docs-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Message Structure and Hierarchy
> Understand CometChat Flutter SDK message categories, types, class hierarchy, and text, media, custom, interactive, and action messages.
Message class hierarchy:
```
BaseMessage (extends AppEntity)
├── TextMessage → category: message, type: text
├── MediaMessage → category: message, type: image/video/audio/file
├── CustomMessage → category: custom, type: developer-defined
├── InteractiveMessage → category: interactive, type: form/card/scheduler/customInteractive
├── Action → category: action, type: groupMember/message
├── Call → category: call, type: audio/video
└── AIAssistantMessage → category: agentic, type: assistant
```
Message categories and types:
* **message** → `text`, `image`, `video`, `audio`, `file`
* **custom** → Developer-defined types (e.g., `location`, `poll`)
* **interactive** → `form`, `card`, `scheduler`, `customInteractive`
* **action** → `groupMember` (joined/left/kicked/banned), `message` (edited/deleted)
* **call** → `audio`, `video`
* **agentic** → `assistant`, `tool-result`, `tool-arguments`
```dart theme={null}
// Common BaseMessage Properties
message.id; // int - Unique message ID
message.sender; // User? - Message sender
message.receiverUid; // String - Receiver UID or GUID
message.receiverType; // String - "user" or "group"
message.category; // String - message/custom/action/interactive/call/agentic
message.type; // String - text/image/video/audio/file/custom
message.sentAt; // DateTime? - When message was sent
message.deliveredAt; // DateTime? - When message was delivered
message.readAt; // DateTime? - When message was read
message.metadata; // Map? - Custom data
// Type-specific Properties
textMessage.text; // String - Text content
mediaMessage.attachment; // Attachment? - File details
customMessage.customData; // Map? - Custom payload
interactiveMessage.interactiveData; // Map - Interactive element data
```
Every message in CometChat belongs to a category (`message`, `custom`, `interactive`, `action`, `call`) and has a specific type within that category. On the SDK side, all messages extend [`BaseMessage`](/sdk/flutter/key-concepts), with subclasses like `TextMessage`, `MediaMessage`, `CustomMessage`, `InteractiveMessage`, `Action`, and `Call`. Understanding this hierarchy helps you handle different message types correctly.
## Message Hierarchy
The below diagram helps you better understand the various message categories and types that a CometChat message can belong to.
The calling feature is not currently supported by the CometChat Flutter SDK.
## Categories Overview
| Category | Types | SDK Class | Description |
| ------------- | ------------------------------------------------ | ----------------------------- | ------------------------------------ |
| `message` | `text`, `image`, `video`, `audio`, `file` | `TextMessage`, `MediaMessage` | Standard user messages |
| `custom` | Developer-defined | `CustomMessage` | Custom data (location, polls, etc.) |
| `interactive` | `form`, `card`, `scheduler`, `customInteractive` | `InteractiveMessage` | Messages with actionable UI elements |
| `action` | `groupMember`, `message` | `Action` | System-generated events |
| `call` | `audio`, `video` | `Call` | Call-related messages |
## BaseMessage Properties
All message types extend `BaseMessage`, which provides these common properties:
| Property | Type | Description |
| -------------------- | ----------------------- | ----------------------------------------------------------------------- |
| `id` | `int` | Unique message identifier |
| `muid` | `String` | Message unique identifier (client-side) |
| `sender` | `User?` | The user who sent the message |
| `receiver` | `AppEntity?` | The receiver (User or Group) |
| `receiverUid` | `String` | UID of the receiver (user UID or group GUID) |
| `type` | `String` | Message type (e.g., `text`, `image`, `custom`) |
| `receiverType` | `String` | `"user"` or `"group"` |
| `category` | `String` | Message category (`message`, `custom`, `action`, `interactive`, `call`) |
| `sentAt` | `DateTime?` | Timestamp when the message was sent |
| `deliveredAt` | `DateTime?` | Timestamp when the message was delivered |
| `readAt` | `DateTime?` | Timestamp when the message was read |
| `metadata` | `Map?` | Custom key-value data attached to the message |
| `readByMeAt` | `DateTime?` | Timestamp when the current user read the message |
| `deliveredToMeAt` | `DateTime?` | Timestamp when the message was delivered to the current user |
| `deletedAt` | `DateTime?` | Timestamp when the message was deleted |
| `editedAt` | `DateTime?` | Timestamp when the message was last edited |
| `deletedBy` | `String?` | UID of the user who deleted the message |
| `editedBy` | `String?` | UID of the user who edited the message |
| `updatedAt` | `DateTime?` | Timestamp of the last update |
| `conversationId` | `String?` | ID of the conversation this message belongs to |
| `parentMessageId` | `int` | ID of the parent message (for threaded messages) |
| `replyCount` | `int` | Number of replies to this message |
| `unreadRepliesCount` | `int` | Number of unread replies |
| `mentionedUsers` | `List` | Users mentioned in this message |
| `hasMentionedMe` | `bool?` | Whether the current user is mentioned |
| `reactions` | `List` | Reactions on this message |
| `quotedMessage` | `BaseMessage?` | The message being quoted/replied to |
| `quotedMessageId` | `int?` | ID of the quoted message |
## Message
A message belonging to the category `message` can be classified into either 1 of the below types:
1. text - A plain text message
2. image- An image message
3. video- A video message
4. audio- An audio message
5. file- A file message
### TextMessage Properties
| Property | Type | Description |
| ------------------ | ----------------------- | -------------------------------- |
| `text` | `String` | The text content of the message |
| `tags` | `List?` | Tags associated with the message |
| `moderationStatus` | `ModerationStatusEnum?` | Content moderation status |
*Inherits all [BaseMessage](#basemessage-properties) properties.*
### MediaMessage Properties
| Property | Type | Description |
| ------------------ | ----------------------- | -------------------------------- |
| `caption` | `String?` | Caption for the media file |
| `attachment` | `Attachment?` | Primary file attachment details |
| `file` | `String?` | Local file path |
| `files` | `List?` | Multiple local file paths |
| `attachments` | `List?` | Multiple file attachments |
| `tags` | `List?` | Tags associated with the message |
| `moderationStatus` | `ModerationStatusEnum?` | Content moderation status |
*Inherits all [BaseMessage](#basemessage-properties) properties.*
### Attachment Properties
| Property | Type | Description |
| --------------- | -------- | ----------------------------------- |
| `fileUrl` | `String` | URL of the uploaded file |
| `fileName` | `String` | Name of the file |
| `fileExtension` | `String` | File extension (e.g., `jpg`, `mp4`) |
| `fileMimeType` | `String` | MIME type (e.g., `image/jpeg`) |
| `fileSize` | `int?` | File size in bytes |
## Custom
In the case of messages that belong to the `custom` category, there are no predefined types. Custom messages can be used by developers to send messages that do not fit in the default category and types provided by CometChat. For messages with the category `custom`, the developers can set their own type to uniquely identify the custom message. A very good example of a custom message would be the sharing of location co-ordinates. In this case, the developer can decide to use the custom message with type set to `location`.
### CustomMessage Properties
| Property | Type | Description |
| -------------------- | ----------------------- | --------------------------------------- |
| `subType` | `String?` | Sub-type for further classification |
| `customData` | `Map?` | Custom key-value payload |
| `tags` | `List?` | Tags associated with the message |
| `conversationText` | `String?` | Text shown in conversation list |
| `updateConversation` | `bool?` | Whether to update the conversation list |
| `sendNotification` | `bool?` | Whether to send a push notification |
*Inherits all [BaseMessage](#basemessage-properties) properties.*
## Interactive
An `InteractiveMessage` is a specialized object that encapsulates an interactive unit within a chat message, such as an embedded form that users can fill out directly within the chat interface. Messages belonging to the `interactive` category can further be classified into one of the below types:
1. form- for interactive form
2. card- for interactive card
3. scheduler- for scheduler message
4. customInteractive- for custom interaction messages
To know about Interactive messages please [click here](/sdk/flutter/interactive-messages).
### InteractiveMessage Properties
| Property | Type | Description |
| ------------------------ | ---------------------- | ----------------------------------------------------------------------- |
| `interactiveData` | `Map` | Data defining the interactive element (form fields, card content, etc.) |
| `interactions` | `List?` | List of user interactions with this message |
| `interactionGoal` | `InteractionGoal?` | Goal criteria for the interactive element |
| `tags` | `List?` | Tags associated with the message |
| `allowSenderInteraction` | `bool` | Whether the sender can interact with the element |
*Inherits all [BaseMessage](#basemessage-properties) properties.*
## Action
Action messages are system-generated messages. Messages belonging to the `action` category can further be classified into one of the below types:
1. groupMember - action performed on a group member.
2. message - action performed on a message.
### Action Properties
| Property | Type | Description |
| ----------- | ------------ | --------------------------------------------------------- |
| `message` | `String?` | Human-readable action description |
| `rawData` | `String?` | Raw action data |
| `action` | `String?` | The action performed (e.g., `joined`, `kicked`, `edited`) |
| `oldScope` | `String?` | Previous member scope (for scope changes) |
| `newScope` | `String?` | New member scope (for scope changes) |
| `actionBy` | `AppEntity?` | Entity that performed the action |
| `actionFor` | `AppEntity?` | Entity the action was performed for |
| `actionOn` | `AppEntity?` | Entity the action was performed on |
*Inherits all [BaseMessage](#basemessage-properties) properties.*
Action messages hold another property called `action` which actually determine the action that has been performed For the type `groupMember` the action can be either one of the below:
1. joined - when a group member joins a group
2. left - when a group member leaves a group
3. kicked - when a group member is kicked from the group
4. banned - when a group member is banned from the group
5. unbanned - when a group member is unbanned from the group
6. added - when a user is added to the group
7. scopeChanged - When the scope of a group member is changed.
For the type `message`, the action can be either one of the below:
1. edited - when a message is edited.
2. deleted - when a message is deleted.
## Call
Messages with the category call are Calling related messages. These can belong to either one of the 2 types
1. audio
2. video
### Call Properties
| Property | Type | Description |
| --------------- | ------------ | --------------------------------- |
| `sessionId` | `String?` | Unique call session identifier |
| `callStatus` | `String?` | Current status of the call |
| `action` | `String?` | Call action type |
| `rawData` | `String?` | Raw call data |
| `initiatedAt` | `DateTime?` | When the call was initiated |
| `joinedAt` | `DateTime?` | When the receiver joined the call |
| `callInitiator` | `AppEntity?` | The user who initiated the call |
| `callReceiver` | `AppEntity?` | The user/group receiving the call |
*Inherits all [BaseMessage](#basemessage-properties) properties.*
The call messages have a property called status that helps you figure out the status of the call. The status can be either one of the below values:
| Status | Description |
| ------------ | ---------------------------- |
| `initiated` | Call started to a user/group |
| `ongoing` | Receiver accepted the call |
| `cancelled` | Initiator canceled the call |
| `rejected` | Receiver rejected the call |
| `unanswered` | Call was not answered |
| `busy` | Receiver was on another call |
| `ended` | Call completed successfully |
***
## Next Steps
Learn how to send text, media, and custom messages
Handle incoming messages with real-time listeners
Create forms, cards, and interactive elements
Modify or remove sent messages