Para consultar el catálogo exhaustivo derivado del esquema, consulta todos los ejemplos.
Qué es
Gestiona mensajes entrantes de WhatsApp, Messenger y SMS, además de preferencias de marketing de WhatsApp.Antes de comenzar
- Crea un endpoint HTTPS público en tu aplicación.
- Configura un endpoint de Webhook de YCloud para los tipos de eventos que necesites.
- Guarda el secreto de firma del endpoint de forma segura.
- Haz que el procesamiento de eventos sea idempotente.
Cómo funciona
YCloud envía una solicitud HTTPPOST cuando ocurre el evento. Verifica la firma, registra el evento de forma duradera, devuelve una respuesta 2xx y procesa las tareas lentas de forma asíncrona.
Request
Los escenarios a continuación muestran solicitudes entregadas a tu URL de Webhook. Trata elid del evento como el identificador de entrega y usa type para enrutar el payload.
Response
Devuelve un estado2xx tras aceptar el evento.
Para la configuración de endpoints, validación de firmas y comportamiento de reintentos, consulta Configurar webhooks.
Mensaje entrante no compatible
En este caso, tu endpoint de Webhook recibió un mensaje entrante no compatible:typeestá establecido enunsupported.errorsexplica por qué el mensaje no es compatible o no está disponible.unsupported.typeidentifica la categoría del mensaje, comopoll_creation,poll_update,editopin.
Request
Response
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- El error
131051conMessage type unknownsignifica que la API Cloud de WhatsApp no admite el tipo de mensaje. - El error
131060conThis message is currently unavailable.significa que WhatsApp no pudo proporcionar el contenido del mensaje. unsupported.typeidentifica la categoría general. No contiene el contenido original del mensaje.- Consulta Mensajes no admitidos en Inbox para ver una lista legible de tipos de mensaje. Consulta la referencia de webhook para mensajes no admitidos de Meta para conocer el contrato de payload actual.
Mensaje de texto entrante
En este caso, tu endpoint de Webhook recibió un mensaje de texto entrante:- Contiene texto sin formato que envió el usuario.
- Contiene la información del mensaje mencionado en
context.
Request
Response
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- Los mensajes entrantes son aquellos enviados desde los clientes a los números de teléfono de tu empresa.
- El campo opcional
contextcontiene la información del mensaje mencionado, que normalmente se utiliza para responder a un mensaje anterior enviado por el usuario o por tu empresa.context.fromes el ID de WhatsApp (número de teléfono sin el prefijo «+») del usuario que envió el mensaje mencionado.context.ides el ID original del mensaje mencionado en la plataforma de WhatsApp, que comienza conwamid..
Mensaje de texto entrante activado por un clic en anuncios de WhatsApp
En este caso, tu endpoint de Webhook recibió un mensaje de texto entrante activado por un clic en anuncios de WhatsApp:- Contiene texto sin formato.
- Contiene información sobre el anuncio.
Request
Response
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- El campo
referralcontiene información sobre el anuncio. Consulta también Anuncios con clic a WhatsApp.
Mensaje de imagen entrante
En este caso, tu endpoint de Webhook recibió un mensaje de imagen entrante:- Contiene una URL de imagen.
- Contiene un pie de foto para describir esta imagen.
Request
Response
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- Se puede acceder directamente a la
image.linken unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezadoX-API-Keypara descargar este archivo en un plazo de 30 días.
Mensaje de video entrante
En este caso, tu endpoint de Webhook recibió un mensaje de video entrante:- Contiene una URL de video.
- Contiene un pie de foto para describir este video.
Request
Response
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- Se puede acceder directamente a la
video.linken unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezadoX-API-Keypara descargar este archivo en un plazo de 30 días.
Mensaje de audio entrante
En este caso, tu endpoint de Webhook recibió un mensaje de audio entrante:- Contiene una URL de audio.
Request
Response
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- Se puede acceder directamente a la
audio.linken unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezadoX-API-Keypara descargar este archivo en un plazo de 30 días.
Mensaje de documento entrante
En este caso, tu endpoint de Webhook recibió un mensaje de documento entrante:- Contiene una URL de documento.
- Contiene un pie de foto para describir este documento.
Request
Response
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- Se puede acceder directamente a la
document.linken unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezadoX-API-Keypara descargar este archivo en un plazo de 30 días.
Mensaje de sticker entrante
En este caso, tu endpoint de Webhook recibió un mensaje de sticker entrante:- Contiene una URL de sticker.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- Se puede acceder a
sticker.linkdirectamente durante unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezadoX-API-Keypara descargar este archivo en un plazo de 30 días.
Mensaje de ubicación entrante
En este caso, tu endpoint de webhook recibió un mensaje de ubicación entrante:- Contiene la latitud y la longitud del lugar.
- Contiene el nombre, la dirección y la URL del lugar.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
Enruta el evento mediantetype, deduplícalo mediante id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.
Mensaje de contactos entrante
En este caso, tu endpoint de webhook recibió un mensaje de contactos entrante:- Contiene un contacto con direcciones, fecha de nacimiento, correos electrónicos, nombre, teléfonos y otros campos de contacto.
- Contiene
origin: contact_requestcuando el usuario compartió el contacto en respuesta a un mensaje de solicitud de información de contacto.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
Enruta el evento mediantetype, deduplícalo mediante id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.
Mensaje de reacción entrante
En este caso, tu endpoint de webhook recibió un mensaje de reacción entrante:- Contiene el ID del mensaje al que reacciona el usuario.
- Contiene el emoji.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- El campo
emojiestá presente cuando el usuario reacciona a un mensaje con un emoji. De lo contrario, indica que el usuario eliminó el emoji de un mensaje.
Mensaje entrante de botón de plantilla
En este caso, tu endpoint de webhook recibió un mensaje entrante de botón de plantilla:- Contiene el
textdel botón de la plantilla que utilizaste al enviar un mensaje de plantilla. - Contiene el
payloaddel botón que proporcionaste al enviar un mensaje de plantilla. - Contiene el wamid (
context.wamid) del mensaje de plantilla que enviaste.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
Enruta el evento mediantetype, deduplícalo mediante id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.
Mensaje entrante de respuesta a lista interactiva
En este caso, tu endpoint de webhook recibió un mensaje entrante de respuesta a lista interactiva:- El campo
interactivecontiene la respuesta de lista en la que el usuario hizo clic en un mensaje interactivo que enviaste previamente. - El campo
contextcontiene información sobre el mensaje interactivo que enviaste previamente al usuario.
Haz clic en el botón para seleccionar un elemento.
El destinatario responde a tu mensaje seleccionando uno de los elementos de tu mensaje interactivo enviado previamente.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- El campo
contextcontiene información sobre el mensaje interactivo que enviaste previamente.context.fromes el WhatsApp ID (número de teléfono sin el prefijo ’+’) de quien envió el mensaje interactivo.context.ides el ID del mensaje original en la plataforma de WhatsApp, que comienza conwamid..
Mensaje entrante de respuesta a botón interactivo
En este caso, tu endpoint de webhook recibió un mensaje entrante de respuesta a botón interactivo:- El campo
interactivecontiene la respuesta del botón en la que el usuario hizo clic en un mensaje interactivo que enviaste previamente. - El campo
contextcontiene información sobre el mensaje interactivo que enviaste previamente al usuario.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- El campo
contextcontiene información sobre el mensaje interactivo que enviaste previamente.context.fromes el WhatsApp ID (número de teléfono sin el prefijo ’+’) de quien envió el mensaje interactivo.context.ides el ID del mensaje original en la plataforma de WhatsApp, que comienza conwamid..
Mensaje entrante de respuesta a Flow interactivo
Al completarse el flow, se enviará un mensaje de respuesta al chat de WhatsApp. Lo recibirás de la misma forma que recibes el resto de mensajes del usuario: a través del webhook de mensajes. El camporesponse_json contendrá datos específicos del flow.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
interactive.typesiempre esnfm_reply.interactive.namesiempre esflow.interactive.bodysiempre esSent.interactive.response_jsonson datos específicos del flow. Su estructura se define en el JSON del flow (consulta Complete action) o, si el flow utiliza un endpoint, está controlada por el endpoint (consulta Final Response Payload en Data Exchange Request). Analiza la cadena JSONinteractive.response_jsonpara obtener un objeto JSON, donde el tipo de datos de sus valores puede ser variado. Por lo general, los valores son texto sin formato, excepto:- Cuando proviene de un componente CheckboxGroup, el valor es una lista de cadenas.
- Cuando se origina a partir de un componente OptIn, el valor es un booleano, es decir,
trueofalse. Actualmente, si está presente, el valor debe sertrue, ya que dicha clave no se incluirá en elresponse_jsonsi el usuario no eligió aceptar (opt-in). - Cuando se origina a partir de un componente DatePicker, el valor es una cadena que representa una marca de tiempo Unix en milisegundos, como
"1725936737548"(es decir, 2024-09-10T02:52:17.548Z). A partir de la versión 5.0 de Flow JSON, las fechas se establecerán en formato “yyyy-MM-dd”, lo que hace que los valores no dependan de las zonas horarias.
- Para enviar un mensaje con un Flow, consulta Mensaje con plantilla de Flow y Mensaje interactivo de Flow.
Mensaje del sistema entrante
En este caso, tu endpoint de webhook recibió un mensaje del sistema entrante:typese establece ensystemysystem.typese establece enuser_changed_number.- Un usuario cambia su número de teléfono en WhatsApp, y
wa_ides el nuevo ID de WhatsApp (número de teléfono sin el prefijo+). user_ides el nuevo BSUID.parent_user_idse incluye únicamente cuando los BSUID principales están habilitados.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
Enruta el evento mediantetype, deduplícalo por id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.
Mensaje de pedido entrante
En este caso, tu endpoint de webhook recibió un mensaje de pedido entrante cuando un cliente añade uno o más productos a su carrito y envía un pedido:- Contiene información sobre el producto pedido.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
Enruta el evento mediantetype, deduplícalo por id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.
Mensaje de consulta sobre producto entrante
En este caso, tu endpoint de webhook recibió un mensaje de texto entrante cuando un cliente consulta sobre un producto:- Contiene información sobre el producto.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- Se recibe un mensaje de consulta sobre producto cuando un usuario solicita más información acerca de un producto específico. Se pueden recibir en dos escenarios:
- Cuando un cliente responde a mensajes de un solo producto o de múltiples productos.
- Cuando un cliente accede al catálogo de una empresa mediante otro punto de entrada, navega a una página de detalles del producto y hace clic en Enviar mensaje a la empresa sobre este producto.
Mensaje entrante de solicitud de bienvenida
Puedes recibir notificaciones por webhook cada vez que un usuario de WhatsApp abra un chat contigo por primera vez. Esto puede ser útil si deseas responder a estos usuarios con un mensaje de bienvenida especial con tu propio diseño. Si habilitas esta función y un usuario abre un chat (generalmente cuando pulsa un enlace universal, enlaces wa.me o api.whatsapp.com ), el cliente de WhatsApp comprueba si existe un hilo de mensajes entre el usuario y tu número de teléfono comercial. Si no lo hay, el cliente activa un webhookrequest_welcome. A continuación, puedes responder al usuario con tu propio mensaje de bienvenida.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
- Para habilitar esta función para un número de teléfono, ve a Meta WhatsApp Manager > Phone Numbers > Settings > Automations.
- Para probar el mensaje
request_welcome, si ya tienes una conversación abierta con el número de teléfono comercial, primero debes eliminar el chat. - Esta función solo activa un mensaje
request_welcomeentrante y no responde ningún mensaje de forma automática. Depende de ti si deseas responder con un mensaje de bienvenida.
SMS entrante
Usasms.inbound.received cuando un usuario responda a tu SMS.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
Lee la respuesta desmsInbound.text. from es el número de teléfono del usuario, to es tu Sender ID registrado y sendTime es la hora de envío del mensaje. No analices este evento como whatsappInboundMessage.
Preferencia de marketing de WhatsApp
Usawhatsapp.user.preferences cuando un usuario de WhatsApp detenga o reanude los mensajes de marketing.
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
Leecategory y value desde whatsappUserPreference; este ejemplo registra una solicitud para detener mensajes de marketing. Usa los identificadores de la empresa y los identificadores de cliente proporcionados para hacer coincidir la preferencia. parentUserId se omite cuando los BSUID principales no están habilitados. Mantén detail como texto explicativo y conserva el timestamp suministrado. Este es un evento de preferencia exclusivo, no un mensaje de chat entrante ni una carga útil de contact.unsubscribe.created.
Texto entrante de Messenger
Suscríbete amessenger.inbound_message.received para mensajes de texto individuales normales. Verifica el encabezado YCloud-Signature antes de aceptar el evento. Un reintento de entrega conserva Event.id; volver a crear un evento a partir del mismo hecho de origen puede generar un nuevo Event.id. Correlaciona los mensajes entrantes repetidos mediante messengerInboundMessage.id.
Solicitud
Respuesta
Explicación
El PSID del cliente esfrom y el ID de la página de Facebook es to. Conserva el texto de forma exacta, incluidos los espacios. sendTime es la hora del evento de origen guardada; createTime es la hora de persistencia local. Este evento solo transporta mensajes de texto normales. La entrega repetida desde el origen puede crear otro evento para el mismo ID de mensaje guardado.
Edición de texto entrante de Messenger
Suscríbete amessenger.inbound_message.updated para recibir el texto más reciente de un mensaje entrante existente. Verifica YCloud-Signature antes de procesar el payload.
Solicitud
Respuesta
Explicación
Mantén el mismoid y metaMessageId del mensaje al actualizar tu registro. El nuevo text.body, el editCount acumulado y editTime describen la edición guardada. Los campos sendTime y createTime del mensaje conservan sus valores originales; el campo createTime del evento es la hora de la edición. Los mensajes no editados omiten los campos de edición. Solo se actualizan los mensajes entrantes existentes; los originales faltantes y las versiones de edición reemplazadas no se reconstruyen. Los reintentos de entrega conservan el ID del evento, pero el reprocesamiento desde el origen puede crear un nuevo ID de evento. Usa el ID del mensaje y el recuento de ediciones para gestionar duplicados y el orden.
