> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Send, retrieve, and manage CometChat messages with REST APIs for user and group chats, including text, media, threads, and reactions.

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.
* A conversation can hold up to **100 pinned messages**. Pins made on behalf of a user and pins made as the app (without `onBehalfOf`) share this limit. Exceeding this limit returns `ERR_PINNED_MESSAGES_LIMIT_EXCEEDED`.
* A user can save up to **100 messages**. Saved messages are private to the user who saved them. Exceeding this limit returns `ERR_SAVED_MESSAGES_LIMIT_EXCEEDED`.
* 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](/rest-api/users). The sender must be authenticated.
* **Groups** — Messages can target a [Group](/rest-api/groups) by specifying the group's GUID as the receiver.
* **Conversations** — Each message exchange creates or updates a [Conversation](/rest-api/conversations) 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](/rest-api/messages/list-threaded-messages) endpoints.
* **Reactions** — Users can [add](/rest-api/messages/add-reaction) or [remove](/rest-api/messages/remove-reaction) emoji reactions on messages.

### Available operations

| Operation | Method | Endpoint | Description |
| - | - | - | - |
| [Send Message](/rest-api/messages/send-message) | `POST` | `/messages` | Send a message to a user or group |
| [List Messages](/rest-api/messages/list-messages) | `GET` | `/messages` | Retrieve all messages for the authenticated user |
| [List User Messages](/rest-api/messages/list-user-messages) | `GET` | `/users/{uid}/messages` | Retrieve messages in a 1-on-1 conversation |
| [List Group Messages](/rest-api/messages/list-group-messages) | `GET` | `/groups/{guid}/messages` | Retrieve messages in a group conversation |
| [Get Message](/rest-api/messages/get-message) | `GET` | `/messages/{id}` | Retrieve a specific message by ID |
| [Update Message](/rest-api/messages/update-message) | `PUT` | `/messages/{id}` | Edit a sent message |
| [Delete Message](/rest-api/messages/delete-message) | `DELETE` | `/messages/{id}` | Soft-delete or permanently delete a message |
| [Pin Message](/rest-api/messages/pin-message) | `POST` | `/messages/{id}/pin` | Pin a message in its conversation |
| [Unpin Message](/rest-api/messages/unpin-message) | `DELETE` | `/messages/{id}/pin` | Unpin a message |
| [Save Message](/rest-api/messages/save-message) | `POST` | `/messages/{id}/save` | Save a message to a user's private saved list |
| [Unsave Message](/rest-api/messages/unsave-message) | `DELETE` | `/messages/{id}/save` | Remove a message from a user's saved list |
| [Mark Message As Interacted](/rest-api/messages/mark-message-as-interacted) | `PATCH` | `/messages/{id}/interacted` | Mark elements of an interactive message as interacted |
| [Send Threaded Message](/rest-api/messages/send-threaded-message) | `POST` | `/messages/{id}/thread` | Reply to a message in a thread |
| [List Threaded Messages](/rest-api/messages/list-threaded-messages) | `GET` | `/messages/{id}/thread` | Retrieve all replies in a thread |
| [List Threads](/rest-api/messages/list-threads) | `GET` | `/threads` | List threads across conversations |
| [Subscribe Thread](/rest-api/messages/subscribe-thread) | `POST` | `/messages/{id}/thread/subscription` | Subscribe a user to a thread |
| [Unsubscribe Thread](/rest-api/messages/unsubscribe-thread) | `DELETE` | `/messages/{id}/thread/subscription` | Unsubscribe a user from a thread |
| [Send Bot Message](/rest-api/messages/send-bot-message) | `POST` | `/bots/{uid}/messages` | Send a message as a bot user |
| [Add Reaction](/rest-api/messages/add-reaction) | `POST` | `/messages/{id}/reactions` | Add an emoji reaction to a message |
| [Remove Reaction](/rest-api/messages/remove-reaction) | `DELETE` | `/messages/{id}/reactions/{reaction}` | Remove an emoji reaction from a message |
| [List All Reactions](/rest-api/messages/list-all-reactions) | `GET` | `/messages/{id}/reactions` | List all reactions on a message |
| [List Reactions by Emoji](/rest-api/messages/list-reactions-with-a-specific-emoji-unicode) | `GET` | `/messages/{id}/reactions/{reaction}` | List reactions filtered by a specific emoji |

Save Message, Unsave Message, Mark Message As Interacted, Subscribe Thread and Unsubscribe Thread require the `onBehalfOf` header, since they act for a specific user. Pin Message and Unpin Message accept it optionally — without it the message is pinned as the app itself.

### 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 |
| `ERR_PINNED_MESSAGES_LIMIT_EXCEEDED` | The conversation has reached its pinned-message limit |
| `ERR_SAVED_MESSAGES_LIMIT_EXCEEDED` | The user has reached their saved-message limit |

For the complete list of error codes, see [Error Guide](/articles/error-guide).

For all system limits (file upload size, message payload, tag counts, etc.), see [Properties and Constraints](/articles/properties-and-constraints).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.