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
- Faça o onboarding do Agent por meio da API REST pública.
- Inscreva um endpoint de webhook ativo na mesma conta em
whatsapp.meta_business_agent.handover.updated.
- 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.
Agents criados no Console não emitem este webhook do cliente. A sincronização do Inbox deles é um fluxo separado.
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.
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.
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.
Resposta
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
