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
dataobject 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 |