> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Enviar un mensaje de WhatsApp
> Envía mensajes de plantilla, de sesión y multimedia de WhatsApp con la API en cola o sincrónica.
## Qué es
La API de WhatsApp Messages envía mensajes de plantilla, texto, imagen, video, audio, documento,
sticker, ubicación, interactivos, contacto y de reacción desde un número de teléfono
de WhatsApp business conectado.
## Antes de comenzar
* Guarda tu clave de API de YCloud en `YCLOUD_API_KEY`.
* Conecta una cuenta de WhatsApp Business y un número de teléfono a YCloud.
* Obtén el número de teléfono del remitente en formato E.164 y el número de teléfono
del destinatario, BSUID o BSUID principal.
* Usa una plantilla `APPROVED` para envíos de plantillas habituales.
* Sube el archivo multimedia primero cuando el mensaje haga referencia a un ID de archivo multimedia de YCloud.
## Cómo funciona
Elige el endpoint según cuándo deba YCloud enviar el mensaje a la
WhatsApp Business API.
| Endpoint | Comportamiento | Úsalo para |
| - | - | - |
| `POST /whatsapp/messages` | Pone en cola el mensaje y lo envía de forma asíncrona. | La mayoría de los flujos de trabajo de mensajería saliente. |
| `POST /whatsapp/messages/sendDirectly` | Envía el mensaje de forma sincrónica a la WhatsApp Business API. | OTP y otros mensajes urgentes. |
Ambos endpoints devuelven un objeto de mensaje de YCloud. La respuesta inicial no
confirma la entrega final. Los cambios de estado posteriores llegan a través de
Webhooks de `whatsapp.message.updated`.
## Direct Send para contenido de utilidad
Direct Send puede enviar contenido de utilidad elegible o convertir una plantilla de
utilidad existente. Funciona con cualquiera de los endpoints de envío. El endpoint `sendDirectly`
controla el envío sincrónico; no habilita Direct Send por sí mismo.
Sigue las [mejores prácticas de Direct Send](/es/api-reference/guides/whatsapp-platform/best-practices/direct-send)
para elegibilidad, solicitudes, conversión de plantillas, límites y eventos de la cuenta.
## Elige el mejor momento de envío
Haz coincidir la hora de envío con el propósito del mensaje y la hora local del destinatario.
* Envía OTP y otros mensajes urgentes de inmediato. Usa
`POST /whatsapp/messages/sendDirectly` cuando tu flujo de trabajo necesite el resultado del
envío antes de continuar.
* Envía actualizaciones transaccionales cuando ocurra el evento relacionado, como un pago,
envío o cambio de cita.
* Programa los mensajes de marketing en horarios razonables según la zona horaria del destinatario.
Usa tus propios datos de entrega, lectura y conversión para probar diferentes franjas horarias
para cada audiencia en lugar de asumir una única mejor hora universal.
* Comienza una campaña programada con un grupo pequeño de destinatarios. Revisa los resultados de entrega,
respuesta y cancelaciones de suscripción antes de enviar al resto de la audiencia.
* Evita envíos repetidos cuando un mensaje se retrase. Guarda `externalId` y procesa
Webhooks de `whatsapp.message.updated` antes de decidir si reintentar.
## Solicitud
Elige cualquiera de los endpoints anteriores y luego usa el cuerpo de solicitud que coincida con el tipo
de mensaje. El valor `from` es tu número de teléfono de WhatsApp business conectado. Dirige el mensaje
al destinatario con `to` en formato E.164 o con `recipient` establecido en un BSUID o
BSUID principal.
### Campos de solicitud comunes
| Campo | Obligatorio | Descripción |
| - | - | - |
| `from` | Sí | Número de teléfono de WhatsApp business conectado en formato E.164. |
| `to` | Condicional | Número de teléfono del destinatario en formato E.164. Obligatorio cuando `recipient` está ausente. |
| `recipient` | Condicional | BSUID o BSUID principal del destinatario. Obligatorio cuando `to` está ausente. |
| `type` | Sí | Tipo de mensaje. Incluye el campo de contenido que coincida con este valor. |
| `template`, `text`, `image` y otros campos de tipo | Condicional | Objeto de contenido requerido por el `type` seleccionado. |
| `context` | No | Contexto del mensaje utilizado al responder a un mensaje anterior. |
| `externalId` | No | Tu referencia única para conciliar el mensaje con un registro interno. |
| `filterUnsubscribed` | No | Solo para encolar. El valor predeterminado es `false`; cuando es `true`, filtra a los destinatarios en la lista de cancelación de suscripción. |
| `filterBlocked` | No | Solo para encolar. El valor predeterminado es `false`; cuando es `true`, filtra a los destinatarios bloqueados. |
`filterUnsubscribed` y `filterBlocked` se aplican solo a
`POST /whatsapp/messages`; no se aplican a `sendDirectly`. Un mensaje en cola
filtrado falla con `RECIPIENT_UNSUBSCRIBED` o
`RECIPIENT_IN_BLOCK_LIST` en su webhook de estado. Para envíos sincrónicos,
aplica verificaciones de consentimiento, cancelación de suscripción y bloqueo en tu aplicación.
Proporciona al menos uno de `to` o `recipient`. Si incluyes ambos, YCloud usa
`to` e ignora `recipient`.
Las plantillas de autenticación con un toque, toque cero y copiar código requieren un número
de teléfono. Usa `to` para estos tipos de plantillas.
### Ejemplos de solicitud
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "template",
"template": {
"name": "sample_whatsapp_template",
"language": {
"code": "en",
"policy": "deterministic"
}
}
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "text",
"text": {
"body": "Hello from YCloud!"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "image",
"image": {
"id": "MEDIA_ID",
"caption": "Product image"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "video",
"video": {
"id": "MEDIA_ID",
"caption": "Product video"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "audio",
"audio": {
"id": "MEDIA_ID"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "document",
"document": {
"id": "MEDIA_ID",
"filename": "invoice.pdf"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "sticker",
"sticker": {
"id": "MEDIA_ID"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "location",
"location": {
"latitude": 37.422,
"longitude": -122.084,
"name": "Googleplex",
"address": "1600 Amphitheatre Pkwy, Mountain View, CA"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "Do you want to continue?"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "yes",
"title": "Yes"
}
}
]
}
}
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "contacts",
"contacts": [
{
"name": {
"formatted_name": "John Smith"
},
"phones": [
{
"phone": "+16315551111",
"type": "CELL"
}
]
}
]
}
```
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"from": "+16315551111",
"to": "+16315551111",
"type": "reaction",
"reaction": {
"message_id": "wamid.BgNODYxN...",
"emoji": "👍"
}
}
```
## Respuesta
Una respuesta exitosa devuelve el objeto de mensaje de YCloud. Un `status: accepted` inicial significa que YCloud aceptó la solicitud de envío. No significa que Meta haya enviado el mensaje ni que se haya entregado al usuario de WhatsApp.
### Ejemplo de respuesta
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "MESSAGE_ID",
"wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"from": "+16315551111",
"to": "+16315552222",
"type": "text",
"status": "accepted",
"externalId": "order-10001",
"createTime": "2026-07-16T12:00:00.000Z"
}
```
### Campos de la respuesta
| Campo | Descripción |
| - | - |
| `id` | ID del mensaje de YCloud. Guárdalo para su recuperación y correlación con Webhook. |
| `wamid` | ID del mensaje original de WhatsApp. Disponible tras el envío a WhatsApp. |
| `wabaId` | ID de la cuenta de WhatsApp Business. |
| `from`, `to` | Números de teléfono del remitente y del destinatario. |
| `type` | Tipo de contenido del mensaje. |
| `status` | Estado actual, como `accepted`, `sent`, `failed`, `delivered` o `read`. |
| `errorCode`, `errorMessage` | Detalles de error de YCloud cuando `status` es `failed`. |
| `whatsappApiError` | Error devuelto por la API de WhatsApp Business cuando esté disponible. |
| `externalId` | La referencia proporcionada en la solicitud. |
| `category` | Categoría de Direct Send, como `utility` para los ejemplos de utilidad anteriores. |
| `ttlSeconds` | Tiempo de vida del mensaje de Direct Send, cuando se define en el mensaje. |
| `totalPrice`, `currency` | Precio estimado o final del mensaje y moneda. |
| `createTime`, `sendTime`, `deliverTime`, `readTime` | Marcas de tiempo del ciclo de vida en formato RFC 3339. |
## Estado de entrega
Suscríbete a Webhooks de `whatsapp.message.updated` para recibir cambios de estado posteriores como `sent`, `failed`, `delivered` o `read`.
Utiliza `GET /whatsapp/messages/{id}` cuando necesites recuperar un mensaje directamente.
Para mensajes multimedia, sube el archivo primero con `POST /whatsapp/media/{phoneNumber}/upload`, luego usa el ID multimedia devuelto en el payload del mensaje.
## Límites y resolución de problemas
* Los envíos habituales de plantillas requieren una plantilla `APPROVED`; las plantillas `ARCHIVED`
no se pueden enviar como mensajes de plantilla ordinarios.
* No reintentes una solicitud aceptada sin una estrategia de idempotencia. Una solicitud
repetida puede enviar un mensaje duplicado.
* Utiliza `id`, `wamid`, `externalId` de YCloud y el estado de Webhook cuando
investigues la entrega.
* Inspecciona `whatsappApiError` cuando una solicitud directa llegue a Meta y Meta la
rechace.
Para conocer los límites de rendimiento, consulta [Límites de velocidad](/es/api-reference/guides/api-fundamentals/rate-limits).
Envía contenido de utilidad, convierte plantillas y supervisa eventos de categoría y restricciones.
Diseña sincronización de estados, reintentos delimitados, comprobaciones de consentimiento, reutilización de archivos multimedia,
y controles de rendimiento para una integración en producción.
Envía mensajes y llamadas por BSUID, solicita números de teléfono, gestiona entradas de la libreta de contactos de Meta
y procesa campos de webhook de BSUID.
## Ejemplos completos de integración
Para ver el flujo de trabajo completo de creación de plantillas y vinculación de variables, consulta
[Ejemplos de creación de plantillas](/es/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples)
y [Ejemplos de mensajería](/es/api-reference/guides/examples/api-examples/whatsapp-messaging-examples).
Utiliza [Gestión de errores de WhatsApp](/es/api-reference/guides/whatsapp-platform/handle-whatsapp-errors)
para distinguir el rechazo de solicitudes de fallos de entrega posteriores, e
[Implementación del receptor de Webhook](/es/api-reference/guides/api-fundamentals/implement-a-webhook-receiver)
para verificar firmas y aceptar actualizaciones de estado de forma duradera.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.