Enviar un mensaje de WhatsApp

Qué es

La API de mensajes de WhatsApp envía mensajes de plantilla, texto, imagen, video, audio, documento, sticker, ubicación, interactivos, contactos y reacciones desde un número de teléfono comercial de WhatsApp 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, su BSUID o su BSUID principal.
Usa una plantilla APPROVED para envíos de plantillas habituales.
Sube los archivos multimedia primero cuando el mensaje haga referencia a un ID de contenido multimedia de YCloud.

Cómo funciona

Elige el endpoint en función de cuándo debe 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 asincrónica.	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.	Mensajes 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 whatsapp.message.updated Webhooks.

Envía tu primer mensaje

Elige una plantilla aprobada que pertenezca a tu WABA conectada. Reemplaza el remitente, el destinatario, el nombre de la plantilla y el idioma con tus propios valores, y luego envía:

curl --request POST https://api.ycloud.com/v2/whatsapp/messages \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "template",
    "externalId": "welcome-10001",
    "template": {
      "name": "welcome_message",
      "language": { "code": "en_US" }
    }
  }'

Guarda el id devuelto y sigue sus eventos whatsapp.message.updated. Una respuesta accepted significa que la solicitud entró en procesamiento, no que el cliente la haya recibido. Configura tanto whatsapp.message.updated como whatsapp.inbound_message.received cuando necesites seguimiento de entrega y respuestas.

Elegir un mensaje de plantilla o de sesión

Usa una plantilla aprobada para mensajes habituales iniciados por la empresa fuera de la ventana de servicio al cliente. Dentro de una ventana abierta, usa tipos de mensajes de formato libre admitidos, como texto, contenido multimedia o respuestas interactivas. Consulta las reglas de la ventana de servicio al cliente al momento del envío. Una ventana de precios no reemplaza la idoneidad para enviar mensajes. Consulta los precios de WhatsApp para conocer las tarifas actuales y las condiciones de los puntos de entrada.

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í solo. Sigue las mejores prácticas de Direct Send para requisitos de elegibilidad, solicitudes, conversión de plantillas, límites y eventos de cuenta.

Elegir el mejor momento de envío

Haz coincidir el momento de envío con el propósito del mensaje y la hora local del destinatario.

Envía contraseñas de un solo uso (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 correspondiente, como un pago, un envío o un cambio de cita.
Programa los mensajes de marketing en horarios razonables en la zona horaria del destinatario. Utiliza tus propios datos de entrega, lectura y conversión para probar diferentes intervalos de tiempo para cada audiencia en lugar de asumir una única mejor hora universal.
Inicia una campaña programada con un grupo pequeño de destinatarios. Comprueba 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 los Webhooks de whatsapp.message.updated antes de decidir si reintentar.

Solicitud

Elige cualquiera de los endpoints anteriores y, luego, usa el cuerpo de la solicitud que coincida con el tipo de mensaje. El valor de from es tu número de teléfono comercial de WhatsApp conectado. Dirige el mensaje al destinatario con to en formato E.164 o con recipient configurado como un BSUID o BSUID principal.

Campos habituales de la solicitud

Campo	Obligatorio	Descripción
`from`	Sí	Número de teléfono comercial de WhatsApp conectado en formato E.164.
`to`	Condicional	Número de teléfono del destinatario en formato E.164. Obligatorio si falta `recipient`.
`recipient`	Condicional	BSUID o BSUID principal del destinatario. Obligatorio si falta `to`.
`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 que se utiliza 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 solo se aplican a POST /whatsapp/messages; no se aplican a sendDirectly. Un mensaje encolado que sea filtrado falla con RECIPIENT_UNSUBSCRIBED o RECIPIENT_IN_BLOCK_LIST en su webhook de estado. Para envíos síncronos, aplica las comprobaciones de consentimiento, cancelación de suscripción y bloqueo en tu aplicación.

Proporciona al menos uno entre to o recipient. Si incluyes ambos, YCloud usa to e ignora recipient.

Las plantillas de autenticación con un solo toque (one-tap), sin toques (zero-tap) y de copiar código requieren un número de teléfono. Usa to para estos tipos de plantilla.

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 de 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": "👍"
  }
}

Agregar variables a la plantilla

Haz coincidir el nombre de la plantilla, el idioma y el orden de los parámetros con tu plantilla aprobada. Para un cuerpo con parámetros de nombre del cliente y referencia de pedido, envía:

{
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Alex" },
          { "type": "text", "text": "ORDER-10001" }
        ]
      }
    ]
  }
}

Consulta los ejemplos de mensajes de plantilla para conocer componentes y tipos de mensajes adicionales.

Responder a un mensaje específico

Establece context.message_id con el ID del mensaje original de WhatsApp (wamid) para crear una respuesta citada. Continúa verificando que la ventana de atención al cliente esté abierta.

{
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "text",
  "text": { "body": "Your order is ready for collection." },
  "context": { "message_id": "wamid.EXAMPLE" }
}

Aplicar filtros de cancelación de suscripción y bloqueo

Para POST /whatsapp/messages, establece filterUnsubscribed: true y filterBlocked: true cuando necesites aplicar tus listas de supresión de YCloud. Ambos tienen como valor predeterminado false y no se aplican a sendDirectly. Inspecciona whatsappMessage.errorCode en los webhooks de estado para RECIPIENT_UNSUBSCRIBED o RECIPIENT_IN_BLOCK_LIST. No esperes un estado separado de filtered. Aplica la supresión en tu aplicación antes de usar sendDirectly. Usa externalId para asociar mensajes con un pedido u otro registro interno. Es un campo de correlación, no una clave de idempotencia del lado del servidor.

Respuesta

Una respuesta correcta devuelve el objeto de mensaje de YCloud. Un estado inicial status: accepted significa que YCloud aceptó la solicitud de envío. No significa que el mensaje haya sido enviado por Meta o 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 respuesta

Campo	Descripción
`id`	ID de mensaje de YCloud. Guárdalo para recuperación y correlación con Webhook.
`wamid`	ID original del mensaje de WhatsApp. Disponible tras enviarse 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 WhatsApp Business API cuando esté disponible.
`externalId`	La referencia suministrada 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 esté establecido 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 los Webhooks de whatsapp.message.updated para recibir cambios de estado posteriores como sent, failed, delivered o read. Usa GET /whatsapp/messages/{id} cuando necesites recuperar un mensaje directamente.

Para mensajes multimedia, sube primero el archivo con POST /whatsapp/media/{phoneNumber}/upload y luego usa el ID multimedia devuelto en el payload del mensaje.

Límites y solución de problemas

Los envíos de plantillas ordinarios 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.
Usa el estado de YCloud id, wamid, externalId y del 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 tasa.

Prácticas recomendadas para Direct Send

Envía contenido de utilidad, convierte plantillas y supervisa los eventos de categoría y restricción.

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 mediante 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 consultar 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. Usa Gestión de errores de WhatsApp para distinguir el rechazo de solicitudes de posteriores errores de entrega, e Implementación del receptor de Webhooks 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

Envía tu primer mensaje

Elegir un mensaje de plantilla o de sesión

Direct Send para contenido de utilidad

Elegir el mejor momento de envío

Solicitud

Campos habituales de la solicitud

Ejemplos de solicitud

Agregar variables a la plantilla

Responder a un mensaje específico

Aplicar filtros de cancelación de suscripción y bloqueo

Respuesta

Ejemplo de respuesta

Campos de respuesta

Estado de entrega

Límites y solución de problemas

Prácticas recomendadas para 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

​Envía tu primer mensaje

​Elegir un mensaje de plantilla o de sesión

​Direct Send para contenido de utilidad

​Elegir el mejor momento de envío

​Solicitud

​Campos habituales de la solicitud

​Ejemplos de solicitud

​Agregar variables a la plantilla

​Responder a un mensaje específico

​Aplicar filtros de cancelación de suscripción y bloqueo

​Respuesta

​Ejemplo de respuesta

​Campos de respuesta

​Estado de entrega

​Límites y solución de problemas

Prácticas recomendadas para 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

Envía tu primer mensaje

Elegir un mensaje de plantilla o de sesión

Direct Send para contenido de utilidad

Elegir el mejor momento de envío

Solicitud

Campos habituales de la solicitud

Ejemplos de solicitud

Agregar variables a la plantilla

Responder a un mensaje específico

Aplicar filtros de cancelación de suscripción y bloqueo

Respuesta

Ejemplo de respuesta

Campos de respuesta

Estado de entrega

Límites y solución de problemas

Ejemplos completos de integración