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 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.
Solicitud
Los escenarios a continuación muestran solicitudes enviadas a tu URL de webhook. Trata elid del evento como el identificador de entrega y utiliza type para enrutar el payload.
Respuesta
Devuelve un estado2xx tras aceptar el evento.
Para la configuración del endpoint, la validación de firmas y el comportamiento de reintentos, consulta Configurar webhooks.
accepted. Las actualizaciones de estado del mensaje activarán el Webhook whatsapp.message.updated.
Por lo general, el estado del mensaje:
- Cambia a
failedsi no podemos entregar este mensaje. - Cambia a
sentsi es posible entregar este mensaje, y más adelante puede cambiar afailed,deliveredoread. - Cambia a
deliveredoreadsi este mensaje se entregó en el dispositivo del destinatario.
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 respuesta2xx 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 mensajesent:
- El
statusdel mensaje essent, 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
pricingCategoryytotalPriceque podríamos cobrarte. - Contiene
wamid, que es el ID del mensaje original en la plataforma de WhatsApp, que empieza porwamid..
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
-
totalPricesolo es un precio estimado antes de que se entregue el primer mensaje, y pasa a ser el precio definitivo cuandostatusesdeliveredoread. 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
sentcambia pronto adeliveredoread, 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
sentdel mensaje y nunca cambiará adelivered. - 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
failedcon el código de error131026, 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 mensajedelivered:
- El
statusdel mensaje esdelivered, 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 sidodelivered. En algunos casos, como cuando un usuario está en la pantalla de chat y llega un mensaje, el mensaje se marca comodeliveredyreadcasi simultáneamente. En este u otros escenarios similares, la notificacióndeliveredno 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
deliveredpara 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 mensajeread:
- El mensaje
statusesread, 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
readdel mensaje.
Mensaje fallido
En este caso, tu endpoint de webhook recibió un evento de mensajefailed:
- El mensaje
statusesfailed. - Contiene
errroCode,errorMessageywhatsappApiError.
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
whatsappApiErrorsi 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
Usaemail.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 conemailId 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
Usasms.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 consms.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
Usavoice.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 convoice.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 amessenger.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 esfrom 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
UsapageId 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.
