Skip to main content

Qué es

Suscríbete a whatsapp.meta_business_agent.handover.updated. Recibes este evento cuando YCloud procesa una devolución de llamada (callback) de traspaso/control admitida para un Meta Business Agent creado mediante API. Informa de la transferencia de control, no del resultado de una asignación en Inbox ni de un mensaje personalizado de traspaso. A diferencia de los dos eventos Echo, este evento conserva intencionadamente el objeto whatsappMetaBusinessAgent porque los metadatos del agente y del control forman parte del contrato de traspaso.

Antes de comenzar

  1. Incorpora el agente mediante la Public REST API.
  2. Suscribe un endpoint de webhook activo en la misma cuenta a whatsapp.meta_business_agent.handover.updated.
  3. Verifica YCloud-Signature con el cuerpo sin procesar de la solicitud, acepta cada evento de forma duradera y procésalo de manera idempotente.
Los agentes creados desde 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 marcadores de posición. Enruta mediante el type externo y lee whatsappMetaBusinessAgent, no whatsappMessage, whatsappEchoMessage ni data. Desduplica las entregas repetidas con el id externo. El timestamp anidado es un número entero en milisegundos Unix; createTime es una cadena RFC 3339.
  • controlState es actualmente APP_CONTROL_TAKEN para las devoluciones de llamada de traspaso de agentes de API admitidas.
  • consumerPhoneNumber procede del sender.phone_number de la devolución de llamada de traspaso y se normaliza a E.164 cuando es válido. No es el número del negocio ni phoneNumberId.
  • El contrato de traspaso actual no expone recipientUserId ni parentRecipientUserId. La identidad ausente del consumidor no se recupera a partir de una devolución de llamada de mensaje cercana.
  • Para el siguiente ejemplo control_passed, actor identifica la app propietaria anterior, no al empleado receptor.
  • reason son metadatos opcionales del proveedor. Trátalo como una cadena abierta, no como un enum fijo.
  • Esta no es una notificación para cada solicitud de take, release, Set Live o Set Draft. Las devoluciones de llamada de control procesadas mientras el agente está en Draft se ignoran.
La carga útil no inventa una identidad de consumidor. consumerPhoneNumber se omite cuando la devolución de llamada no proporciona un número de teléfono válido y no se infiere ningún BSUID a partir de mensajes adyacentes. phoneNumberId identifica el número de la empresa, que puede atender a muchos clientes.
No consideres este evento como prueba de que se haya asignado un empleado o de que se haya enviado o entregado un mensaje personalizado de traspaso.

Solicitud

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

Respuesta

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

El agente traspasa el control a tu aplicación

Solicitud

APP_CONTROL_TAKEN informa de la transferencia de control, no de la asignación de un empleado de Inbox ni de la entrega de un mensaje de traspaso personalizado. actor es el ID de la app propietaria anterior en este ejemplo.

Respuesta

Explicación

Usa consumerPhoneNumber para correlacionar la transición de control con el consumidor cuando esté presente. No infieras una asignación de Inbox ni la entrega de un mensaje a partir de este evento.

Ejemplos relacionados