> ## 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.
# Visão Geral
> Endpoints de envio de mensagens WhatsApp em todos os formatos suportados
**Auth:** `TokenAccount` ou `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** não
O módulo `/api/message/*` cobre o envio de **todos os formatos suportados pelo WhatsApp**, texto, mídias, sticker, localização, contato, reação, enquete, carrossel, botões, lista, formulário, PIX e status (stories). Todas as rotas validam ownership da instância e aceitam `TokenAccount` ou `TokenInstance`.
Para **buscar uma mensagem por ID** use [`GET /api/chat/getMessage/:instance`](/pt/api/chat/find-message), esse endpoint deixou de pertencer ao módulo de mensagens.
## Endpoints disponíveis
| Método | Path | Tipo |
| ------ | --------------------------------- | ------------------------------------------------------------ |
| POST | `/api/message/text/:instance` | [Texto](/pt/api/messages/text) |
| POST | `/api/message/media/:instance` | [Imagem / vídeo / áudio / documento](/pt/api/messages/media) |
| POST | `/api/message/sticker/:instance` | [Sticker (WebP)](/pt/api/messages/sticker) |
| POST | `/api/message/location/:instance` | [Localização](/pt/api/messages/location) |
| POST | `/api/message/contact/:instance` | [Contato (vCard)](/pt/api/messages/contact) |
| POST | `/api/message/reaction/:instance` | [Reação (emoji)](/pt/api/messages/reaction) |
| POST | `/api/message/poll/:instance` | [Enquete](/pt/api/messages/poll) |
| POST | `/api/message/carousel/:instance` | [Carrossel de cards](/pt/api/messages/carousel) |
| POST | `/api/message/button/:instance` | [Botões interativos](/pt/api/messages/buttons) |
| POST | `/api/message/list/:instance` | [Lista (sections)](/pt/api/messages/list) |
| POST | `/api/message/form/:instance` | [Formulário (Native Flow)](/pt/api/messages/form) |
| POST | `/api/message/pix/:instance` | [PIX (pagamento BR)](/pt/api/messages/pix) |
| POST | `/api/message/status/:instance` | [Status (stories)](/pt/api/messages/status) |
## Estrutura comum
### Destinatário (`number` ou `to`)
A maioria dos endpoints aceita o destinatário no campo `number`. Os formatos suportados são:
* Número simples: `"5511999999999"` (preferido).
* JID privado: `"5511999999999@s.whatsapp.net"`.
* JID oculto (`@lid`): `"123456789012345@lid"`, identificador anônimo usado pelo WhatsApp em grupos/canais quando o número real não está exposto.
* JID grupo: `"120363406289005073@g.us"`.
* JID newsletter: `"120363422585881117@newsletter"`.
* Status broadcast: `"status@broadcast"`.
### Comportamento brasileiro do número
Para números começando com `55` (Brasil), o serviço tenta automaticamente variações:
* Com 9 (`5511999999999`)
* Sem 9 (`551199999999`)
Isso resolve um histórico de inconsistências em DDDs antigos. Se o número não for encontrado em nenhuma das variações, o handler retorna `400 Number is not registered on WhatsApp`.
### Campos opcionais comuns
| Campo | Tipo | Aplica-se a | Descrição |
| -------------- | -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `delay` | int (segundos) | quase todos | Tempo de espera antes do envio. Durante o intervalo o servidor envia "digitando..." e depois "paused". |
| `replyTo` | string | quase todos | ID da mensagem original a citar. A mensagem precisa pertencer à mesma instância e estar no banco. |
| `replyPrivate` | bool | quase todos | Quando a mensagem citada é de grupo, redireciona a resposta para o privado do autor (mantém a citação). |
| `mention` | string\[] | text / media | Números (ou JIDs) a mencionar. **Apenas em grupos.** Limite de 10 por mensagem. |
| `mentionAll` | bool | text / media | Menciona todos os membros do grupo (`@todos`). **Apenas em grupos.** |
| `linkPreview` | bool | text | Quando `true`, busca metadados Open Graph da 1ª URL e envia como `ExtendedTextMessage` com card. Default `false`. |
| `source` | string | todos | Identificador de origem para rastreabilidade (ex.: `crm`, `n8n`). Default: `"api"`. |
`delay` é em **segundos** (não milissegundos). Valor `3` = 3 s de "digitando".
Reactions (`/api/message/reaction/:instance`) não suportam `delay`/`replyTo`/`mention`, o payload é mínimo (`messageId`, `reaction`, `participant`). Status (`/api/message/status/:instance`) também não usa `number`/`replyTo` (sempre vai para `status@broadcast`).
### Resposta padrão (200)
Todos os endpoints de envio retornam o mesmo envelope `MessageSentDetails`:
```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"
}
}
}
```
Campos opcionais no `data`: `mentions` (quando há menção), `replyTo` (quando há citação), `chat.groupName` (quando é grupo), `mediaUrl`/`mediaMimeType`/`mediaSize`/`fileName` (quando é mídia), `vcard` (quando é contato).
`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`.
### Erros comuns
| Status | Mensagem |
| ------ | ------------------------------------------------------------------------------------------------------ |
| 400 | `Instance name is required` |
| 400 | `Invalid request body: ` |
| 400 | `Number is required` |
| 400 | `Message is required` (e variantes por endpoint: `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: ` |
Envelope de erro:
```json theme={null}
{
"success": false,
"error": { "message": "Number is not registered on WhatsApp" }
}
```
## Limites observados
| Recurso | Limite |
| ---------------------- | ------------------------------------------------------------------------ |
| Texto | \~65k caracteres (mensagens > 4096 podem ser cortadas em alguns clients) |
| Imagem / vídeo / áudio | até 16 MB |
| Documento | até 100 MB |
| Botões | máx 3 por mensagem |
| Lista | máx 10 sections × 10 rows |
| Carrossel | máx 10 cards |
| Enquete | 2 a 12 opções |
## Próximos passos
Endpoint mais usado, ideal como "Hello World".
Imagem, vídeo, áudio e documento por URL ou base64.
Recupera uma mensagem específica do histórico.
Recebe eventos `message.exchange` em tempo real.