Skip to main content
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 las 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.

Solicitud

Los siguientes escenarios muestran las solicitudes enviadas a tu URL de webhook. Trata el id del evento como el identificador de entrega y usa type para enrutar el payload.

Respuesta

Devuelve un estado 2xx tras aceptar el evento.
Para la configuración del endpoint, la validación de firmas y el comportamiento de reintentos, consulta Configurar webhooks.

Mensaje entrante no admitido

En este caso, tu endpoint de webhook recibió un mensaje entrante no admitido:
  • 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.

Solicitud

Respuesta

Confirma la recepción de la entrega tras aceptar el evento de forma duradera.

Explicación

  • El error 131051 con Message type unknown significa que la API de WhatsApp Cloud 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 del mensaje original.
  • 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 ver el contrato de payload actual.

Mensaje de texto entrante

En este caso, tu endpoint de webhook recibió un mensaje de texto entrante:
  • Contiene el texto sin formato que envió el usuario.
  • Contiene la información del mensaje mencionado en context.

Solicitud

Respuesta

Confirma la recepción de la entrega tras aceptar el evento de forma duradera.

Explicación

  • Los mensajes entrantes son aquellos enviados por clientes a los números de teléfono de tu empresa.
  • El objeto context (opcional) contiene la información del mensaje mencionado, utilizado normalmente para responder a un mensaje anterior enviado por el usuario o por tu empresa.
    • context.from es el WhatsApp ID (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 clic a anuncios de WhatsApp

En este caso, tu endpoint de webhook recibió un mensaje de texto entrante activado por un clic a anuncios de WhatsApp:
  • Contiene texto sin formato.
  • Contiene información sobre el anuncio.

Solicitud

Respuesta

Confirma la recepción de 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.

Solicitud

Respuesta

Confirma la recepción de 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.

Solicitud

Respuesta

Confirma la recepción de 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.

Solicitud

Respuesta

Confirma la recepción de 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.

Solicitud

Respuesta

Confirma la recepción de 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 directamente a sticker.link en pocos minutos para la comodidad del consumidor, pero siempre debes incluir un encabezado X-API-Key para descargar este archivo en un plazo de 30 días.

Mensaje entrante de ubicación

En este caso, tu endpoint de webhook recibió un mensaje entrante de ubicación:
  • 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 entrante de contactos

En este caso, tu endpoint de webhook recibió un mensaje entrante de contactos:
  • Contiene un contacto con direcciones, fecha de cumpleaños, 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 entrante de reacción

En este caso, tu endpoint de webhook recibió un mensaje entrante de reacción:
  • 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

  • emoji está presente cuando el usuario reacciona a un mensaje con un emoji. Si no lo está, 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 usaste 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 la 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 del mensaje interactivo que enviaste previamente.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

  • context contiene información sobre el mensaje interactivo que enviaste previamente.
    • context.from es el ID de WhatsApp (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 empieza por 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 de 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

  • context contiene información sobre el mensaje interactivo que enviaste previamente.
    • context.from es el ID de WhatsApp (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 empieza por wamid..

Mensaje entrante de respuesta a Flow interactivo

Al completarse el flujo, se enviará un mensaje de respuesta al chat de WhatsApp. Lo recibirás de la misma forma en que recibes todos los demás mensajes del usuario: a través del webhook de mensajes. El campo response_json contendrá datos específicos del flujo.

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 flujo. La estructura se define en el JSON del flujo (consulta la acción Complete) o, si el flujo utiliza un endpoint, está controlada por este (consulta Carga útil de respuesta final en Solicitud de intercambio de datos). Analiza la cadena JSON de 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 se origina en 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 no se incluirá dicha clave en el response_json si el usuario no optó por participar.
    • 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 sean independientes de las zonas horarias.
  • Para enviar un mensaje con un Flow, consulta Mensaje de plantilla Flow y Mensaje interactivo de Flow.

Mensaje de sistema entrante

En este caso, tu endpoint de webhook recibió un mensaje de 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. previous_user_id identifica el BSUID anterior cuando Meta lo proporciona.
  • parent_user_id y previous_parent_user_id son BSUID principales opcionales, incluidos solo cuando están habilitados y son proporcionados por Meta. Mantén los nombres de campo originales en snake_case dentro de system.

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 errores a un procesador asíncrono.

Mensaje de cambio de BSUID entrante

También puedes recibir un mensaje de sistema entrante con system.type establecido en user_changed_user_id. El número de teléfono del usuario puede permanecer sin cambios o no estar disponible. Usa system.previous_user_id y system.user_id para asociar los BSUID anterior y nuevo cuando se proporcionen ambos. Los campos de BSUID principal son opcionales.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Este ejemplo omite from y system.wa_id porque el número de teléfono no está disponible. Si se proporciona wa_id, contiene un número de teléfono sin el + inicial; no asumas que difiere del número de teléfono anterior. Conserva tu número de teléfono existente cuando el evento no proporcione un reemplazo.

Mensaje de pedido entrante

En este caso, tu endpoint de webhook recibió un mensaje de pedido entrante cuando un cliente agrega 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 mediante id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Mensaje de consulta de 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 de producto cuando un usuario solicita más información sobre un producto específico. Se pueden recibir en dos situaciones:
    • Cuando un cliente responde a Mensajes de un solo producto o de varios 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 de solicitud de bienvenida entrante

Puedes recibir una notificación por webhook siempre que un usuario de WhatsApp abra un chat contigo por primera vez. Esto puede resultar ú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, por lo general al tocar 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 el número de teléfono de tu empresa. Si no lo hay, el cliente activa un webhook request_welcome. Luego 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 Administrador de WhatsApp > Números de teléfono > Configuración > Automatizaciones.
  • Para probar el mensaje request_welcome, si ya tienes una conversación abierta con el número de teléfono de la empresa, 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 desde 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 después de aceptar el evento de forma duradera.

Explicación

Lee category y value desde whatsappUserPreference; este ejemplo registra una solicitud para detener los mensajes de marketing. Usa los identificadores de la empresa y los identificadores de cliente proporcionados para asociar la preferencia. parentUserId se omite cuando los BSUID principales no están habilitados. Mantén detail como texto explicativo y preserva el timestamp proporcionado. Este es un evento de preferencia dedicado, 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 ordinarios. Verifica el encabezado YCloud-Signature antes de aceptar el evento. Un reintento de entrega conserva Event.id; recrear 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. Preserva el texto exactamente, 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 ordinarios. Las entregas repetidas desde el origen pueden 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 la carga útil.

Solicitud

Respuesta

Explicación

Mantén los mismos id y metaMessageId del mensaje al actualizar tu registro. El nuevo text.body, el editCount acumulativo y editTime describen la edición guardada. Los campos sendTime y createTime del mensaje conservan sus valores originales; el campo createTime del evento corresponde a la hora de edición. Los mensajes sin editar omiten los campos de edición. Solo se actualizan los mensajes entrantes existentes; los originales que falten y las versiones de edición reemplazadas no se reconstruyen. Los reintentos de entrega conservan el ID del evento, pero el reprocesamiento en el origen puede generar un nuevo ID de evento. Usa el ID de mensaje y el recuento de ediciones para gestionar los duplicados y el orden.