Saltar al contenido principal

Qué es

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

Antes de comenzar

  1. Incorpora el Agent a través de la API REST pública.
  2. Suscribe un endpoint de Webhook activo en la misma cuenta a whatsapp.meta_business_agent.handover.updated.
  3. Verifica YCloud-Signature con respecto al cuerpo sin procesar de la solicitud, acepta cada evento de forma duradera y procésalo de manera idempotente.
Los Agents creados mediante la consola no emiten este Webhook para clientes. Su sincronización con 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 mediante el type externo y lee whatsappMetaBusinessAgent, no whatsappMessage, whatsappEchoMessage o data. Desduplica las entregas repetidas utilizando 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 Agent admitidas de la API.
  • consumerPhoneNumber proviene 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 de la empresa ni phoneNumberId.
  • El contrato de traspaso actual no expone recipientUserId ni parentRecipientUserId. La identidad del consumidor ausente no se recupera a partir de una devolución de llamada de mensaje adyacente.
  • Para el siguiente ejemplo de control_passed, actor identifica la aplicación propietaria anterior, no al empleado receptor.
  • reason corresponde a metadatos opcionales del proveedor. Trátalo como una cadena abierta, no como un enum fijo.
  • Esta no es una notificación para cada solicitud take, release, Set Live o Set Draft. Las devoluciones de llamada de control procesadas mientras el Agent está en Draft se ignoran.
La carga útil no inventa la identidad del 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 trates este evento como prueba de que se asignó un empleado o de que se envió o entregó un mensaje de traspaso personalizado.

Solicitud

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

Respuesta

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

El Agent traspasa el control a tu aplicación

Solicitud

APP_CONTROL_TAKEN informa la transferencia de control, no la asignación de un empleado en Inbox ni la entrega de un mensaje de traspaso personalizado. actor es el ID de la aplicación 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 en Inbox ni la entrega de un mensaje a partir de este evento.

Ejemplos relacionados