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
APPROVEDpara 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: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 endpointsendDirectly 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/sendDirectlycuando 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
externalIdy procesa los Webhooks dewhatsapp.message.updatedantes de decidir si reintentar.
Solicitud
Para las plantillas de marketing con Max Price, cualquiera de los dos endpoints de envío aceptabidSpec.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
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.
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:
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
Mensaje de plantilla
Mensaje de plantilla
Mensaje de texto
Mensaje de texto
Mensaje de imagen
Mensaje de imagen
Mensaje de video
Mensaje de video
Mensaje de audio
Mensaje de audio
Mensaje de documento
Mensaje de documento
Mensaje de sticker
Mensaje de sticker
Mensaje de ubicación
Mensaje de ubicación
Mensaje interactivo
Mensaje interactivo
Mensaje de contactos
Mensaje de contactos
Mensaje de reacción
Mensaje de reacción
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:Responder a un mensaje específico
Establececontext.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
ParaPOST /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. Unstatus: 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 dewhatsapp.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.
Límites y solución de problemas
- Los envíos de plantillas normales requieren una plantilla
APPROVED; las plantillasARCHIVEDno 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
idde YCloud,wamid,externalIdy el estado de Webhook cuando investigando la entrega. - Inspecciona
whatsappApiErrorcuando una solicitud directa llega a Meta y Meta la rechaza ello.
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.

