Messaging - CometChat Docs

Quick Reference - Core messaging methods:

// Send a text message
const textMessage = new CometChat.TextMessage("UID", "Hello!", CometChat.RECEIVER_TYPE.USER);
await CometChat.sendMessage(textMessage);

// Listen for incoming messages
CometChat.addMessageListener("listener-id", new CometChat.MessageListener({
  onTextMessageReceived: (msg) => console.log("Text:", msg),
  onMediaMessageReceived: (msg) => console.log("Media:", msg),
  onCustomMessageReceived: (msg) => console.log("Custom:", msg),
}));

Available via: SDK | REST API | UI Kits

Messaging is one of the core features of CometChat. We’ve thoughtfully created methods to help you send, receive and fetch message history. At the minimum, you must add code for sending messages and receiving messages. Once you’ve implemented that, you can proceed to more advanced features like typing indicators and delivery & read receipts.

Send a Message

Use CometChat.sendMessage() to send a text message to a user or group. The method returns a TextMessage object on success.

Response

On Success — Returns a TextMessage object:TextMessage Object:

Parameter	Type	Description	Sample Value
`id`	string	Unique message identifier	`"25182"`
`conversationId`	string	Conversation identifier	`"cometchat-uid-2_user_cometchat-uid-3"`
`text`	string	Message text content	`"Hello"`
`type`	string	Message type	`"text"`
`category`	string	Message category	`"message"`
`receiverId`	string	UID of the receiver	`"cometchat-uid-3"`
`receiverType`	string	Type of receiver	`"user"`
`sentAt`	number	Unix timestamp when sent	`1771320772`
`updatedAt`	number	Unix timestamp of last update	`1771320772`
`sender`	object	Sender user details	See below ↓
`receiver`	object	Receiver user details	See below ↓
`data`	object	Additional message data	See below ↓
`reactions`	array	Message reactions	`[]`
`mentionedUsers`	array	Users mentioned in message	`[]`
`mentionedMe`	boolean	Whether logged-in user is mentioned	`false`
`metadata`	object	Custom metadata	`{"@injected": {"extensions": {"link-preview": {"links": []}}}}`

sender Object:

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the sender	`"cometchat-uid-2"`
`name`	string	Display name	`"George Alan"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320632`
`hasBlockedMe`	boolean	Whether sender has blocked logged-in user	`false`
`blockedByMe`	boolean	Whether logged-in user has blocked sender	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

receiver Object:

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the receiver	`"cometchat-uid-3"`
`name`	string	Display name	`"Nancy Grace"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320647`
`hasBlockedMe`	boolean	Whether receiver has blocked logged-in user	`false`
`blockedByMe`	boolean	Whether logged-in user has blocked receiver	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

data Object:

Parameter	Type	Description	Sample Value
`text`	string	Message text	`"Hello"`
`resource`	string	SDK resource identifier	`"REACT_NATIVE-4_0_13-..."`
`entities`	object	Sender and receiver entities	See below ↓
`metadata`	object	Injected metadata from extensions	`{"@injected": {"extensions": {"link-preview": {"links": []}}}}`
`moderation`	object	Moderation status	See below ↓

data.entities Object:

Parameter	Type	Description	Sample Value
`sender`	object	Sender entity wrapper	See below ↓
`receiver`	object	Receiver entity wrapper	See below ↓

data.entities.sender Object:

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	Sender user details	See below ↓

data.entities.sender.entity Object:

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier	`"cometchat-uid-2"`
`name`	string	Display name	`"George Alan"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320632`
`tags`	array	User tags	`[]`

data.entities.receiver Object:

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	Receiver user details	See below ↓

data.entities.receiver.entity Object:

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier	`"cometchat-uid-3"`
`name`	string	Display name	`"Nancy Grace"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320647`
`conversationId`	string	Conversation identifier	`"cometchat-uid-2_user_cometchat-uid-3"`
`tags`	array	User tags	`[]`

data.moderation Object:

Parameter	Type	Description	Sample Value
`status`	string	Moderation status	`"pending"`

Receive Messages in Real Time

Use CometChat.addMessageListener() to listen for incoming text, media, and custom messages while your app is running.

Response

onTextMessageReceived — Returns a TextMessage object:TextMessage Object:

Parameter	Type	Description	Sample Value
`id`	string	Unique message identifier	`"25180"`
`conversationId`	string	Conversation identifier	`"cometchat-uid-2_user_cometchat-uid-3"`
`text`	string	Message text content	`"Hello"`
`type`	string	Message type	`"text"`
`category`	string	Message category	`"message"`
`receiverId`	string	UID of the receiver	`"cometchat-uid-2"`
`receiverType`	string	Type of receiver	`"user"`
`sentAt`	number	Unix timestamp when sent	`1771320657`
`updatedAt`	number	Unix timestamp of last update	`1771320657`
`sender`	object	Sender user details	See below ↓
`receiver`	object	Receiver user details	See below ↓
`data`	object	Additional message data	See below ↓
`reactions`	array	Message reactions	`[]`
`mentionedUsers`	array	Users mentioned in message	`[]`
`mentionedMe`	boolean	Whether logged-in user is mentioned	`false`
`metadata`	object	Custom metadata	`{"@injected": {"extensions": {"link-preview": {"links": []}}}}`

sender Object (TextMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the sender	`"cometchat-uid-3"`
`name`	string	Display name	`"Nancy Grace"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320647`
`hasBlockedMe`	boolean	Whether sender has blocked logged-in user	`false`
`blockedByMe`	boolean	Whether logged-in user has blocked sender	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

receiver Object (TextMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the receiver	`"cometchat-uid-2"`
`name`	string	Display name	`"George Alan"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320632`
`hasBlockedMe`	boolean	Whether receiver has blocked logged-in user	`false`
`blockedByMe`	boolean	Whether logged-in user has blocked receiver	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

data Object (TextMessage):

Parameter	Type	Description	Sample Value
`text`	string	Message text	`"Hello"`
`resource`	string	SDK resource identifier	`"REACT_NATIVE-4_0_13-..."`
`entities`	object	Sender and receiver entities	See below ↓
`metadata`	object	Injected metadata from extensions	`{"@injected": {"extensions": {"link-preview": {"links": []}}}}`
`moderation`	object	Moderation status	`{"status": "approved"}`

data.entities Object (TextMessage):

Parameter	Type	Description	Sample Value
`sender`	object	Sender entity wrapper	See below ↓
`receiver`	object	Receiver entity wrapper	See below ↓

data.entities.sender Object (TextMessage):

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	Sender user details	See below ↓

data.entities.sender.entity Object (TextMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier	`"cometchat-uid-3"`
`name`	string	Display name	`"Nancy Grace"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320647`
`tags`	array	User tags	`[]`

data.entities.receiver Object (TextMessage):

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	Receiver user details	See below ↓

data.entities.receiver.entity Object (TextMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier	`"cometchat-uid-2"`
`name`	string	Display name	`"George Alan"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320632`
`conversationId`	string	Conversation identifier	`"cometchat-uid-2_user_cometchat-uid-3"`
`tags`	array	User tags	`[]`

onMediaMessageReceived — Returns a MediaMessage object:MediaMessage Object:

Parameter	Type	Description	Sample Value
`id`	string	Unique message identifier	`"25183"`
`conversationId`	string	Conversation identifier	`"cometchat-uid-2_user_cometchat-uid-3"`
`type`	string	Media type	`"image"`
`category`	string	Message category	`"message"`
`receiverId`	string	UID of the receiver	`"cometchat-uid-2"`
`receiverType`	string	Type of receiver	`"user"`
`sentAt`	number	Unix timestamp when sent	`1771320862`
`updatedAt`	number	Unix timestamp of last update	`1771320862`
`sender`	object	Sender user details	See below ↓
`receiver`	object	Receiver user details	See below ↓
`data`	object	Additional message data	See below ↓
`reactions`	array	Message reactions	`[]`
`mentionedUsers`	array	Users mentioned in message	`[]`
`mentionedMe`	boolean	Whether logged-in user is mentioned	`false`

sender Object (MediaMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the sender	`"cometchat-uid-3"`
`name`	string	Display name	`"Nancy Grace"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"`
`status`	string	Online status	`"offline"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320859`
`hasBlockedMe`	boolean	Whether sender has blocked logged-in user	`false`
`blockedByMe`	boolean	Whether logged-in user has blocked sender	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

receiver Object (MediaMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the receiver	`"cometchat-uid-2"`
`name`	string	Display name	`"George Alan"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320632`
`hasBlockedMe`	boolean	Whether receiver has blocked logged-in user	`false`
`blockedByMe`	boolean	Whether logged-in user has blocked receiver	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

data Object (MediaMessage):

Parameter	Type	Description	Sample Value
`type`	string	Media type	`"image"`
`category`	string	Message category	`"message"`
`url`	string	URL to the media file	`"https://data-in.cometchat.io/.../1771320861_514214897_9876c9a3f300f29c8ee619765c1ad768.jpg"`
`resource`	string	SDK resource identifier	`"REACT_NATIVE-4_0_13-..."`
`attachments`	array	Media attachments	See below ↓
`entities`	object	Sender and receiver entities	See below ↓
`moderation`	object	Moderation status	`{"status": "approved"}`

data.attachments Array (per item):

Parameter	Type	Description	Sample Value
`url`	string	URL to the attachment	`"https://data-in.cometchat.io/.../1771320861_514214897_9876c9a3f300f29c8ee619765c1ad768.jpg"`
`name`	string	File name	`"44.jpg"`
`mimeType`	string	MIME type	`"image/jpeg"`
`extension`	string	File extension	`"jpg"`
`size`	number	File size in bytes	`142099`

data.entities Object (MediaMessage):

Parameter	Type	Description	Sample Value
`sender`	object	Sender entity wrapper	See below ↓
`receiver`	object	Receiver entity wrapper	See below ↓

data.entities.sender Object (MediaMessage):

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	Sender user details	See below ↓

data.entities.sender.entity Object (MediaMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier	`"cometchat-uid-3"`
`name`	string	Display name	`"Nancy Grace"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"`
`status`	string	Online status	`"offline"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320859`
`tags`	array	User tags	`[]`

data.entities.receiver Object (MediaMessage):

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	Receiver user details	See below ↓

data.entities.receiver.entity Object (MediaMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier	`"cometchat-uid-2"`
`name`	string	Display name	`"George Alan"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771320632`
`conversationId`	string	Conversation identifier	`"cometchat-uid-2_user_cometchat-uid-3"`
`tags`	array	User tags	`[]`

onCustomMessageReceived — Returns a CustomMessage object:CustomMessage Object:

Parameter	Type	Description	Sample Value
`id`	string	Unique message identifier	`"25191"`
`conversationId`	string	Conversation identifier	`"cometchat-uid-2_user_cometchat-uid-3"`
`type`	string	Custom message type	`"test-custom"`
`category`	string	Message category	`"custom"`
`receiverId`	string	UID of the receiver	`"cometchat-uid-2"`
`receiverType`	string	Type of receiver	`"user"`
`sentAt`	number	Unix timestamp when sent	`1771324025`
`updatedAt`	number	Unix timestamp of last update	`1771324025`
`customData`	object	Custom payload data	See below ↓
`sender`	object	Sender user details	See below ↓
`receiver`	object	Receiver user details	See below ↓
`data`	object	Additional message data	See below ↓
`reactions`	array	Message reactions	`[]`
`mentionedUsers`	array	Users mentioned in message	`[]`
`mentionedMe`	boolean	Whether logged-in user is mentioned	`false`
`metadata`	object	Custom metadata	`{"@injected": {"extensions": {"link-preview": {"links": []}}}}`

customData Object:

Parameter	Type	Description	Sample Value
`greeting`	string	Custom greeting message	`"Hello from custom message!"`
`timestamp`	number	Custom timestamp	`1771324022864`

sender Object (CustomMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the sender	`"cometchat-uid-3"`
`name`	string	Display name	`"Nancy Grace"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"`
`status`	string	Online status	`"offline"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771323567`
`hasBlockedMe`	boolean	Whether sender has blocked logged-in user	`false`
`blockedByMe`	boolean	Whether logged-in user has blocked sender	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

receiver Object (CustomMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the receiver	`"cometchat-uid-2"`
`name`	string	Display name	`"George Alan"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771323089`
`hasBlockedMe`	boolean	Whether receiver has blocked logged-in user	`false`
`blockedByMe`	boolean	Whether logged-in user has blocked receiver	`false`
`deactivatedAt`	number	Deactivation timestamp (0 if active)	`0`
`tags`	array	User tags	`[]`

data Object (CustomMessage):

Parameter	Type	Description	Sample Value
`text`	string	Fallback text	`"Sent a custom message"`
`resource`	string	SDK resource identifier	`"REACT_NATIVE-4_0_14-..."`
`customData`	object	Custom payload data	`{"greeting": "Hello from custom message!", "timestamp": 1771324022864}`
`entities`	object	Sender and receiver entities	See below ↓
`metadata`	object	Injected metadata from extensions	`{"@injected": {"extensions": {"link-preview": {"links": []}}}}`
`moderation`	object	Moderation status	`{"status": "approved"}`

data.entities Object (CustomMessage):

Parameter	Type	Description	Sample Value
`sender`	object	Sender entity wrapper	See below ↓
`receiver`	object	Receiver entity wrapper	See below ↓

data.entities.sender Object (CustomMessage):

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	Sender user details	See below ↓

data.entities.sender.entity Object (CustomMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier	`"cometchat-uid-3"`
`name`	string	Display name	`"Nancy Grace"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"`
`status`	string	Online status	`"offline"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771323567`
`tags`	array	User tags	`[]`

data.entities.receiver Object (CustomMessage):

Parameter	Type	Description	Sample Value
`entityType`	string	Type of entity	`"user"`
`entity`	object	Receiver user details	See below ↓

data.entities.receiver.entity Object (CustomMessage):

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier	`"cometchat-uid-2"`
`name`	string	Display name	`"George Alan"`
`avatar`	string	URL to avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
`status`	string	Online status	`"online"`
`role`	string	User role	`"default"`
`lastActiveAt`	number	Unix timestamp of last activity	`1771323089`
`conversationId`	string	Conversation identifier	`"cometchat-uid-2_user_cometchat-uid-3"`
`tags`	array	User tags	`[]`

Next Steps

Send a Message

Send text, media, and custom messages to users and groups

Receive Messages

Listen for real-time messages and fetch missed messages

Typing Indicators

Show real-time typing status in conversations

Delivery & Read Receipts

Track when messages are delivered and read

​Send a Message

​Receive Messages in Real Time

​Next Steps

Send a Message

Receive Messages

Typing Indicators

Delivery & Read Receipts

Send a Message

Receive Messages in Real Time

Next Steps