> ## 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.

# Handover do Agent do WhatsApp atualizado

> Observe os callbacks suportados de handover de controle do Agent e entenda seus limites de correlação.

## O que é

Inscreva-se em `whatsapp.meta_business_agent.handover.updated`.

Você recebe este evento quando a YCloud processa um callback suportado de handover/controle para um Agent criado via API. Ele relata a transferência de controle, não o resultado de uma atribuição no Inbox ou uma mensagem personalizada de transição.

Diferente dos dois eventos Echo, este evento mantém intencionalmente o objeto
`whatsappMetaBusinessAgent` porque os metadados do Agent e de controle fazem parte do contrato de handover.

## Antes de começar

1. Faça o onboarding do Agent por meio da [API REST pública](/pt/api-reference/meta-business-agents/onboard).
2. Inscreva um endpoint de webhook ativo na mesma conta em `whatsapp.meta_business_agent.handover.updated`.
3. Verifique `YCloud-Signature` em relação ao corpo bruto da requisição, aceite cada evento de forma durável e processe-o com idempotência.

<Warning>
  Agents criados no Console não emitem este webhook do cliente. A sincronização do Inbox deles é um fluxo separado.
</Warning>

Consulte [Configurar webhooks](/pt/api-reference/guides/api-fundamentals/configure-webhooks#subscribe-to-echo-and-handover-events) para obter informações sobre a configuração do endpoint.

## Como funciona

Todos os exemplos usam identificadores de espaço reservado. Faça o roteamento pelo `type` externo e leia
`whatsappMetaBusinessAgent`, não `whatsappMessage`, `whatsappEchoMessage` ou `data`.

Elimine entregas duplicadas com o `id` externo. O `timestamp` aninhado
é um número inteiro em milissegundos Unix; `createTime` é uma string RFC 3339.

* `controlState` atualmente é `APP_CONTROL_TAKEN` para callbacks suportados de handover de Agent via API.
* `consumerPhoneNumber` vem do `sender.phone_number` do callback de handover e é normalizado para E.164 quando válido. Não é o número comercial nem o `phoneNumberId`.
* O contrato atual de handover não expõe `recipientUserId` ou `parentRecipientUserId`. A identidade ausente do consumidor não é recuperada de um callback de mensagem adjacente.
* Para o exemplo de `control_passed` abaixo, `actor` identifica o app proprietário anterior, não o funcionário receptor.
* `reason` são metadados opcionais do provedor. Trate-os como uma string aberta, não como um enum fixo.
* Esta não é uma notificação para cada requisição de `take`, `release`, Set Live ou Set Draft. Callbacks de controle processados enquanto o Agent estiver em Draft são ignorados.

<Warning>
  O payload não inventa uma identidade de consumidor. `consumerPhoneNumber` é omitido quando o callback não fornece um número de telefone válido, e nenhum BSUID é inferido a partir de mensagens adjacentes. `phoneNumberId` identifica o número comercial, que pode atender a muitos clientes.
</Warning>

Não trate este evento como prova de que um funcionário foi atribuído ou de que uma mensagem personalizada de transição foi enviada ou entregue.

## Requisição

A YCloud envia esses corpos JSON em requisições HTTP `POST` para a URL de webhook configurada por você.

## Resposta

Retorne uma resposta `2xx` após aceitar o evento de forma durável. Processe tarefas demoradas de maneira assíncrona.

## Agent transfere o controle para sua aplicação

### Requisição

APP\_CONTROL\_TAKEN relata a transferência de controle, não a atribuição a um funcionário no Inbox ou a entrega de uma mensagem personalizada de transição. actor é o ID do app proprietário anterior neste exemplo.

```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
  }
}
```

### Resposta

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

### Explicação

Use `consumerPhoneNumber` para correlacionar a transição de controle com o consumidor quando estiver presente. Não infira uma atribuição no Inbox ou entrega de mensagem a partir deste evento.

### Exemplos relacionados

* [Mensagem de eco do WhatsApp criada](/pt/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-created)
* [Mensagem de eco do WhatsApp atualizada](/pt/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-updated)
* [Exemplos de Echo e handover de Agent](/pt/api-reference/guides/examples/webhook-examples/overview#echo-and-agent-handover-events)
* [Catálogo completo de payloads](/pt/api-reference/guides/examples/webhook-examples/webhook-payload-examples)


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