Quando o Meta Business Agent é ativado em um número do WhatsApp gerenciado por um Business Solution Provider (BSP), o app do parceiro deixa de ser o respondente principal: as mensagens do consumidor chegam pelo campo de webhook standby enquanto o agente mantém o controle, e o app recupera o controle enviando uma mensagem ou, como parceiro de escalonamento configurado, chamando o Thread Control com a ação take.[1] Três campos de webhook carregam o tráfego, dois Termos de Serviço controlam cada chamada de API, e a Meta cobra a empresa diretamente a US$ 2,00 por 1 milhão de tokens. O mecanismo está documentado nas páginas de desenvolvedores da Meta e pode ser testado em números na allowlist antes que um consumidor real chegue ao agente.
Principais conclusões
- O Meta Business Agent exige três assinaturas de campos de webhook (messages, standby e messaging_handovers), e as mensagens do consumidor migram para standby enquanto o agente mantém o controle.
- Seu app assume o controle ao enviar qualquer mensagem e o mantém até chamar o Thread Control com a ação release; nas palavras da Meta, “Stopping message sends does not release control” (parar de enviar mensagens não libera o controle).
- Dois Termos de Serviço controlam cada chamada de API: o do cliente no WhatsApp Manager e o do BSP no Facebook Developer Portal.
- Solution Partners e Tech Providers se autenticam com um token de Business Integration System User (BISU) que possui as duas permissões exigidas, além do header X-API-Version: 2.0.0.
- Um agente configurado com ai_audience ALLOWLISTED_ONLY pode ser ativado sem um método de pagamento, então testar com consumidores na allowlist vem antes da cobrança.
O que muda na configuração do seu webhook quando o Meta Business Agent está ativo?
O Meta Business Agent exige três assinaturas de campos de webhook: messages, standby e messaging_handovers, todas configuradas no Developer Portal. O campo que carrega a mensagem do consumidor depende de quem detém o controle: standby enquanto o agente o detém, messages enquanto seu app o detém. Um evento messaging_handovers dispara sempre que o controle muda de mãos, e standby é o padrão para novas conversas assim que o agente é ativado.[4]
O payload de standby contém um dos três objetos: standby.messages para a mensagem recebida do consumidor, standby.message_echoes para cada mensagem enviada pelo agente, e standby.statuses para as confirmações de envio, entrega e leitura dessas mensagens.[3] O conteúdo recebido usa a mesma estrutura de payload de um webhook de mensagem recebida padrão, e suas próprias mensagens enviadas nunca são ecoadas de volta para você.
O guia completo do Meta Business Agent resume esse modelo de roteamento. Para uma integração construída por um BSP, a mudança de código é ramificar o handler pelo nome do campo, armazenar o contexto de standby para dar continuidade quando seu app se tornar o handler ativo, e deduplicar pelo id da mensagem.
Como funciona o Thread Control entre o Meta Business Agent e seu app?
Thread Control é o endpoint da Cloud API que transfere o controle de uma conversa entre o Meta Business Agent e um app. Release devolve a conversa ao Meta Business Agent como respondente automático. Pass transfere o controle para o parceiro de escalonamento configurado para o número de telefone, ou para o agente quando control_pass.target_role é “ai_agent”. Ambos exigem que quem chama já detenha o controle. Take adquire o controle do detentor atual e é restrito ao parceiro de escalonamento configurado; outros apps recebem um erro e assumem o controle enviando uma mensagem.
A página Get Started da Meta (atualizada em 25 de agosto de 2026) documenta POST https://graph.facebook.com/v21.0//thread_control com X-API-Version: 2.0.0 e um corpo com messaging_product “whatsapp”, a action, e o consumidor no campo to. A referência do Thread Control (Cloud API) (atualizada em 4 de setembro de 2026) documenta as mesmas três ações em https://api.facebook.com/business/whatsapp/phone_numbers/{phone_number_id}/thread_control com X-API-Version 1.0.0, então teste release primeiro no seu próprio ambiente.[2]
Ativar o Meta Business Agent não pausa nada do seu lado: seu app passa para o papel de standby, e enviar qualquer mensagem a partir dele transfere imediatamente o controle principal de volta para seu app, o que a Meta aponta como a causa mais comum de agentes que ficam silenciosos em produção. Nas palavras da Meta, “Your app retains control until you explicitly release it. Stopping message sends does not release control” (seu app mantém o controle até que você o libere explicitamente; parar de enviar mensagens não libera o controle). Uma resposta automática que dispara em uma mensagem de standby, portanto, silencia o agente até que seu app chame release.
Quando o controle é transferido, o app que o perdeu recebe um webhook control_taken em messaging_handovers com previous_owner_app_id, new_owner_app_id, new_owner_business_id, e a string metadata da chamada; é o único payload de messaging_handovers documentado nas páginas de desenvolvedores do Meta Business Agent. As páginas da Meta ainda não descrevem como o parceiro de escalonamento é configurado nem se um app de BSP pode assumir esse papel.
Quais Termos de Serviço precisam ser aceitos para as chamadas de API funcionarem?
Dois Termos de Serviço controlam cada chamada de API do Meta Business Agent em um número gerenciado por BSP: o cliente aceita os Termos de Serviço do Meta Business Agent no WhatsApp Manager, e o Solution Partner ou Tech Provider aceita os Termos de Serviço de Tech Provider no Facebook Developer Portal. Até que ambos estejam em vigor, a Meta rejeita as chamadas com 403 Forbidden e um erro de Termos de Serviço.
A aba do lado do cliente aparece no WhatsApp Manager somente quando pelo menos um número de telefone na WhatsApp Account (anteriormente WhatsApp Business Account, ou WABA) é elegível; o checklist de elegibilidade cobre essas condições, que incluem números da Cloud API gerenciados por um Solution Partner ou via Embedded Signup.[12]
O lado do parceiro exige o status de Tech Provider: um app da Meta com o caso de uso WhatsApp, verificação de empresa, App Review com dois vídeos de demonstração, e acesso avançado às permissões whatsapp_business_messaging e whatsapp_business_management.[5] A 360Dialog, um Official Meta Solution Partner, opera a infraestrutura de WhatsApp Business API e a Partner Platform que ISVs e revendedores integram; em um número que ela gerencia, a aceitação de Tech Provider é a etapa do lado do parceiro, e a aceitação no WhatsApp Manager é a etapa da própria empresa.
O que acontece com os tokens BISU e as permissões de system user?
Solution Partners e Tech Providers autenticam chamadas da API da Plataforma do Meta Business Agent em nome de WABAs de clientes com um token de Business Integration System User (BISU), enquanto integradores diretos usam um token de system user para sua própria WABA. Ambos os tipos de token exigem whatsapp_business_messaging e whatsapp_business_management. Um token BISU permite que uma única plataforma atue em nome de várias WABAs de clientes sob uma única credencial e é gerado via Embedded Signup com Facebook Login for Businesses.[6] Um token sem uma das permissões retorna 401, segundo o Quickstart da Meta.[11]
Toda requisição da API da Plataforma também precisa do header X-API-Version: 2.0.0; sem ele, as requisições assumem o padrão 1.0.0, no qual o endpoint Skills não está disponível. O system user de uma integração direta precisa ter o papel de Admin e ter a WABA atribuída com “View and manage phone numbers” habilitado.
Pronto para rodar o Meta Business Agent no seu próprio número de WhatsApp Business API? Começar a usar a API.
As respostas do agente aparecem no seu dashboard ou inbox do BSP?
Se as respostas do agente aparecem no seu dashboard ou inbox do BSP depende de o BSP ter integrado o campo de webhook standby a esse produto. A Meta entrega cada resposta do agente ao seu app como um eco em standby.message_echoes, contendo o corpo exato da requisição enviada para POST /{phone-number-id}/messages, com confirmações de entrega e leitura em standby.statuses. A Meta não documenta o comportamento do inbox de nenhum BSP, então pergunte ao seu provedor e teste em um número na allowlist.
O handoff humano do lado do agente é regido por dois campos de Agent Settings: handoff.enabled controla se o agente libera o controle da thread após enviar uma mensagem de handoff, e handoff.message_selection escolhe DEFAULT, AGENT ou CUSTOM como origem dessa mensagem.[8] A documentação da Meta não especifica o que dispara um handoff; a resposta do endpoint Agent Test traz um campo handoff_reason para observá-lo.
Quais mensagens são cobradas pela Meta e quais pelo seu BSP?
A Meta cobra a empresa diretamente por cada mensagem do Meta Business Agent, incluindo empresas que acessam a WhatsApp Business Platform por meio de um Solution Provider, a uma taxa global única de US$ 2,00 por 1 milhão de tokens; uma mensagem típica consome de 20.000 a 25.000 tokens, aproximadamente 4 a 5 centavos de dólar, já que é uma única cobrança por token que cobre o processamento e a entrega pelo agente.[7] A janela gratuita de 72 horas do ponto de entrada e a janela de atendimento ao cliente de 24 horas não isentam as mensagens do agente. Uma mensagem que não é template é cobrada como mensagem de agente ou como mensagem de serviço, nunca como as duas, então uma resposta humana após um handoff é uma mensagem de serviço: gratuita até 1º de outubro de 2026, depois cobrada por mensagem.
A Meta não entrega mensagens do agente para uma empresa sem um método de pagamento em sua conta de Business Agent: uma linha de crédito da Meta faturada mensalmente ou, a partir de 8 de setembro de 2026, um cartão de crédito ou débito Visa ou Mastercard. Linhas de crédito, cartões, moedas e faturas são abordados em quem cobra pelas mensagens do Meta Business Agent.
O que você deve testar antes de ativar o Meta Business Agent?
Teste em um número ativo com o agente restrito a consumidores na allowlist; sob o ai_audience padrão de EVERYONE, o agente responde a todos os consumidores. A ordem documentada pela Meta é adicionar cada consumidor de teste com POST /{entity_id}/agent_config/allowlist (um consumer_phone_number por chamada, em formato E.164), definir ai_audience como ALLOWLISTED_ONLY com PUT /{entity_id}/agent_config/settings, conferir com GET, e só então definir rollout.enabled como true.[9] Um agente ativado com ai_audience definido como ALLOWLISTED_ONLY não exige um método de pagamento, então um cliente de BSP pode testar de ponta a ponta antes de configurar a cobrança; ativá-lo para EVERYONE, ou expandir para EVERYONE depois, exige um método de pagamento e retorna 400 até que ele seja associado.[10]
Antes de fazer a mudança, execute estas verificações:
- Ambos os Termos de Serviço estão aceitos, e uma chamada de teste não retorna mais 403.
- O app está inscrito nos três campos de webhook, e uma mensagem de um consumidor na allowlist chega em standby.
- Toda automação capaz de enviar mensagens nesse número está inventariada; cada uma que dispara tira o controle do agente.
- Uma chamada release funciona, e a próxima mensagem do consumidor chega novamente em standby.
- O Onboarding foi chamado para o número; caso contrário, as chamadas de configuração retornam 500 com “no workspace found”.
O Meta Business Agent adiciona um segundo respondente a um número, e a falha documentada mais comum, um agente silencioso em produção, se resume a qual dos dois detém o controle. Uma integração que sabe qual campo está lendo, libera o que assume, e comprova a sequência primeiro em uma allowlist está pronta para a mudança descrita na cobertura inicial do lançamento da 360Dialog.
Para entender o que ativar o Meta Business Agent significa para um número gerenciado pela 360Dialog, fale conosco.
Perguntas frequentes
Qual é a diferença entre release e pass no Thread Control?
Release devolve uma conversa ao Meta Business Agent como respondente automático, enquanto pass transfere o controle para o parceiro de escalonamento configurado para o número de telefone, ou para o agente quando control_pass.target_role é “ai_agent”. Ambos exigem que quem chama já detenha o controle, e após o release as mensagens do consumidor voltam para seu campo standby.
O que é um parceiro de escalonamento no Meta Business Agent?
Um parceiro de escalonamento é a empresa configurada para um número de telefone que pode chamar o Thread Control com a ação take, adquirindo o controle do Meta Business Agent, de outro app, ou de uma conversa inativa. Outros apps recebem um erro ao tentar take, e a Meta ainda não documenta como o parceiro de escalonamento é configurado.
Preciso de um token BISU se eu integrar diretamente com a Cloud API?
Um integrador direto se autentica com um token de system user para sua própria WhatsApp Account. Um token de Business Integration System User (BISU) é para Solution Partners e Tech Providers que chamam as APIs da Plataforma do Meta Business Agent em nome de WhatsApp Accounts de clientes. Ambos os tipos de token exigem as permissões whatsapp_business_messaging e whatsapp_business_management.
O que acontece se meu app nunca chamar a ação release do Thread Control?
Seu app mantém o controle de toda conversa em que enviou uma mensagem, e o Meta Business Agent não responde ali até que o controle seja liberado. A Meta afirma que parar de enviar mensagens não libera o controle, então as mensagens do consumidor continuam chegando no seu campo messages enquanto o agente permanece em silêncio.
Posso limitar o Meta Business Agent a números de teste antes de colocá-lo em produção?
O Meta Business Agent pode ser limitado a números de teste adicionando cada consumidor à allowlist e definindo ai_audience como ALLOWLISTED_ONLY antes de definir rollout.enabled como true. Sob a configuração padrão EVERYONE, a allowlist é ignorada. Um agente restrito à allowlist pode ser ativado sem um método de pagamento; expandir para EVERYONE exige um.
Fontes
[1] “Get started with Meta Business Agent Platform APIs.” Updated August 25, 2026. https://developers.facebook.com/documentation/meta-business-agent/get-started. Accessed September 7, 2026.
[2] “Thread Control (Cloud API).” Updated September 4, 2026. https://developers.facebook.com/documentation/meta-business-agent/reference/operate/thread-control-cloud-api. Accessed September 7, 2026.
[3] “Standby webhooks.” Updated August 4, 2026. https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/standby. Accessed September 7, 2026.
[4] “Meta Business Agent Troubleshooting.” Updated August 27, 2026. https://developers.facebook.com/documentation/meta-business-agent/troubleshooting. Accessed September 7, 2026.
[5] “Become a Tech Provider.” Updated August 20, 2026. https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/get-started-for-tech-providers. Accessed September 7, 2026.
[6] “Access Tokens.” Updated June 30, 2026. https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens/. Accessed September 7, 2026.
[7] “Upcoming pricing updates for Meta Business Agent, service and utility messages.” Updated August 25, 2026. https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/non-template-messages. Accessed September 7, 2026.
[8] “Agent Settings.” Updated September 4, 2026. https://developers.facebook.com/documentation/meta-business-agent/reference/onboard/agent-settings. Accessed September 7, 2026.
[9] “Agent Allowlist.” Updated September 4, 2026. https://developers.facebook.com/documentation/meta-business-agent/reference/onboard/agent-allowlist. Accessed September 7, 2026.
[10] “Meta Business Agent Changelog.” Updated September 3, 2026. https://developers.facebook.com/documentation/meta-business-agent/changelog/. Accessed September 7, 2026.
[11] “Meta Business Agent Quickstart.” Updated August 27, 2026. https://developers.facebook.com/documentation/meta-business-agent/quickstart. Accessed September 7, 2026.
[12] “Meta Business Agent Platform overview.” Updated August 28, 2026. https://developers.facebook.com/documentation/meta-business-agent/overview. Accessed September 7, 2026.
