Saltar al contenido principal

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 por API. Conserva el contenido del mensaje del evento creado: las actualizaciones de estado omiten el contenido del mensaje y type. Las actualizaciones fallidas incluyen los detalles del error de origen cuando están disponibles. El contrato actual mantiene el nombre del evento sin cambios y expone las modificaciones de estado bajo whatsappMessage, coincidiendo con el objeto utilizado por el evento creado correspondiente.

Antes de comenzar

  1. Incorpora el Agente a través de 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 de forma duradera cada evento y procésalo de manera idempotente.
Los Agentes creados en la consola no emiten este webhook de cliente. La sincronización de su Inbox es un flujo independiente.
Consulta Configurar webhooks para la configuración del endpoint.

Cómo funciona

Todos los ejemplos utilizan identificadores de marcador de posición. Enruta por el type externo y lee whatsappMessage, no whatsappMetaBusinessAgent, whatsappEchoMessage o data. Deduplica entregas repetidas con el id externo. El createTime externo 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.
  • Haz coincidir las actualizaciones con el evento creado por id o wamid, dentro del alcance de tu cuenta y número de empresa.
  • El teléfono del cliente y el BSUID son independientes. Cuando el estado de origen suministra 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 user_id explícitos de ese contacto. Con cero o múltiples contactos, las identidades faltantes permanecen omitidas; nunca se infieren una de la otra.
  • from solo se incluye cuando la devolución de llamada de origen proporciona un número de teléfono visible de empresa 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 idénticos repetidos sin cambios 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 de mensajes ordinarios enviados por API utilizan whatsapp.message.updated, no este evento.

Solicitud

YCloud envía estos cuerpos JSON en solicitudes HTTP POST a la URL de webhook que hayas configurado.

Respuesta

Devuelve una respuesta 2xx tras aceptar cada evento de forma duradera. Procesa el trabajo lento de forma asíncrona.

Mensaje de eco entregado

Solicitud

Correlaciona con el evento creado mediante id o wamid. Los eventos actualizados omiten el contenido y el tipo del mensaje.

Respuesta

Explicación

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

Mensaje de eco leído

Solicitud

Correlaciona con el evento creado mediante id o wamid. Los eventos actualizados omiten el contenido y el tipo del mensaje.

Respuesta

Explicación

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

Estado enviado 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

Conserva 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 los detalles del error de origen cuando están disponibles.

Respuesta

Explicación

Utiliza errorCode y errorMessage para diagnósticos cuando la devolución de llamada de origen los proporcione.

Ejemplos relacionados