Skip to main content

Qué es

Suscríbete a whatsapp.echo_message.updated. Recibes este evento cuando YCloud procesa un estado de eco saliente coincidente para un Meta Business Agent creado mediante la API. Conserva el contenido del mensaje del evento creado: las actualizaciones de estado omiten el contenido del mensaje y type. Las actualizaciones fallidas incluyen detalles del error de origen cuando están disponibles. El contrato actual mantiene el nombre del evento sin cambios y expone los cambios de estado bajo whatsappMessage, coincidiendo con el objeto utilizado por el evento de creación correspondiente.

Antes de empezar

  1. Incorpora el Agent mediante la API REST pública.
  2. Suscribe un endpoint de webhook activo en la misma cuenta a whatsapp.echo_message.updated.
  3. Verifica YCloud-Signature contra el cuerpo sin procesar de la solicitud, acepta cada evento de forma duradera y procésalo de manera idempotente.
Los Agents creados en la consola no emiten este webhook de cliente. Su sincronización con Inbox es un flujo independiente.
Consulta Configurar webhooks para ver la configuración del endpoint.

Cómo funciona

Todos los ejemplos usan identificadores de marcador de posición. Enruta mediante el type exterior y lee whatsappMessage, no whatsappMetaBusinessAgent, whatsappEchoMessage ni data. Deduplica las entregas repetidas con el id exterior. El createTime exterior es la hora del evento del webhook; el updateTime anidado y las horas específicas del estado son horas de origen en formato RFC 3339.
  • Empareja las actualizaciones con el evento de creación mediante id o wamid, delimitado a tu cuenta y número comercial.
  • El teléfono del cliente y el BSUID son independientes. Cuando el estado de origen proporciona tanto recipient_id como recipient_user_id, el evento incluye to junto con recipientUserId o parentRecipientUserId.
  • Si un elemento de estado omite esas identidades y la misma devolución de llamada contiene exactamente un contacto, YCloud puede usar el wa_id y el user_id explícitos de ese contacto. Con cero o múltiples contactos, las identidades que falten permanecen omitidas; nunca se infieren entre sí.
  • from solo se incluye cuando la devolución de llamada de origen proporciona un número de teléfono visible del negocio válido. No se deriva de phoneNumberId.
  • Mantén el historial de eventos separado del estado actual de tu mensaje. Un evento tardío de sent puede llegar después de read; regístralo sin degradar el estado actual.
  • El ejemplo de envío tardío a continuación hace referencia al mensaje del ejemplo de lectura. El ejemplo fallido hace referencia a un mensaje diferente.
  • Los estados sin cambios y del mismo rango repetidos se suprimen durante el procesamiento. Esto no garantiza una entrega HTTP exactamente una vez.
  • Un estado recibido antes de su registro de eco puede reintentarse internamente. No dependas del orden de entrega.
  • Los estados habituales de mensajes enviados por API usan whatsapp.message.updated, no este evento.

Solicitud

YCloud envía estos cuerpos JSON en solicitudes HTTP POST a tu URL de webhook configurada.

Respuesta

Devuelve una respuesta 2xx tras aceptar cada evento de forma duradera. Procesa las tareas lentas de forma asíncrona.

Mensaje de eco entregado

Solicitud

Correlaciona con el evento de creación mediante id o wamid. Los eventos actualizados omiten el contenido del mensaje y el tipo.

Respuesta

Explicación

Registra la transición a entregado y conserva el contenido del mensaje recibido en el evento de creación.

Mensaje de eco leído

Solicitud

Correlaciona con el evento de creación mediante id o wamid. Los eventos actualizados omiten el contenido del mensaje y el tipo.

Respuesta

Explicación

Registra la transición a leído utilizando updateTime y readTime como horas del evento de origen.

Estado de envío tardío tras lectura

Solicitud

Un estado de origen de menor rango puede llegar después de la lectura. Registra el evento sin degradar el estado actual de tu mensaje.

Respuesta

Explicación

Mantén este evento en el historial de entregas, pero no degrades un estado actual posterior como read.

Mensaje de eco fallido

Solicitud

Este es un mensaje fallido independiente, no una transición desde lectura. Las actualizaciones fallidas incluyen detalles del error de origen cuando están disponibles.

Respuesta

Explicación

Usa errorCode e errorMessage para el diagnóstico cuando la devolución de llamada de origen los proporcione.

Ejemplos relacionados