Overview

Send, retrieve, and manage messages in one-on-one and group conversations.

A Message is the core unit of communication in CometChat. Users can send text, media files, and custom data to other users or groups. Messages support threading, reactions, read receipts, and delivery tracking.

Key behaviors

• Maximum file upload size is 100 MB per message (includes the file and the entire POST body).
• The message JSON payload (including metadata) can be up to 65,536 characters (~65 KB).
• The data object within a message must not exceed 10 KB. It accepts any JSON structure with UTF8mb4 encoding.
• Messages can have up to 25 tags, each up to 100 characters (UTF8mb4).
• Soft-deleted messages remain in the database. Permanently deleted messages (via API) are removed entirely.
• For groups with more than 300 members, unread message counts and conversations are not updated.
• Delivery and read receipts are sent for groups of up to 300 online users.

How messages connect to other resources

• Users — Messages are sent by and delivered to Users. The sender must be authenticated.
• Groups — Messages can target a Group by specifying the group’s GUID as the receiver.
• Conversations — Each message exchange creates or updates a Conversation that tracks the last message and unread count.
• Threads — Any message can be a parent for a thread. Replies are managed via the threaded messages endpoints.
• Reactions — Users can add or remove emoji reactions on messages.

Available operations

Operation	Method	Endpoint	Description
Send Message	POST	/messages	Send a message to a user or group
List Messages	GET	/messages	Retrieve all messages for the authenticated user
List User Messages	GET	/users/{uid}/messages	Retrieve messages in a 1-on-1 conversation
List Group Messages	GET	/groups/{guid}/messages	Retrieve messages in a group conversation
Get Message	GET	/messages/{id}	Retrieve a specific message by ID
Update Message	PUT	/messages/{id}	Edit a sent message
Delete Message	DELETE	/messages/{id}	Soft-delete or permanently delete a message
Send Threaded Message	POST	/messages/{id}/thread	Reply to a message in a thread
List Threaded Messages	GET	/messages/{id}/thread	Retrieve all replies in a thread
Send Bot Message	POST	/bots/{uid}/messages	Send a message as a bot user
Add Reaction	POST	/messages/{id}/reactions	Add an emoji reaction to a message
Remove Reaction	DELETE	/messages/{id}/reactions/{reaction}	Remove an emoji reaction from a message
List All Reactions	GET	/messages/{id}/reactions	List all reactions on a message
List Reactions by Emoji	GET	/messages/{id}/reactions/{reaction}	List reactions filtered by a specific emoji

Message properties

Property	Type	Description
id	integer	Unique message identifier. System-generated, read-only.
type	string	Message type: text, image, audio, video, file, or a custom type.
category	string	Message category: message or custom.
data	object	Arbitrary JSON structure (max 10 KB). Recognized keys: text, attachments, custom_data, metadata. Accepts UTF8mb4.
tags	array of strings	Tags for categorizing messages. Max 25 tags, 100 characters each (UTF8mb4).
sender	string	UID of the user who sent the message. Read-only.
receiver	string	UID (for user messages) or GUID (for group messages) of the recipient.
receiverType	string	Receiver type: user or group.
sentAt	integer	UNIX timestamp of when the message was sent. Read-only.

Error handling

Error Code	Description
AUTH_ERR_EMPTY_APIKEY	API key is missing from the request headers
AUTH_ERR_APIKEY_NOT_FOUND	The provided API key is invalid
ERR_MSG_NOT_FOUND	The specified message does not exist
ERR_UID_NOT_FOUND	The receiver UID does not exist
ERR_GUID_NOT_FOUND	The receiver group GUID does not exist

For the complete list of error codes, see Error Guide.

For all system limits (file upload size, message payload, tag counts, etc.), see Properties and Constraints.