Messaging

Overview of CometChat messaging capabilities — send, receive, and fetch message history for text, media, custom, and interactive messages.

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