> ## 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.
# Resumen
> Endpoints para enviar mensajes de WhatsApp en todos los formatos compatibles
**Auth:** `TokenAccount` o `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** no
El módulo `/api/message/*` cubre el envío de **todos los formatos compatibles con WhatsApp**, texto, media, sticker, ubicación, contacto, reacción, encuesta, carrusel, botones, lista, formulario, PIX y status (historias). Todas las rutas validan la propiedad de la instancia y aceptan tanto `TokenAccount` como `TokenInstance`.
Para **buscar un mensaje por ID** usa [`GET /api/chat/getMessage/:instance`](/es/api/chat/find-message); ese endpoint ya no pertenece al módulo de mensajes.
## Endpoints disponibles
| Método | Ruta | Tipo |
| ------ | --------------------------------- | ------------------------------------------------------------ |
| POST | `/api/message/text/:instance` | [Texto](/es/api/messages/text) |
| POST | `/api/message/media/:instance` | [Imagen / video / audio / documento](/es/api/messages/media) |
| POST | `/api/message/sticker/:instance` | [Sticker (WebP)](/es/api/messages/sticker) |
| POST | `/api/message/location/:instance` | [Ubicación](/es/api/messages/location) |
| POST | `/api/message/contact/:instance` | [Contacto (vCard)](/es/api/messages/contact) |
| POST | `/api/message/reaction/:instance` | [Reacción (emoji)](/es/api/messages/reaction) |
| POST | `/api/message/poll/:instance` | [Encuesta](/es/api/messages/poll) |
| POST | `/api/message/carousel/:instance` | [Carrusel de tarjetas](/es/api/messages/carousel) |
| POST | `/api/message/button/:instance` | [Botones interactivos](/es/api/messages/buttons) |
| POST | `/api/message/list/:instance` | [Lista (secciones)](/es/api/messages/list) |
| POST | `/api/message/form/:instance` | [Formulario (Native Flow)](/es/api/messages/form) |
| POST | `/api/message/pix/:instance` | [PIX (pago BR)](/es/api/messages/pix) |
| POST | `/api/message/status/:instance` | [Status (historias)](/es/api/messages/status) |
## Estructura común
### Destinatario (`number` o `to`)
La mayoría de los endpoints aceptan al destinatario en el campo `number`. Formatos soportados:
* Número simple: `"5511999999999"` (preferido).
* JID privado: `"5511999999999@s.whatsapp.net"`.
* JID oculto (`@lid`): `"123456789012345@lid"`, identificador anónimo que WhatsApp usa en grupos/canales cuando el número real no está expuesto.
* JID de grupo: `"120363406289005073@g.us"`.
* JID de newsletter: `"120363422585881117@newsletter"`.
* Status broadcast: `"status@broadcast"`.
### Comportamiento de números brasileños
Para números que comienzan con `55` (Brasil), el servicio prueba automáticamente variaciones:
* Con 9 (`5511999999999`)
* Sin 9 (`551199999999`)
Esto soluciona una inconsistencia histórica en los códigos de área antiguos. Si el número no se encuentra en ninguna de las variaciones, el handler retorna `400 Number is not registered on WhatsApp`.
### Campos opcionales comunes
| Campo | Tipo | Aplica a | Descripción |
| -------------- | -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `delay` | int (segundos) | casi todos | Tiempo de espera antes de enviar. Durante el intervalo el servidor envía "escribiendo..." y luego "pausado". |
| `replyTo` | string | casi todos | ID del mensaje original a citar. El mensaje debe pertenecer a la misma instancia y existir en la base de datos. |
| `replyPrivate` | bool | casi todos | Cuando el mensaje citado es de un grupo, redirige la respuesta al chat privado del autor (manteniendo la cita). |
| `mention` | string\[] | text / media | Números (o JIDs) a mencionar. **Solo en chats de grupo.** Límite de 10 por mensaje. |
| `mentionAll` | bool | text / media | Menciona a todos los miembros del grupo (`@everyone`). **Solo en chats de grupo.** |
| `linkPreview` | bool | text | Cuando es `true`, obtiene metadatos Open Graph de la primera URL y envía como `ExtendedTextMessage` con una tarjeta. Default `false`. |
| `source` | string | todos | Identificador de origen para trazabilidad (p. ej., `crm`, `n8n`). Default: `"api"`. |
`delay` es en **segundos** (no milisegundos). Un valor de `3` = 3 s de "escribiendo".
Las reacciones (`/api/message/reaction/:instance`) no soportan `delay`/`replyTo`/`mention`, el payload es mínimo (`messageId`, `reaction`, `participant`). Status (`/api/message/status/:instance`) tampoco usa `number`/`replyTo` (siempre va a `status@broadcast`).
### Respuesta estándar (200)
Todos los endpoints de envío retornan el mismo envoltorio `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 opcionales en `data`: `mentions` (cuando hay una mención), `replyTo` (cuando hay una cita), `chat.groupName` (cuando es un grupo), `mediaUrl`/`mediaMimeType`/`mediaSize`/`fileName` (cuando es media), `vcard` (cuando es un contacto).
`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`.
### Errores comunes
| Status | Mensaje |
| ------ | ------------------------------------------------------------------------------------------------------ |
| 400 | `Instance name is required` |
| 400 | `Invalid request body: ` |
| 400 | `Number is required` |
| 400 | `Message is required` (y 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: ` |
Envoltorio de error:
```json theme={null}
{
"success": false,
"error": { "message": "Number is not registered on WhatsApp" }
}
```
## Límites observados
| Recurso | Límite |
| ---------------------- | ---------------------------------------------------------------------------- |
| Texto | \~65k caracteres (mensajes > 4096 pueden ser truncados por algunos clientes) |
| Imagen / video / audio | hasta 16 MB |
| Documento | hasta 100 MB |
| Botones | máx. 3 por mensaje |
| Lista | máx. 10 secciones × 10 filas |
| Carrusel | máx. 10 tarjetas |
| Encuesta | 2 a 12 opciones |
## Próximos pasos
El endpoint más usado, ideal como "Hello World".
Imagen, video, audio y documento por URL o base64.
Recupera un mensaje específico del historial.
Recibe eventos `message.exchange` en tiempo real.