Saltar al contenido principal
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 HTTP POST 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 el id del evento como el identificador de entrega y usa type para enrutar el payload.

Response

Devuelve un estado 2xx 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:
  • type está establecido en unsupported.
  • errors explica por qué el mensaje no es compatible o no está disponible.
  • unsupported.type identifica la categoría del mensaje, como poll_creation, poll_update, edit o pin.

Request

Response

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

  • El error 131051 con Message type unknown significa que la API Cloud de WhatsApp no admite el tipo de mensaje.
  • El error 131060 con This message is currently unavailable. significa que WhatsApp no pudo proporcionar el contenido del mensaje.
  • unsupported.type identifica 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 context contiene 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.from es el ID de WhatsApp (número de teléfono sin el prefijo «+») del usuario que envió el mensaje mencionado.
    • context.id es el ID original del mensaje mencionado en la plataforma de WhatsApp, que comienza con wamid..

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

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.link en unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para 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.link en unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para 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.link en unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para 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.link en unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para 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.link directamente durante unos minutos para comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para 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 mediante type, 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_request cuando 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 mediante type, 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 emoji está 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 text del botón de la plantilla que utilizaste al enviar un mensaje de plantilla.
  • Contiene el payload del 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 mediante type, 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 interactive contiene la respuesta de lista en la que el usuario hizo clic en un mensaje interactivo que enviaste previamente.
  • El campo context contiene 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 context contiene información sobre el mensaje interactivo que enviaste previamente.
    • context.from es el WhatsApp ID (número de teléfono sin el prefijo ’+’) de quien envió el mensaje interactivo.
    • context.id es el ID del mensaje original en la plataforma de WhatsApp, que comienza con wamid..

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 interactive contiene la respuesta del botón en la que el usuario hizo clic en un mensaje interactivo que enviaste previamente.
  • El campo context contiene información sobre el mensaje interactivo que enviaste previamente al usuario.
example-inboundmessage-buttonreply.png

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

  • El campo context contiene información sobre el mensaje interactivo que enviaste previamente.
    • context.from es el WhatsApp ID (número de teléfono sin el prefijo ’+’) de quien envió el mensaje interactivo.
    • context.id es el ID del mensaje original en la plataforma de WhatsApp, que comienza con wamid..

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 campo response_json contendrá datos específicos del flow.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

  • interactive.type siempre es nfm_reply. interactive.name siempre es flow. interactive.body siempre es Sent.
  • interactive.response_json son 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 JSON interactive.response_json para 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, true o false. Actualmente, si está presente, el valor debe ser true, ya que dicha clave no se incluirá en el response_json si 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:
  • type se establece en system y system.type se establece en user_changed_number.
  • Un usuario cambia su número de teléfono en WhatsApp, y wa_id es el nuevo ID de WhatsApp (número de teléfono sin el prefijo +).
  • user_id es el nuevo BSUID. parent_user_id se 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 mediante type, 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 mediante type, 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 webhook request_welcome. A continuación, puedes responder al usuario con tu propio mensaje de bienvenida. example-inboundmessage-welcomemessage

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_welcome entrante y no responde ningún mensaje de forma automática. Depende de ti si deseas responder con un mensaje de bienvenida.

SMS entrante

Usa sms.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 de smsInbound.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

Usa whatsapp.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

Lee category 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 a messenger.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 es from 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 a messenger.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 mismo id 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.