Skip to main content
Using CometChat, you can work with four types of messages. The first three you can send directly:
  1. A Text Message, the most common and standard message type.
  2. A Media Message, for sending photos, videos and files.
  3. A Custom Message, for sending completely custom data using Map structures.
The fourth is receive-only:
  1. A Card Message, a structured, interactive card message created server-side via the REST API and delivered to clients.
You can also send metadata along with a text or media message. Think, for example, if you’d want to share the user’s location with every message, you can use the metadata field.

​
Text Message

In other words, as a sender, how do I send a text message? To send a text message to a single user or group, you need to use the sendMessage() method and pass a TextMessage object to it.

​
Add Metadata

To send custom data along with a text message, you can use the setMetadata method and pass a Map to it. 
Map<String,String> metadata = {};
metadata["lattitude"] =  "50.6192171633316" ;
metadata["longitude"]  = "-72.68182268750002" ;
textMessage.metadata = metadata;

​
Add Tags

To add a tag to a message you can assign value in .tags variable of the TextMessage Class. tags accepts a list of tags. 
List<String> tags = [];
tags.add("pinned");
textMessage.tags = tags;
Once the text message object is ready, you need to use the sendMessage() method to send the text message to the recipient. 
String receiverID = "cometchat-uid-1";
String messageText = "messageText";
String receiverType = CometChatConversationType.user;
String type = CometChatMessageType.text;

TextMessage textMessage = TextMessage(text: messageText,
                                    receiverUid: receiverID,
          													receiverType: receiverType,
           													type: type);
CometChat.sendMessage(textMessage, 
  onSuccess: (TextMessage message) {
	debugPrint("Message sent successfully:  $message");
  }, onError: (CometChatException e) {
	debugPrint("Message sending failed with exception:  ${e.message}");
  }
);
The TextMessage class constructor takes the following parameters:
ParameterDescription
receiverIDUID of the user or GUID of the group receiving the messageRequired
messageTextThe text messageRequired
receiverTypeThe type of the receiver- CometChatReceiverType.user (user) or CometChatReceiverType.group (group)Required
typeThe type of the message that needs to be sent which in this case can be: CometChatMessageType.text__(text)
When a text message is sent successfully, the response will include a TextMessage object which includes all information related to the sent message.

​
Set Quoted Message

To set a quoted message for a message, use the setQuotedMessageId and setQuotedMessage method of the TextMessage class. This method accepts the ID of the message to be quoted. 
textMessage.quotedMessageId = 0
textMessage.quotedMessage =  // Pass base message object here that you want to quote.
Once the text message object is ready, you need to use the sendMessage() method to send the text message to the recipient. 
String receiverID = "UID";
  String messageText = "Hello CometChat!";
  String receiverType = CometChatReceiverType.user;

  TextMessage textMessage =
      TextMessage(receiverID, messageText, receiverType);

  CometChat.sendMessage(
    textMessage,
    onSuccess: (TextMessage message) {
      print("Message sent successfully: ${message.toString()}");
    },
    onError: (CometChatException e) {
      print("Message sending failed with exception: ${e.message}");
    },
  );
The TextMessage class constructor takes the following parameters:
ParameterDescription
receiverIDUID of the user or GUID of the group receiving the messageRequired
messageTextThe text messageRequired
receiverTypeThe type of the receiver- CometChatConstants.RECEIVER_TYPE_USER (user) or CometChatConstants.RECEIVER_TYPE_GROUP (group)Required
When a text message is sent successfully, the response will include a TextMessage object which includes all information related to the sent message.

​
Media Message

In other words, as a sender, how do I send a media message like photos, videos & files? To send a media message to any user or group, you need to use the sendMediaMessage() method and pass a MediaMessage object to it.

​
Add Metadata

To send custom data along with a media message, you can use the setMetadata method and pass a Map to it. 
Map<String,dynamic> metadata = {};
metadata["lattitude"] =  "50.6192171633316" ;
metadata["longitude"]  = "-72.68182268750002" ;
mediaMessage.metadata = metadata;

​
Add Caption(Text along with Media Message)

mediaMessage.caption = "Message Caption";

​
Add Tags

To add a tag to a message you can use the setTags() method of the MediaMessage Class. The setTags() method accepts a list of tags. 
List<String> tags = [];
tags.add("pinned");
mediaMessage.tags = tags;
There are 2 ways you can send Media Messages using the CometChat SDK:
  1. By providing the File : You can directly share the file object while creating an object of the MediaMessage class. When the media message is sent using the sendMediaMessage() method, this file is then uploaded to CometChat servers and the URL of the file is sent in the success response of the sendMediaMessage() function.
String receiverID;
String messageType = CometChatMessageType.image;
String receiverType = CometChatConversationType.user ;
String filePath = "storage/emulated/0/Download/46.jpg";
MediaMessage mediaMessage = MediaMessage(
receiverType: receiverType,
type: messageType,
receiverUid: receiverID,
file: filePath);

await CometChat.sendMediaMessage(mediaMessage, 
  onSuccess: (MediaMessage message) {
  	debugPrint("Media message sent successfully:${mediaMessage.metadata}");
  }, onError: (e) {
  	debugPrint("Media message sending failed with exception: ${e.message}");
  }
);
The MediaMessage class constructor takes the following parameters:
ParameterDescription
receiverIdThe UID or GUID of the recipientRequired
fileThe file object to be sentRequired
messageTypeThe type of the message that needs to be sent which, in this case, can be:
1. CometChatMessageType.image (image)
2. CometChatMessageType.video (video)
3. CometChatMessageType.audio (audio)
4. CometChatMessageType.file (file)		Required
receiverTypeThe type of the receiver to whom the message is to be sent, i.e., CometChatReceiverType.user (user) or CometChatReceiverType.group (group)Required
  1. By providing the URL of the File: The second way to send media messages using the CometChat SDK is to provide the SDK with the URL of any file that is hosted on your servers or any cloud storage. To achieve this you will have to make use of the Attachment class that is available in the MediaMessage class. For more information, you can refer to the below code snippet:
MediaMessage mediaMessage = MediaMessage(
                          receiverType: receiverType,
                          type: messageType,
                          receiverUid: receiverID,
                          file: null);

String fileUrl  = "https://pngimg.com/uploads/mario/mario_PNG125.png";
String fileName   = "test";
String fileExtension = "png";
String fileMimeType = "image/png";

Attachment attach =  Attachment(fileUrl,fileName,fileExtension,fileMimeType,null);
mediaMessage.attachment= attach;

await CometChat.sendMediaMessage(mediaMessage,
  onSuccess: (MediaMessage message) {
  	debugPrint( "Media message sent successfully: ${mediaMessage}");                            
  }, onError: (CometChatException e) {
  	debugPrint("Media message sending failed with exception: ${e.message}");
  }
);
When a media message is sent successfully, the response will include a MediaMessage object which includes all information related to the sent message. If you wish to send a caption or some text along with the Media Message, you can use the caption field provided by the MediaMessage class. To get and set the caption you can use the .caption variable . As with text messages, the metadata field can be used with media messages as well. Any additional information can be passed along with the media message as a Map.

​
Send Multiple Media Files

You can send multiple media files (images, videos, audio, or documents) in a single message. This enables richer and more efficient conversations. 
String receiverID = "cometchat-uid-1";
String receiverType = CometChatConversationType.user;
String messageType = CometChatMessageType.image;

// Create a list of file paths
List<String> filePaths = [
  "storage/emulated/0/Download/image1.jpg",
  "storage/emulated/0/Download/image2.jpg",
  "storage/emulated/0/Download/image3.jpg",
];

MediaMessage mediaMessage = MediaMessage(
  receiverType: receiverType,
  type: messageType,
  receiverUid: receiverID,
  files: filePaths,  // Use 'files' for multiple files
);

await CometChat.sendMediaMessage(mediaMessage, 
  onSuccess: (MediaMessage message) {
    debugPrint("Multiple media files sent successfully");
    // Access the list of attachments
    List<Attachment>? attachments = message.attachments;
    for (var attachment in attachments ?? []) {
      debugPrint("Attachment URL: ${attachment.fileUrl}");
    }
  }, 
  onError: (CometChatException e) {
    debugPrint("Media message sending failed: ${e.message}");
  }
);

​
File Size and Count Validation

The SDK automatically validates file size and count when sending media messages. You can configure these limits through Settings in the CometChat Dashboard.
ValidationDescription
File SizeMaximum size per file (configurable in Dashboard)
File CountMaximum number of files per message (configurable in Dashboard)
If validation fails, the onError callback will be triggered with details about the validation error. 
await CometChat.sendMediaMessage(mediaMessage, 
  onSuccess: (MediaMessage message) {
    debugPrint("Media message sent successfully");
  }, 
  onError: (CometChatException e) {
    // Handle validation errors
    if (e.code == "ERR_FILE_SIZE_EXCEEDED") {
      debugPrint("File size exceeds the allowed limit");
    } else if (e.code == "ERR_FILE_COUNT_EXCEEDED") {
      debugPrint("Too many files in a single message");
    } else {
      debugPrint("Error: ${e.message}");
    }
  }
);

​
Custom Message

In other words, as a sender, how do I send a custom message like location co-ordinates? CometChat allows you to send custom messages which are neither text nor media messages. In order to send a custom message, you need to use the sendCustomMessage() method. The sendCustomMessage() methods takes an object of the CustomMessage which can be obtained using the below constructor. 
CustomMessage customMessage = CustomMessage( receiverUid: UID,
    type: type,
    customData: customData,
    receiverType: receiverType,
    subType: subType,
  );
The above constructor, helps you create a custom message with the message type set to whatever is passed to the constructor and the category set to custom. The parameters involved are:
  1. receiverUid - Unique id of the user or group to which the message is to be sent.
  2. receiverType - Type of the receiver i.e user or group
  3. customType - custom message type that you need to set
  4. customData - The data to be passed as the message in the form of a Map.
You can also use the subType field of the CustomMessage class to set a specific type for the custom message. This can be achieved using the subtype field.

​
Add Tags

To add a tag to a message you can assign value in .tags variable of the CustomMessage Class. tags accepts a list of tags. 
List<String> tags = [];
tags.add("pinned");
textMessage.tags = tags;
Once the object of CustomMessage class is ready you can send the custom message using the sendCustomMessage() method. 
String UID = "UID";
String subType = "LOCATION";
String receiverType = CometChatConversationType.user;
String type = CometChatMessageType.custom;

Map<String, String> customData = {};
customData["latitude"] = "19.0760";
customData["longitude"] = "72.8777";

CustomMessage customMessage = CustomMessage(
  receiverUid: UID,
  type: type,
  customData: customData,
  receiverType: receiverType,
  subType: subType,
);

CometChat.sendCustomMessage(customMessage, onSuccess: (CustomMessage message) {
  debugPrint("Custom Message Sent Successfully : $message");
}, onError: (CometChatException e) {
  debugPrint("Custom message sending failed with exception: ${e.message}");
});
The above sample explains how custom messages can be used to share the location with a user. Similarly, you can send custom messages to groups. On success, you will receive an object of CustomMessage class.

​
Update Conversation

How can I decide whether the custom message should update the last message of a conversation? By default, a custom message will update the last message of a conversation. If you wish to not update the last message of the conversation when a custom message is sent, please use updateConversation (boolean value) method of the Custom Message. 
String UID = "UID";
String subType = "LOCATION";
String receiverType = CometChatConversationType.user;
String type = CometChatMessageType.custom;

Map<String, String> customData = {};
customData["latitude"] = "19.0760";
customData["longitude"] = "72.8777";

CustomMessage customMessage = CustomMessage(
  receiverUid: UID,
  type: type,
  customData: customData,
  receiverType: receiverType,
  subType: subType,
);
customMessage.updateConversation = false;

CometChat.sendCustomMessage(customMessage, onSuccess: (CustomMessage message) {
  debugPrint("Custom Message Sent Successfully : $message");
}, onError: (CometChatException e) {
  debugPrint("Custom message sending failed with exception: ${e.message}");
});

​
Custom Notification Body

How can i customise the notification body of custom message? To add a custom notification body for Push, Email & SMS notification of a custom message you can use the conversationText method of Custom Message class. 
String UID = "UID";
String subType = "LOCATION";
String receiverType = CometChatConversationType.user;
String type = CometChatMessageType.custom;

Map<String, String> customData = {};
customData["latitude"] = "19.0760";
customData["longitude"] = "72.8777";

CustomMessage customMessage = CustomMessage(
  receiverUid: UID,
  type: type,
  customData: customData,
  receiverType: receiverType,
  subType: subType,
);
customMessage.conversationText = "Custom Notification Body";

CometChat.sendCustomMessage(customMessage, onSuccess: (CustomMessage message) {
  debugPrint("Custom Message Sent Successfully : $message");
}, onError: (CometChatException e) {
  debugPrint("Custom message sending failed with exception: ${e.message}");
});

​
Card Message

In other words, as a sender, how do I send a card message? A CardMessage is a structured, interactive message rendered as a card bubble. It belongs to the card category and carries a block of card schema JSON that the CometChat Cards library draws.
Card Messages cannot be sent through the SDK. The CardMessage class is receive-only — it has no public constructor and the SDK exposes no sendCardMessage() method. Card Messages are created server-side via the Platform REST API or the Dashboard Bubble Builder, and delivered to clients like any other message.To create and send a Card Message, use the REST API. See the Send Message REST API reference for the message creation flow.
On the receiving end, the CardMessage object gives you access to the card payload and its related fields. 
final card = cardMessage.getCard();                 // raw card schema/payload (Map<String, dynamic>?)
final text = cardMessage.getText();                 // optional text shown alongside the card
final fallbackText = cardMessage.getFallbackText(); // shown when the card cannot be rendered
final tags = cardMessage.getTags();                 // tags associated with the message
The CardMessage class provides the following methods:
MethodReturnsDescription
getCard()Map<String, dynamic>?The raw card schema/payload passed to the Cards renderer.
getText()String?Optional text shown alongside the card.
getFallbackText()String?Text displayed when the card payload cannot be rendered.
getTags()List<String>?Tags associated with the message.
CardMessage extends BaseMessage, so it also exposes the standard message fields (id, sender, receiverUid, sentAt, category = card, etc.). To handle incoming Card Messages on the client, implement onCardMessageReceived on your MessageListener.

​
Render a Card Message

A CardMessage carries raw card-schema JSON in getCard(). To draw it natively, use the CometChat Cards renderer package (cometchat_cards) — the same renderer the UI Kit’s card bubble wraps. It is a pure renderer: you hand it the card JSON and an action callback, and you own all action behavior.

​
Add the Cards dependency

Add the cards package to your pubspec.yaml: 
dependencies:
  cometchat_cards: ^1.0.0

​
Render the card

Pass the card JSON (jsonEncode(cardMessage.getCard())) to the renderer and handle actions through the callback. 
import 'package:cometchat_cards/cometchat_cards.dart';
import 'dart:convert';

Widget buildCardMessage(CardMessage cardMessage) {
  return CometChatCardView(
    cardJson: jsonEncode(cardMessage.getCard()),
    themeMode: CometChatCardThemeMode.auto, // follows system light/dark
    onAction: (CometChatCardActionEvent event) {
      // event.action    -> one of the tagged action types
      // event.elementId -> id of the tapped button/link
      if (event.action is CometChatCardOpenUrlAction) {
        // Open URL in browser
      } else if (event.action is CometChatCardChatWithUserAction) {
        // Navigate to chat
      } else if (event.action is CometChatCardCopyToClipboardAction) {
        // Copy to clipboard
      } else {
        // Handle the remaining action types
      }
    },
  );
}
The Cards library is a pure renderer — it never executes actions, it only emits them through the callback. You own all behavior (opening URLs, navigating to chats, API calls, etc.). See Campaigns → Supported Card Actions for the full list of action types.When rendering directly, fallback is your responsibility: if the card JSON is empty or invalid, fall back to cardMessage.getFallbackText() (then getText()).