> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Traspaso de control del agente de WhatsApp actualizado

> Observa las devoluciones de llamada de traspaso de control de agentes admitidas y comprende sus límites de correlación.

## Qué es

Suscríbete a `whatsapp.meta_business_agent.handover.updated`.

Recibes este evento cuando YCloud procesa una devolución de llamada de traspaso/control admitida para un agente creado mediante API. Informa la transferencia de control, no el resultado de una asignación en Inbox ni un mensaje de traspaso personalizado.

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 [API REST pública](/es/api-reference/meta-business-agents/onboard).
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 de forma duradera cada evento y procésalo de manera idempotente.

<Warning>
  Los agentes creados desde la consola no emiten este Webhook de cliente. Su sincronización con Inbox es un flujo independiente.
</Warning>

Consulta [Configurar webhooks](/es/api-reference/guides/api-fundamentals/configure-webhooks#subscribe-to-echo-and-handover-events) 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
`whatsappMetaBusinessAgent`, no `whatsappMessage`, `whatsappEchoMessage` o `data`.

Deduplica las entregas repetidas con el `id` externo. El `timestamp` anidado
es un 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 creados por API admitidas.
* `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 del negocio ni `phoneNumberId`.
* El contrato de traspaso actual no expone `recipientUserId` ni `parentRecipientUserId`. La identidad faltante del consumidor no se recupera a partir de una devolución de llamada de mensaje contigua.
* Para el ejemplo de `control_passed` a continuación, `actor` identifica la aplicación propietaria anterior, no al empleado receptor.
* `reason` son metadatos opcionales del proveedor. Trátalo como una cadena abierta, no como una enumeración fija.
* 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 borrador (Draft) se ignoran.

<Warning>
  La carga útil no inventa una identidad de consumidor. Se omite `consumerPhoneNumber` cuando la devolución de llamada no proporciona un número de teléfono válido, y no se deduce ningún BSUID a partir de mensajes adyacentes. `phoneNumberId` identifica el número del negocio, que puede atender a muchos clientes.
</Warning>

No trates este evento como prueba de que se asignó a 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 configurado.

## Respuesta

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

## El agente transfiere el control a tu aplicación

### Solicitud

APP\_CONTROL\_TAKEN informa la transferencia de control, no una asignación de 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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_agent_handover",
  "type": "whatsapp.meta_business_agent.handover.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:04.000Z",
  "whatsappMetaBusinessAgent": {
    "agentId": "00000000-0000-4000-8000-000000000001",
    "metaAgentId": "META_AGENT_ID",
    "phoneNumberId": "PHONE_NUMBER_ID",
    "wabaId": "WABA_ID",
    "consumerPhoneNumber": "+12025550124",
    "controlState": "APP_CONTROL_TAKEN",
    "actor": "PREVIOUS_OWNER_APP_ID",
    "reason": "customer_request",
    "timestamp": 1788919204000
  }
}
```

### Respuesta

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explicación

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

### Ejemplos relacionados

* [Mensaje de eco de WhatsApp creado](/es/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-created)
* [Mensaje de eco de WhatsApp actualizado](/es/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-updated)
* [Ejemplos de eco y traspaso de agentes](/es/api-reference/guides/examples/webhook-examples/overview#echo-and-agent-handover-events)
* [Catálogo completo de payloads](/es/api-reference/guides/examples/webhook-examples/webhook-payload-examples)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.