> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Endpoints for sending WhatsApp messages in every supported format
**Auth:** `TokenAccount` or `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotent:** no
The `/api/message/*` module covers sending **every format supported by WhatsApp**, text, media, sticker, location, contact, reaction, poll, carousel, buttons, list, form, PIX and status (stories). All routes validate instance ownership and accept either `TokenAccount` or `TokenInstance`.
To **fetch a message by ID** use [`GET /api/chat/getMessage/:instance`](/en/api/chat/find-message); that endpoint no longer belongs to the messages module.
## Available endpoints
| Method | Path | Type |
| ------ | --------------------------------- | ---------------------------------------------------------- |
| POST | `/api/message/text/:instance` | [Text](/en/api/messages/text) |
| POST | `/api/message/media/:instance` | [Image / video / audio / document](/en/api/messages/media) |
| POST | `/api/message/sticker/:instance` | [Sticker (WebP)](/en/api/messages/sticker) |
| POST | `/api/message/location/:instance` | [Location](/en/api/messages/location) |
| POST | `/api/message/contact/:instance` | [Contact (vCard)](/en/api/messages/contact) |
| POST | `/api/message/reaction/:instance` | [Reaction (emoji)](/en/api/messages/reaction) |
| POST | `/api/message/poll/:instance` | [Poll](/en/api/messages/poll) |
| POST | `/api/message/carousel/:instance` | [Card carousel](/en/api/messages/carousel) |
| POST | `/api/message/button/:instance` | [Interactive buttons](/en/api/messages/buttons) |
| POST | `/api/message/list/:instance` | [List (sections)](/en/api/messages/list) |
| POST | `/api/message/form/:instance` | [Form (Native Flow)](/en/api/messages/form) |
| POST | `/api/message/pix/:instance` | [PIX (BR payment)](/en/api/messages/pix) |
| POST | `/api/message/status/:instance` | [Status (stories)](/en/api/messages/status) |
## Common structure
### Recipient (`number` or `to`)
Most endpoints accept the recipient in the `number` field. Supported formats:
* Plain number: `"5511999999999"` (preferred).
* Private JID: `"5511999999999@s.whatsapp.net"`.
* Hidden JID (`@lid`): `"123456789012345@lid"`, anonymous identifier WhatsApp uses in groups/channels when the real number is not exposed.
* Group JID: `"120363406289005073@g.us"`.
* Newsletter JID: `"120363422585881117@newsletter"`.
* Status broadcast: `"status@broadcast"`.
### Brazilian number behavior
For numbers starting with `55` (Brazil), the service automatically tries variations:
* With 9 (`5511999999999`)
* Without 9 (`551199999999`)
This works around a long-standing inconsistency in older area codes. If the number is not found in any of the variations, the handler returns `400 Number is not registered on WhatsApp`.
### Common optional fields
| Field | Type | Applies to | Description |
| -------------- | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `delay` | int (seconds) | almost all | Wait time before sending. During the interval the server sends "typing..." and then "paused". |
| `replyTo` | string | almost all | ID of the original message to quote. The message must belong to the same instance and exist in the database. |
| `replyPrivate` | bool | almost all | When the quoted message is from a group, redirects the reply to the author's private chat (keeping the quote). |
| `mention` | string\[] | text / media | Numbers (or JIDs) to mention. **Group chats only.** Limit of 10 per message. |
| `mentionAll` | bool | text / media | Mentions every member of the group (`@everyone`). **Group chats only.** |
| `linkPreview` | bool | text | When `true`, fetches Open Graph metadata from the first URL and sends as `ExtendedTextMessage` with a card. Default `false`. |
| `source` | string | all | Origin identifier for traceability (e.g., `crm`, `n8n`). Default: `"api"`. |
`delay` is in **seconds** (not milliseconds). A value of `3` = 3 s of "typing".
Reactions (`/api/message/reaction/:instance`) do not support `delay`/`replyTo`/`mention`, the payload is minimal (`messageId`, `reaction`, `participant`). Status (`/api/message/status/:instance`) also does not use `number`/`replyTo` (it always goes to `status@broadcast`).
### Standard response (200)
All send endpoints return the same `MessageSentDetails` envelope:
```json theme={null}
{
"success": true,
"message": "Message sent successfully",
"status": "sent",
"data": {
"messageId": "3EB08FCF27E532F1B0F5",
"direction": "outgoing",
"messageType": "text",
"content": "Ola!",
"source": "api",
"timestamp": "2026-04-30T14:30:00Z",
"chat": {
"jid": "5511999999999@s.whatsapp.net",
"isGroup": false
},
"sender": {
"jid": "5511777777777@s.whatsapp.net",
"instance": "minha-instancia"
}
}
}
```
Optional fields in `data`: `mentions` (when there is a mention), `replyTo` (when there is a quote), `chat.groupName` (when it is a group), `mediaUrl`/`mediaMimeType`/`mediaSize`/`fileName` (when it is media), `vcard` (when it is a contact).
`status` ∈ `sent | disconnected | invalid_number | mentions_not_supported | reply_message_not_found | reply_message_instance_mismatch | private_reply_failed | send_failed | media_download_failed | media_upload_failed | media_validation_failed | unsupported_media_type | image_conversion_failed | sticker_upload_failed | audio_conversion_failed | invalid_message_id | missing_participant | invalid_request`.
### Common errors
| Status | Message |
| ------ | ------------------------------------------------------------------------------------------------------- |
| 400 | `Instance name is required` |
| 400 | `Invalid request body: ` |
| 400 | `Number is required` |
| 400 | `Message is required` (and per-endpoint variants: `MediaURL is required`, `Question is required`, etc.) |
| 400 | `Mentions are only supported in group chats` |
| 400 | `Original message not found (ID: ...)` |
| 400 | `Original message does not belong to this instance` |
| 404 | `Instance not found` |
| 503 | `Instance is not connected to WhatsApp` |
| 500 | `Failed to send message: ` |
Error envelope:
```json theme={null}
{
"success": false,
"error": { "message": "Number is not registered on WhatsApp" }
}
```
## Observed limits
| Resource | Limit |
| --------------------- | ------------------------------------------------------------------- |
| Text | \~65k characters (messages > 4096 may be truncated by some clients) |
| Image / video / audio | up to 16 MB |
| Document | up to 100 MB |
| Buttons | max 3 per message |
| List | max 10 sections × 10 rows |
| Carousel | max 10 cards |
| Poll | 2 to 12 options |
## Next steps
The most-used endpoint, ideal as a "Hello World".
Image, video, audio and document by URL or base64.
Retrieves a specific message from the history.
Receive `message.exchange` events in real time.