Saltar al contenido principal

Qué es

La API de mensajes de WhatsApp envía mensajes de plantilla, texto, imagen, video, audio, documento, sticker, ubicación, interactivos, contacto y reacción desde un número de teléfono comercial de WhatsApp conectado.

Antes de comenzar

  • Almacena 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 de mensaje 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 en función de cuándo deba YCloud enviar el mensaje a la API de WhatsApp Business. 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.

Envía tu primer mensaje

Elige una plantilla aprobada perteneciente a tu WABA conectada. Sustituye el remitente, el destinatario, el nombre de la plantilla y el idioma por tus propios valores, y luego envía:
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 atención al cliente. Dentro de una ventana abierta, usa tipos de mensajes libres compatibles, como texto, contenido multimedia o respuestas interactivas. Consulta las reglas de la ventana de atención al cliente al momento del envío. Una ventana de precios no reemplaza la elegibilidad para mensajería. Consulta los precios de WhatsApp para conocer los cargos actuales y las condiciones de los puntos de entrada.

Envío directo para contenido de Utilidad y Autenticación

El envío directo admite mensajes de Utilidad y Autenticación iniciados por la empresa sin crear primero plantillas de mensaje. YCloud también admite la conversión de plantillas de Utilidad existentes. El envío directo funciona con cualquiera de los endpoints de envío. El endpoint sendDirectly controla el envío síncrono; no habilita el envío directo por sí solo. Para Autenticación, el envío directo acepta texto o un botón OTP interactivo explícito. Una plantilla de Autenticación no se puede convertir en un mensaje de envío directo. Sigue las prácticas recomendadas de envío directo para la elegibilidad, las solicitudes, la conversión de plantillas, los límites y los eventos de cuenta.

Elegir 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 mensajes OTP y otros mensajes con urgencia temporal 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 para horarios razonables en 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 hora óptima 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. Almacena externalId y procesa los Webhooks de whatsapp.message.updated antes de decidir si reintentar.

Solicitud

Para las plantillas de marketing con Max Price, cualquiera de los dos endpoints de envío acepta bidSpec.per_message_bid_multiplier. Omite todo el objeto bidSpec para usar un multiplicador de 1. Consulta la guía de integración de Max Price para ver los multiplicadores por país, los límites de puja y los webhooks de cobro final. 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 comercial de WhatsApp conectado. Dirígete al destinatario con to en formato E.164 o con recipient establecido en un BSUID o BSUID principal.

Campos comunes de la solicitud

filterUnsubscribed y filterBlocked se aplican solo a POST /whatsapp/messages; no se aplican a sendDirectly. Un filtrado el mensaje en cola falla con RECIPIENT_UNSUBSCRIBED o RECIPIENT_IN_BLOCK_LIST en su Webhook de estado. Para los envíos síncronos, aplica las comprobaciones 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 de un toque, de cero toques y de copiar código requieren un teléfono número. El envío directo explícito de OTP también requiere un número de teléfono: usa to, no recipient por sí solo.

Envío directo para OTP con autenticación explícita

Meta está desplegando Authentication Direct Send en fase alfa. La WABA del remitente necesita acceso al envío interactivo de OTP mediante Authentication Direct Send. Que una solicitud de Authentication Direct Send de solo texto se procese correctamente no confirma el acceso a los botones de OTP.
Usa el mismo cuerpo de la solicitud con POST /v2/whatsapp/messages/sendDirectly para el envío síncrono o POST /v2/whatsapp/messages para el envío en cola. Establece type en interactive, category en authentication, interactive.type en button, y proporciona exactamente un botón con type: "otp". Establece interactive.action.buttons[0].otp.code en una cadena de 4–10 letras o dígitos ASCII. Incluye el mismo código como valor independiente en interactive.body.text. En iOS 26 y versiones posteriores, los mensajes con opción de copiar el código y los de un solo toque pueden ofrecer sugerencias de teclado para códigos numéricos de 4 a 8 dígitos. Las notificaciones de WhatsApp y el autocompletado de códigos de seguridad deben estar habilitados en el dispositivo del destinatario. Esto no requiere integración adicional en la aplicación de iOS; la función sin toques sigue disponible solo en Android. Consulta las experiencias de OTP de Meta. Copiar código:
Autorrelleno con un toque:
Autorrelleno sin tocar:
Para un toque y cero toques, proporciona de 1 a 5 aplicaciones Android con nombres de paquete únicos y un hash de clave de firma de 11 caracteres para cada aplicación. Reemplaza el nombre de paquete y el hash de ejemplo con los valores de tu aplicación. Los nombres de paquete pueden contener como máximo 224 caracteres y deben tener al menos dos segmentos separados por puntos; cada segmento empieza con una letra y contiene solo letras, dígitos o guiones bajos. Configura el protocolo de enlace OTP de WhatsApp para tu aplicación antes de solicitar un código. Para los requisitos de configuración y de dispositivos, consulta la guía de experiencias OTP de Meta. Establece zero_tap_terms_accepted en true en cada solicitud de zero-tap para confirmar los términos de zero-tap de Meta en nombre de tu empresa. Omite ese campo para one-tap y para copiar código. Para copiar código, omite también supported_apps y autofill_text. Los campos opcionales del botón, text y autofill_text, están limitados a 25 caracteres y no deben estar vacíos ni contener variables, saltos de línea, formato, direcciones URL ni emojis. code_expiration_minutes especifica el tiempo de caducidad del código, de 1 a 90 minutos (Meta usa 10 de forma predeterminada). Tu aplicación debe seguir verificando el código y hacer cumplir su caducidad. El campo independiente ttlSeconds controla la duración de la entrega del mensaje: el envío directo de autenticación acepta de 30 a 900 segundos y su valor predeterminado es 600 segundos. Consulta límites de TTL del envío directo. Comprueba whatsapp.message.updated para consultar el estado de entrega y verifica el autorrelleno en un dispositivo compatible. Que un mensaje se entregue por sí solo no confirma que un handshake de autorrelleno haya tenido éxito.

Ejemplos de solicitud

Agrega variables de plantilla

Comprueba que el nombre de la plantilla, el idioma y el orden de los parámetros coincidan con tu plantilla aprobada. Para un cuerpo con los parámetros nombre del cliente y referencia del pedido, envía:
Consulta ejemplos de plantillas de mensajes para ver componentes y tipos de mensajes adicionales.

Responder a un mensaje específico

Establece context.message_id en el ID del mensaje original de WhatsApp (wamid) para crear una respuesta citada. Sigue comprobando que la ventana de atención al cliente esté abierta.

Aplica los filtros de baja 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 detectar RECIPIENT_UNSUBSCRIBED o RECIPIENT_IN_BLOCK_LIST. No esperes un estado filtered independiente. 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 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.

Respuesta de ejemplo

Campos de la respuesta

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 los mensajes multimedia, sube primero el archivo con POST /whatsapp/media/{phoneNumber}/upload y luego usa el ID de multimedia devuelto en la carga útil del mensaje.

Límites y solución de problemas

  • Los envíos de plantillas normales requieren una plantilla APPROVED; las plantillas ARCHIVED no se pueden enviar como plantillas de mensaje normales.
  • No reintentes una solicitud aceptada sin una estrategia de idempotencia. Una solicitud repetida Una solicitud puede enviar un mensaje duplicado.
  • Usa id de YCloud, wamid, externalId y el estado de Webhook cuando investigando la entrega.
  • Inspecciona whatsappApiError cuando una solicitud directa llega a Meta y Meta la rechaza ello.
Para conocer los límites de rendimiento, consulta Límites de rendimiento.

Prácticas recomendadas para el envío directo

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 la sincronización de estados, los reintentos acotados, las comprobaciones de consentimiento, la reutilización de contenido multimedia, y los controles de rendimiento para una integración de producción.

Usa ID de usuario con ámbito de empresa

Envía mensajes y llamadas mediante BSUID, solicita números de teléfono y gestiona el contacto de Meta entradas de la agenda y procesar los campos del Webhook de BSUID.

Ejemplos completos de integración

Para ver el flujo completo de creación de plantillas y vinculación de variables, consulta Ejemplos de creación de plantillas y Ejemplos de mensajería. Usa Manejo de errores de WhatsApp para distinguir el rechazo de la solicitud de los fallos de entrega posteriores, y Implementación del receptor de Webhook para verificar firmas y aceptar actualizaciones de estado de forma duradera.