Enviar un mensaje de WhatsApp

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

Mensaje de plantilla

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "template",
  "template": {
    "name": "sample_whatsapp_template",
    "language": {
      "code": "en",
      "policy": "deterministic"
    }
  }
}

Mensaje de texto

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "text",
  "text": {
    "body": "Hello from YCloud!"
  }
}

Mensaje con imagen

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "image",
  "image": {
    "id": "MEDIA_ID",
    "caption": "Product image"
  }
}

Mensaje de video

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "video",
  "video": {
    "id": "MEDIA_ID",
    "caption": "Product video"
  }
}

Mensaje de audio

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "audio",
  "audio": {
    "id": "MEDIA_ID"
  }
}

Mensaje de documento

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "document",
  "document": {
    "id": "MEDIA_ID",
    "filename": "invoice.pdf"
  }
}

Mensaje de sticker

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "sticker",
  "sticker": {
    "id": "MEDIA_ID"
  }
}

Mensaje de ubicación

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "location",
  "location": {
    "latitude": 37.422,
    "longitude": -122.084,
    "name": "Googleplex",
    "address": "1600 Amphitheatre Pkwy, Mountain View, CA"
  }
}

Mensaje interactivo

{
  "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"
          }
        }
      ]
    }
  }
}

Mensaje de contactos

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "John Smith"
      },
      "phones": [
        {
          "phone": "+16315551111",
          "type": "CELL"
        }
      ]
    }
  ]
}

Mensaje de reacción

{
  "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

{
  "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.

Prácticas recomendadas de Direct Send

Envía contenido de utilidad, convierte plantillas y supervisa eventos de categoría y restricciones.

Prácticas recomendadas para producción

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.

Usa ID de usuario con ámbito empresarial

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 y Ejemplos de mensajería. Utiliza Gestión de errores de WhatsApp para distinguir el rechazo de solicitudes de fallos de entrega posteriores, e Implementación del receptor de Webhook para verificar firmas y aceptar actualizaciones de estado de forma duradera.

Primeros pasos

Guías

Endpoints

Webhooks

Enviar un mensaje de WhatsApp

Qué es

Antes de comenzar

Cómo funciona

Direct Send para contenido de utilidad

Elige el mejor momento de envío

Solicitud

Campos de solicitud comunes

Ejemplos de solicitud

Respuesta

Ejemplo de respuesta

Campos de la respuesta

Estado de entrega

Límites y resolución de problemas

Prácticas recomendadas de Direct Send

Prácticas recomendadas para producción

Usa ID de usuario con ámbito empresarial

Ejemplos completos de integración

​Qué es

​Antes de comenzar

​Cómo funciona

​Direct Send para contenido de utilidad

​Elige el mejor momento de envío

​Solicitud

​Campos de solicitud comunes

​Ejemplos de solicitud

​Respuesta

​Ejemplo de respuesta

​Campos de la respuesta

​Estado de entrega

​Límites y resolución de problemas

Prácticas recomendadas de Direct Send

Prácticas recomendadas para producción

Usa ID de usuario con ámbito empresarial

​Ejemplos completos de integración

Qué es

Antes de comenzar

Cómo funciona

Direct Send para contenido de utilidad

Elige el mejor momento de envío

Solicitud

Campos de solicitud comunes

Ejemplos de solicitud

Respuesta

Ejemplo de respuesta

Campos de la respuesta

Estado de entrega

Límites y resolución de problemas

Ejemplos completos de integración