Skip to main content
Para consultar el catálogo exhaustivo derivado del esquema, consulta todos los ejemplos.

Qué es

Gestiona actualizaciones de mensajes para WhatsApp, Messenger, Email, SMS y mensajes de Voice.

Antes de empezar

  • 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 de forma segura el secreto de firma del endpoint.
  • 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 escenarios a continuación muestran solicitudes enviadas a tu URL de webhook. Trata el id del evento como el identificador de entrega y utiliza 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.
Para WhatsApp, tras solicitar con éxito a la API el envío de mensajes, estos tienen el estado accepted. Las actualizaciones de estado del mensaje activarán el Webhook whatsapp.message.updated. Por lo general, el estado del mensaje:
  • Cambia a failed si no podemos entregar este mensaje.
  • Cambia a sent si es posible entregar este mensaje, y más adelante puede cambiar a failed, delivered o read.
  • Cambia a delivered o read si este mensaje se entregó en el dispositivo del destinatario.
Sin embargo, la situación real es compleja. En primer lugar, no garantizamos el orden de las notificaciones de webhook, especialmente cuando los eventos ocurren casi de forma simultánea. En segundo lugar, los eventos delivered pueden ocurrir después de failed, y viceversa, especialmente cuando el usuario final utiliza varios dispositivos.

Mensaje entregado con Max Price

Utiliza la actualización del mensaje entregado para conciliar el cobro final de un mensaje de marketing con Max Price.

Solicitud

Respuesta

Devuelve una respuesta 2xx tras aceptar el evento de forma duradera.

Explicación

bidPricingFlag: true y pricingCategory: marketing_lite_bidding identifican la modalidad de puja. En delivered o read, usa totalPrice y currency para el cobro final. El valor configurado en maxBid es un precio máximo; el importe indicado en accepted o sent es una estimación. Consulta la Guía de integración de Max Price para ver la configuración y ejemplos de multiplicadores.

Mensaje enviado

En este caso, tu endpoint de webhook recibió un evento de mensaje sent:
  • El status del mensaje es sent, lo que significa que el mensaje está en tránsito dentro de los sistemas de WhatsApp.
  • Contiene información sobre la conversación, incluida la hora en que caduca y el tipo de origen.
  • Contiene el estimado de pricingCategory y totalPrice que podríamos cobrarte.
  • Contiene wamid, que es el ID del mensaje original en la plataforma de WhatsApp, que empieza por wamid..

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

  • totalPrice solo es un precio estimado antes de que se entregue el primer mensaje, y pasa a ser el precio definitivo cuando status es delivered o read. El saldo retenido por los mensajes enviados pero aún no entregados no estará disponible hasta que los mensajes se descarten (los mensajes enviados que no se entregan en 30 días se descartan).
  • Por lo general, un mensaje sent cambia pronto a delivered o read, excepto si:
    • La cuenta de WhatsApp del destinatario no tiene conexión; tus mensajes de WhatsApp enviados no se entregarán hasta que el destinatario disponga de servicios de internet funcionales o activos.
    • Cualquier mensaje enviado a un contacto que te haya bloqueado siempre mostrará el sent del mensaje y nunca cambiará a delivered.
    • El destinatario ha desactivado las confirmaciones de lectura y no recibirás las confirmaciones de lectura (read) del mensaje.
    • El mensaje cambia más adelante a failed con el código de error 131026, lo que significa “Message Undeliverable.” o “Receiver is incapable of receiving this message”. Lo más probable es que el destinatario no esté registrado o esté utilizando una versión antigua de WhatsApp.
    • El mensaje no se entregó para ofrecer una experiencia de usuario de alta calidad. Consulta Límites de plantillas de mensajes de marketing por usuario.

Mensaje entregado

En este caso, tu endpoint de webhook recibió un evento de mensaje delivered:
  • El status del mensaje es delivered, lo que significa que el mensaje se entregó en el dispositivo del destinatario.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

  • Este evento indica que el mensaje enviado por tu empresa se entregó en el dispositivo del usuario.
  • Para que un estado sea read, debe haber sido delivered. En algunos casos, como cuando un usuario está en la pantalla de chat y llega un mensaje, el mensaje se marca como delivered y read casi simultáneamente. En este u otros escenarios similares, la notificación delivered no se devolverá, ya que se sobreentiende que un mensaje ha sido entregado si ha sido leído. El motivo de este comportamiento es la optimización interna.
  • Es posible que generemos más de 1 evento de webhook delivered para el mismo mensaje, especialmente si el usuario final utiliza varios dispositivos.
  • pricingModel: “PMP”: indica que se aplica el precio por mensaje. Consulta también whatsapp-message-pricing-updates
  • pricingType
    • regular — indica que el mensaje es facturable.
    • free_customer_service — indica que el mensaje es gratuito porque fue un mensaje de plantilla de utilidad o un mensaje sin plantilla enviado dentro de una ventana de servicio al cliente.
    • free_entry_point — indica que el mensaje es gratuito porque forma parte de una conversación de punto de entrada gratuito.

Mensaje leído

En este caso, tu endpoint de webhook recibió un evento de mensaje read:
  • El mensaje status es read, lo que significa que el destinatario leyó el mensaje.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

  • Si el destinatario ha desactivado las confirmaciones de lectura, no recibirás las confirmaciones read del mensaje.

Mensaje fallido

En este caso, tu endpoint de webhook recibió un evento de mensaje failed:
  • El mensaje status es failed.
  • Contiene errroCode, errorMessage y whatsappApiError.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

  • Estos eventos tienen como objetivo notificarte sobre los cambios de estado de los mensajes salientes que enviaste previamente a los clientes.
  • El motivo del fallo en el envío de mensajes suele ser que los parámetros de la solicitud del mensaje no son válidos, que el número de teléfono del cliente no está registrado, etc. Consulta también WhatsApp Errors para la gestión de errores.
  • Se proporciona whatsappApiError si intentamos enviar este mensaje a la plataforma de WhatsApp de Meta para ayudarte a comprender los detalles del error. Consulta también Cloud API Error Codes.
  • No te cobramos por los mensajes fallidos.

Actualización de entrega de correo electrónico

Usa email.delivery.updated cuando el estado de entrega de un correo electrónico cambie a delivered o failed.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Correlaciona la entrega con emailId y recipientAddress: el estado se aplica a este destinatario. Usa externalId cuando se suministre para coincidir con tu propio registro. Inspecciona errorCode y errorMessage en una entrega fallida. La propiedad del payload es emailDelivery, no whatsappMessage.

Actualización de entrega de SMS

Usa sms.message.updated cuando el estado de entrega de un SMS cambie a delivered o undelivered.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Identifica el SMS con sms.id y lee sms.status. Inspecciona errorCode cuando la entrega falle. SMS utiliza undelivered para un recibo de entrega negativo; no apliques el modelo de estado read de WhatsApp a este evento.

Actualización de entrega de voz

Usa voice.message.updated cuando el estado de un mensaje de voz cambie a delivered o undelivered.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Identifica el mensaje de voz con voice.id y lee voice.status. Inspecciona errorCode cuando se proporcione. Este evento de entrega pertenece a la API de mensajería de voz; es independiente de los eventos del ciclo de vida de WhatsApp Calling.

Instantánea de lectura saliente de Messenger

Suscríbete a messenger.message.updated para obtener instantáneas salientes individuales ordinarias guardadas. Un reintento de entrega conserva Event.id; volver a crear un evento a partir del mismo hecho de origen puede producir un nuevo Event.id. Correlaciona las actualizaciones mediante messengerMessage.id.

Estados de envío y recepción

accepted significa que Meta aceptó el envío, no que el mensaje fue sent o delivered. rejected es un rechazo de envío definitivo; unknown es un resultado no confirmado y no debe tratarse como un fallo. No vuelvas a enviar automáticamente un mensaje después de un tiempo de espera agotado o un resultado unknown. Comprueba su estado guardado usando un ID de mensaje devuelto cuando esté disponible, o contacta con soporte. Una instantánea conserva los hechos guardados actuales, teniendo read prioridad sobre delivered, sent y el resultado del envío. Los recibos tardíos no degradan ese estado. Es posible que recibas instantáneas repetidas o que te pierdas estados intermedios. Usa GET /v2/messenger/messages/{id} con from, o recupera mediante el ID de mensaje confirmado de Meta, para conciliar tu estado guardado actual. Las notificaciones de resultados de envío se ofrecen según el principio del mejor esfuerzo. No dependas de recibir un webhook para cada resultado de envío sincrónico. Los identificadores opcionales, errorCode y las horas de recepción se omiten cuando no están disponibles. Es posible que un error de envío almacenado permanezca presente después de que hechos de recepción posteriores establezcan un estado más determinante.

Solicitud

Respuesta

Explicación

El ID de la página de Facebook es from y el PSID del cliente es to. Este ejemplo expone el estado read guardado sin inventar campos sendTime o deliverTime faltantes. id es el ID de mensaje de YCloud, mientras que metaMessageId es la identidad del proveedor.

Reacción a un mensaje de Messenger

Solicitud

Respuesta

Explicación

Usa pageId y psid para identificar la conversación, y metaMessageId para identificar el mensaje de destino. Una reacción es una interacción y no cambia el estado de entrega. Es posible que el mensaje de destino no tenga un registro local en YCloud. Conserva el createTime de origen; pueden producirse entregas repetidas. Verifica YCloud-Signature con el cuerpo sin procesar antes de devolver una respuesta correcta.

Reacción a un mensaje de Messenger eliminada

Solicitud

Respuesta

Explicación

Elimina la reacción asociada con esta página, el PSID del cliente y el mensaje de destino de Meta. unreact puede omitir reaction y emoji. No exijas un ID de mensaje local ni deduzcas un cambio en el estado del mensaje. Los reintentos de entrega HTTP conservan el mismo ID de evento y cuerpo; las devoluciones de llamada de origen repetidas pueden crear un nuevo ID de evento. Verifica YCloud-Signature con el cuerpo sin procesar antes de devolver una respuesta correcta.