Send Messages - CometChat Docs

AI Integration Quick Reference

Field	Value
Key Classes	`TextMessage`, `MediaMessage`, `CustomMessage`
Key Methods	`CometChat.sendMessage()`, `CometChat.sendMediaMessage()`, `CometChat.sendCustomMessage()`
Receiver Types	`CometChatReceiverType.user`, `CometChatReceiverType.group`
Message Types	`CometChatMessageType.text`, `CometChatMessageType.image`, `CometChatMessageType.video`, `CometChatMessageType.audio`, `CometChatMessageType.file`, `CometChatMessageType.custom`
Prerequisites	SDK initialized, user logged in

// Send text message to user
TextMessage textMessage = TextMessage(
  text: "Hello!",
  receiverUid: "UID",
  receiverType: CometChatReceiverType.user,
  type: CometChatMessageType.text,
);
CometChat.sendMessage(textMessage, onSuccess: (msg) {}, onError: (e) {});

// Send text message to group
TextMessage groupMessage = TextMessage(
  text: "Hello group!",
  receiverUid: "GUID",
  receiverType: CometChatReceiverType.group,
  type: CometChatMessageType.text,
);
CometChat.sendMessage(groupMessage, onSuccess: (msg) {}, onError: (e) {});

// Send media message (image)
MediaMessage mediaMessage = MediaMessage(
  receiverUid: "UID",
  receiverType: CometChatReceiverType.user,
  type: CometChatMessageType.image,
  file: "path/to/image.jpg",
);
CometChat.sendMediaMessage(mediaMessage, onSuccess: (msg) {}, onError: (e) {});

// Send custom message
CustomMessage customMessage = CustomMessage(
  receiverUid: "UID",
  receiverType: CometChatReceiverType.user,
  type: "location",
  customData: {"latitude": "50.6192", "longitude": "-72.6818"},
);
CometChat.sendCustomMessage(customMessage, onSuccess: (msg) {}, onError: (e) {});

CometChat supports three types of messages:

Type	Method	Use Case
Text	`CometChat.sendMessage()`	Plain text messages
Media	`CometChat.sendMediaMessage()`	Images, videos, audio, files
Custom	`CometChat.sendCustomMessage()`	Location, polls, or any structured data

You can also send Interactive Messages for forms, cards, and custom UI elements.

Available via: SDK | REST API | UI Kits

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.

Dart

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.

Dart

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.

Dart (User)
Dart (group)

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}");
  }
);

String receiverID = "cometchat-guid-1";
String messageText = "messageText";
String receiverType = CometChatConversationType.group;
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:

Parameter	Description
`receiverID`	`UID` of the user or `GUID` of the group receiving the message	Required
`messageText`	The text message	Required
`receiverType`	The type of the receiver- `CometChatReceiverType.user` (user) or `CometChatReceiverType.group` (group)	Required
type	The 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.

Response

On Success — A TextMessage object containing all details of the sent message:TextMessage Object:

Parameter	Type	Description	Sample Value
`id`	number	Unique message ID	`401`
`metadata`	object	Custom metadata attached to the message	`{}`
`receiver`	object	Receiver user object	See below ↓
`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	`null`
`deliveredAt`	number	Epoch timestamp when the message was delivered	`0`
`deletedAt`	number	Epoch timestamp when the message was deleted	`0`
`replyCount`	number	Number of replies to this message	`0`
`sender`	object	Sender user object	See below ↓
`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)	`-1`
`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	`1745554729`
`text`	string	The text content of the message	`"messageText"`
`tags`	array	List of tags associated with the message	`[]`
`unreadRepliesCount`	number	Count of unread replies	`0`
`mentionedUsers`	array	List of mentioned users	`[]`
`hasMentionedMe`	boolean	Whether the current user is mentioned	`false`
`reactions`	array	List of reactions on the message	`[]`
`moderationStatus`	string	Moderation status of the message	`null`
`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`

Error

Parameter	Type	Description	Sample Value
`code`	string	Error code identifier	`"ERR_EMPTY_MESSAGE_TEXT"`
`message`	string	Human-readable error message	`"The text message body is empty."`
`details`	string	Additional technical details	`"Please provide a non-empty text for the 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.

Dart

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.

Dart (User)
Dart (Group)

String receiverID = "UID";
String messageText = "Hello CometChat!";
String receiverType = CometChatReceiverType.user;
String type = CometChatMessageType.text;

TextMessage textMessage = TextMessage(
  text: messageText,
  receiverUid: receiverID,
  receiverType: receiverType,
  type: type,
);
textMessage.quotedMessageId = 10;

CometChat.sendMessage(textMessage,
  onSuccess: (TextMessage message) {
    debugPrint("Message sent successfully: ${message.toString()}");
  },
  onError: (CometChatException e) {
    debugPrint("Message sending failed with exception: ${e.message}");
  },
);

String receiverID = "GUID";
String messageText = "Hello CometChat!";
String receiverType = CometChatReceiverType.group;
String type = CometChatMessageType.text;

TextMessage textMessage = TextMessage(
  text: messageText,
  receiverUid: receiverID,
  receiverType: receiverType,
  type: type,
);
textMessage.quotedMessageId = 10;

CometChat.sendMessage(textMessage,
  onSuccess: (TextMessage message) {
    debugPrint("Message sent successfully: ${message.toString()}");
  },
  onError: (CometChatException e) {
    debugPrint("Message sending failed with exception: ${e.message}");
  },
);

The TextMessage class constructor takes the following parameters:

Parameter	Description
`receiverID`	`UID` of the user or `GUID` of the group receiving the message	Required
`messageText`	The text message	Required
`receiverType`	The type of the receiver- `CometChatReceiverType.user` (user) or `CometChatReceiverType.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.

Response

On Success — A TextMessage object containing all details of the sent quoted message:TextMessage Object:

Parameter	Type	Description	Sample Value
`id`	number	Unique message ID	`402`
`metadata`	object	Custom metadata attached to the message	`{}`
`receiver`	object	Receiver user object	See below ↓
`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	`1745554800`
`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	`null`
`deliveredAt`	number	Epoch timestamp when the message was delivered	`0`
`deletedAt`	number	Epoch timestamp when the message was deleted	`0`
`replyCount`	number	Number of replies to this message	`0`
`sender`	object	Sender user object	See below ↓
`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)	`-1`
`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`
`text`	string	The text content of the message	`"Hello CometChat!"`
`tags`	array	List of tags associated with the message	`[]`
`unreadRepliesCount`	number	Count of unread replies	`0`
`mentionedUsers`	array	List of mentioned users	`[]`
`hasMentionedMe`	boolean	Whether the current user is mentioned	`false`
`reactions`	array	List of reactions on the message	`[]`
`moderationStatus`	string	Moderation status of the message	`null`
`quotedMessageId`	number	ID of the quoted message	`401`

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`

Error

Parameter	Type	Description	Sample Value
`code`	string	Error code identifier	`"ERR_EMPTY_MESSAGE_TEXT"`
`message`	string	Human-readable error message	`"The text message body is empty."`
`details`	string	Additional technical details	`"Please provide a non-empty text for the 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.

Dart

Map<String,dynamic> metadata = {};
metadata["lattitude"] =  "50.6192171633316" ;
metadata["longitude"]  = "-72.68182268750002" ;
mediaMessage.metadata = metadata;

Add Caption(Text along with Media Message)

Dart

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.

Dart

List<String> tags = [];
tags.add("pinned");
mediaMessage.tags = tags;

Set Quoted Message

To quote a message in a media message, use the quotedMessageId property of the MediaMessage class.

Dart

mediaMessage.quotedMessageId = 10;

There are 2 ways you can send Media Messages using the CometChat SDK:

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.

Dart (User)
Dart (Group)

String receiverID = "cometchat-uid-1";
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}");
  }
); 

String receiverID = "cometchat-guid-1";
String messageType = CometChatMessageType.image;
String receiverType = CometChatConversationType.group;
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:

Parameter	Description
receiverId	The UID or GUID of the recipient	Required
file	The file object to be sent	Required
messageType	The 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
receiverType	The type of the receiver to whom the message is to be sent, i.e., `CometChatReceiverType.user` (user) or `CometChatReceiverType.group` (group)	Required

Response

On Success — A MediaMessage object containing all details of the sent media message:MediaMessage Object:

Parameter	Type	Description	Sample Value
`id`	number	Unique message ID	`403`
`metadata`	object	Custom metadata attached to the message	`{}`
`receiver`	object	Receiver user object	See below ↓
`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	`1745554900`
`receiverUid`	string	UID of the receiver	`"cometchat-uid-2"`
`type`	string	Type of the message	`"image"`
`readAt`	number	Epoch timestamp when the message was read	`0`
`deletedBy`	string	UID of the user who deleted the message	`null`
`deliveredAt`	number	Epoch timestamp when the message was delivered	`0`
`deletedAt`	number	Epoch timestamp when the message was deleted	`0`
`replyCount`	number	Number of replies to this message	`0`
`sender`	object	Sender user object	See below ↓
`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	`1745554900`
`tags`	array	List of tags associated with the message	`[]`
`unreadRepliesCount`	number	Count of unread replies	`0`
`mentionedUsers`	array	List of mentioned users	`[]`
`hasMentionedMe`	boolean	Whether the current user is mentioned	`false`
`reactions`	array	List of reactions on the message	`[]`
`caption`	string	Caption text for the media message	`null`
`attachment`	object	File attachment details	See below ↓
`file`	string	Local file path	`"storage/emulated/0/Download/46.jpg"`
`files`	array	List of additional file paths	`null`
`attachments`	array	List of additional attachments	`null`
`moderationStatus`	string	Moderation status of the message	`null`
`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`

attachment Object:

Parameter	Type	Description	Sample Value
`fileUrl`	string	URL of the uploaded file	`"https://data-us.cometchat.io/assets/images/46.jpg"`
`fileName`	string	Name of the file	`"46.jpg"`
`fileExtension`	string	File extension	`"jpg"`
`fileMimeType`	string	MIME type of the file	`"image/jpeg"`
`fileSize`	number	File size in bytes	`24576`

Error

Parameter	Type	Description	Sample Value
`code`	string	Error code identifier	`"ERR_FILE_TOO_LARGE"`
`message`	string	Human-readable error message	`"The file size exceeds the allowed limit."`
`details`	string	Additional technical details	`"Maximum allowed file size is 25 MB."`

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:

Dart (User)
Dart (Group)

String receiverID = "cometchat-uid-1";
String messageType = CometChatMessageType.image;
String receiverType = CometChatConversationType.user;

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}");
  }
);   

String receiverID = "cometchat-guid-1";
String messageType = CometChatMessageType.image;
String receiverType = CometChatConversationType.group;

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.

Response

On Success — A MediaMessage object containing all details of the sent media message (via URL):MediaMessage Object:

Parameter	Type	Description	Sample Value
`id`	number	Unique message ID	`404`
`metadata`	object	Custom metadata attached to the message	`{}`
`receiver`	object	Receiver user object	See below ↓
`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	`1745555000`
`receiverUid`	string	UID of the receiver	`"cometchat-uid-2"`
`type`	string	Type of the message	`"image"`
`readAt`	number	Epoch timestamp when the message was read	`0`
`deletedBy`	string	UID of the user who deleted the message	`null`
`deliveredAt`	number	Epoch timestamp when the message was delivered	`0`
`deletedAt`	number	Epoch timestamp when the message was deleted	`0`
`replyCount`	number	Number of replies to this message	`0`
`sender`	object	Sender user object	See below ↓
`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	`1745555000`
`tags`	array	List of tags associated with the message	`[]`
`unreadRepliesCount`	number	Count of unread replies	`0`
`mentionedUsers`	array	List of mentioned users	`[]`
`hasMentionedMe`	boolean	Whether the current user is mentioned	`false`
`reactions`	array	List of reactions on the message	`[]`
`caption`	string	Caption text for the media message	`null`
`attachment`	object	File attachment details	See below ↓
`file`	string	Local file path	`null`
`files`	array	List of additional file paths	`null`
`attachments`	array	List of additional attachments	`null`
`moderationStatus`	string	Moderation status of the message	`null`
`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`

attachment Object:

Parameter	Type	Description	Sample Value
`fileUrl`	string	URL of the file	`"https://pngimg.com/uploads/mario/mario_PNG125.png"`
`fileName`	string	Name of the file	`"test"`
`fileExtension`	string	File extension	`"png"`
`fileMimeType`	string	MIME type of the file	`"image/png"`
`fileSize`	number	File size in bytes	`null`

Error

Parameter	Type	Description	Sample Value
`code`	string	Error code identifier	`"ERR_INVALID_MESSAGE_TYPE"`
`message`	string	Human-readable error message	`"The message type provided is not supported."`
`details`	string	Additional technical details	`"Supported types are image, video, audio, and file."`

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.

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.

Dart

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 CustomMessage class constructor takes the following parameters:

Parameter	Description	Required
`receiverUid`	UID of the user or GUID of the group to which the message is to be sent	Yes
`receiverType`	Type of the receiver — `CometChatConversationType.user` or `CometChatConversationType.group`	Yes
`type`	Custom message type string (e.g., `"location"`, `"poll"`)	Yes
`customData`	The data to be passed as the message in the form of a `Map`	Yes
`subType`	Optional sub-type for the custom message	No

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 Metadata

To send custom data along with a custom message, you can use the metadata property and pass a Map to it.

Dart

Map<String, dynamic> metadata = {};
metadata["priority"] = "high";
metadata["source"] = "mobile";
customMessage.metadata = metadata;

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.

Dart

List<String> tags = [];
tags.add("pinned");
textMessage.tags = tags;

Set Quoted Message

To quote a message in a custom message, use the quotedMessageId property of the CustomMessage class.

Dart

customMessage.quotedMessageId = 10;

Once the object of CustomMessage class is ready you can send the custom message using the sendCustomMessage() method.

User
Group

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}");
});

String GUID = "GUID";
String subType = "LOCATION";
String receiverType = CometChatConversationType.group;
String type = CometChatMessageType.custom;

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

CustomMessage customMessage = CustomMessage(
  receiverUid: GUID,
  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.

Response

On Success — A CustomMessage object containing all details of the sent custom message:CustomMessage Object:

Parameter	Type	Description	Sample Value
`id`	number	Unique message ID	`405`
`metadata`	object	Custom metadata attached to the message	`{}`
`receiver`	object	Receiver user object	See below ↓
`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	`1745555100`
`receiverUid`	string	UID of the receiver	`"cometchat-uid-2"`
`type`	string	Type of the message	`"custom"`
`readAt`	number	Epoch timestamp when the message was read	`0`
`deletedBy`	string	UID of the user who deleted the message	`null`
`deliveredAt`	number	Epoch timestamp when the message was delivered	`0`
`deletedAt`	number	Epoch timestamp when the message was deleted	`0`
`replyCount`	number	Number of replies to this message	`0`
`sender`	object	Sender user object	See below ↓
`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	`"custom"`
`deliveredToMeAt`	number	Epoch timestamp when delivered to the current user	`0`
`updatedAt`	number	Epoch timestamp when the message was last updated	`1745555100`
`customData`	object	Custom data payload	`{"latitude": "19.0760", "longitude": "72.8777"}`
`tags`	array	List of tags associated with the message	`[]`
`unreadRepliesCount`	number	Count of unread replies	`0`
`mentionedUsers`	array	List of mentioned users	`[]`
`hasMentionedMe`	boolean	Whether the current user is mentioned	`false`
`reactions`	array	List of reactions on the message	`[]`
`text`	string	Conversation text for notifications	`null`
`updateConversation`	boolean	Whether to update the conversation’s last message	`false`
`sendNotification`	boolean	Whether to send a push notification	`false`
`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`

Error

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

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.

User
Group

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}");
});

String GUID = "GUID";
String subType = "LOCATION";
String receiverType = CometChatConversationType.group;
String type = CometChatMessageType.custom;

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

CustomMessage customMessage = CustomMessage(
  receiverUid: GUID,
  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.

User
Group

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}");
});

String GUID = "GUID";
String subType = "LOCATION";
String receiverType = CometChatConversationType.group;
String type = CometChatMessageType.custom;

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

CustomMessage customMessage = CustomMessage(
  receiverUid: GUID,
  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}");
});

It is also possible to send interactive messages from CometChat , to know more click here

Next Steps

Receive Messages

Handle incoming messages in real-time

Edit Message

Modify sent messages after delivery

Interactive Messages

Send forms, cards, and interactive elements

Delete Message

Remove messages from conversations

​Text Message

​Add Metadata

​Add Tags

​Set Quoted Message

​Media Message

​Add Metadata

​Add Caption(Text along with Media Message)

​Add Tags

​Set Quoted Message

​Custom Message

​Add Metadata

​Add Tags

​Set Quoted Message

​Update Conversation

​Custom Notification Body

​Next Steps

Receive Messages

Edit Message

Interactive Messages

Delete Message

Text Message

Add Metadata

Add Tags

Set Quoted Message

Media Message

Add Metadata

Add Caption(Text along with Media Message)

Add Tags

Set Quoted Message

Custom Message

Add Metadata

Add Tags

Set Quoted Message

Update Conversation

Custom Notification Body

Next Steps