Ative o Meta Business Agent em um número WhatsApp gerenciado por BSP completando sete etapas nas ferramentas de desenvolvedor da Meta: aceitar os Termos de Serviço do MBA no WhatsApp Manager, configurar o faturamento, criar um system user com a função Admin, atribuir o app e a WABA a esse usuário, gerar um token BISU com as permissões necessárias, inscrever o app na WABA e inscrever nos campos de Webhook que direcionam as conversas entre o agente e a sua aplicação. Para uma visão mais ampla do produto, veja o guia completo sobre o Meta Business Agent.
Pontos-chave
- A configuração do Meta Business Agent em um número gerenciado por BSP requer sete etapas distintas, cada uma dependente da conclusão bem-sucedida da anterior.
- O BSP ou Tech Provider deve aceitar os Termos de Serviço do Tech Provider no Facebook Developer Portal antes que as chamadas de API do MBA funcionem.
- O MBA requer um token BISU com escopo para as permissões
whatsapp_business_messagingewhatsapp_business_management; um token sem qualquer uma dessas permissões retorna um erro 401 Unauthorized.[1] - A chamada da API de Onboarding (
POST /{entity_id}/agent_onboarding) é uma etapa obrigatória antes de configurar o agente pelo Endpoint de configurações.[2] - Teste com
ai_audiencedefinido comoALLOWLISTED_ONLYantes de ir para produção. Nenhum método de pagamento é necessário durante os testes.[3]
Quais são os pré-requisitos para ativar o Meta Business Agent em um número gerenciado por BSP?
Antes de iniciar a configuração, reúna três IDs e confirme que seu número de telefone é elegível. Você precisa de um WhatsApp Business Account (WABA) ID do WhatsApp Manager, um Business Portfolio ID do Meta Business Suite e um App ID do Facebook Developer Portal.[1] O app deve ter a permissão whatsapp_business_messaging concedida.
O número de telefone deve atender a todas as seis condições de elegibilidade.[4] Ele deve estar em um segmento suportado com uma categoria de negócio válida. Todos os segmentos são suportados, exceto Finanças, Governo, Saúde, Álcool, Jogos de Azar, medicamentos de venda livre e serviços matrimoniais. O número deve ser gerenciado pela Cloud API, inclusive por meio de um Solution Partner ou Embedded Signup. Nem a WABA nem o negócio proprietário podem estar restritos ou banidos. O negócio deve estar em um país autorizado para MBA e deve cumprir os requisitos de confiança e verificação.
Confirme a elegibilidade programaticamente com GET /{phone_number_id}/agent_eligibility usando o header X-API-Version: 2.0.0.[4] Para a lista completa de condições, veja o checklist de elegibilidade.
Aceitar os Termos de Serviço do MBA
Aceite os Termos de Serviço do MBA no WhatsApp Manager navegando até a WABA correta e abrindo a aba Meta Business Agent. Essa aba aparece somente se pelo menos um número de telefone na WABA for elegível.[1] Selecione os números elegíveis e conclua a aceitação. O agente não é ativado após essa etapa.
Para números gerenciados por BSP, duas aceitações são necessárias. O cliente aceita os Termos de Serviço do MBA no WhatsApp Manager. O BSP ou Tech Provider deve aceitar separadamente os Termos de Serviço do Tech Provider, registrando-se como Tech Provider no Facebook Developer Portal.[1] O Meta Business Agent rejeita chamadas de API até que ambos estejam registrados.
Configurar o faturamento para o Meta Business Agent
Configure um método de pagamento no Billing Hub da Meta antes de ativar o agente para tráfego de produção. As mensagens não são entregues a menos que a conta tenha um método de pagamento vinculado.[1] Navegue até business.facebook.com/latest/billing_hub/ e adicione um método de pagamento para o Business Portfolio associado à WABA.
Ativar o agente com ai_audience definido como ALLOWLISTED_ONLY não requer método de pagamento.[3] Um método de pagamento é necessário somente ao expandir para EVERYONE.
Criar e configurar um system user
Crie um system user com a função Admin no Meta Business Suite e, em seguida, atribua tanto o app quanto a WABA a esse usuário. As requisições de API do MBA se autenticam como system user.[1] Se um system user adequado já existir, pule para a atribuição de ativos.
Acesse o Meta Business Suite (business.facebook.com/settings/), abra Configurações, selecione System users em Usuários, clique em + Add, insira um nome, selecione a função Admin e clique em Create system user.
Para atribuir ativos, selecione o system user, clique no menu de três pontos e clique em Assign Assets. Selecione Apps, encontre o app e ative a caixa de seleção. Em seguida, encontre a WABA, ative a caixa de seleção e clique no controle deslizante ao lado de View and manage phone numbers. Clique em Assign Assets para salvar.
Se você gerencia múltiplas WABAs e precisa de ajuda para configurar system users entre elas, fale conosco sobre como simplificar o processo por meio de uma única integração de parceiro.
Gerar um token BISU com as permissões necessárias
Gere um token Business Integration System User (BISU) para o system user. Um token BISU permite que sua plataforma atue em nome de múltiplas WABAs de clientes sob uma única credencial.[1] A Meta documenta duas opções de token: um token de system user padrão para integradores diretos e um token BISU para Solution Partners e Tech Providers.
O MBA requer um token BISU com escopo para as permissões whatsapp_business_messaging e whatsapp_business_management; um token sem qualquer uma dessas permissões retorna um erro 401 Unauthorized.[5] Este é o ponto de falha mais comum durante a configuração. Verifique se ambas as permissões estão selecionadas antes de gerar o token.
Inclua o header X-API-Version: 2.0.0 em toda requisição de API do MBA.[1] Requisições sem esse header usam a versão 1.0.0 por padrão, onde o Endpoint de Skills não está disponível.
A equipe de suporte de parceiros da 360Dialog pode verificar a configuração do seu token antes que você encontre um erro 401.
Inscrever nos campos de Webhook necessários
Inscreva seu app na WABA e configure os três campos de Webhook necessários que conectam seu app ao pipeline de conversas.[1]
Primeiro, inscreva o app na WABA. No Graph API Explorer, selecione o app, escolha Get App Token, selecione o Business Portfolio e a WABA e envie POST /{WABA_ID}/subscribed_apps. Verifique com GET /{WABA_ID}/subscribed_apps.
Segundo, inscreva nos campos de Webhook no Facebook Developer Portal. Abra o app, navegue até a aba WhatsApp e abra Configuration. Inscreva-se em três campos: messages, standby e messaging_handovers.[1]
Esses campos estabelecem o roteamento de conversas entre o MBA e a sua aplicação. O MBA atua como o respondente principal. Seu app de parceiro recebe mensagens dos consumidores no Webhook standby enquanto o agente detém o controle, e no Webhook messages quando seu app detém o controle. O Webhook messaging_handovers é disparado a cada mudança de controle. Seu app de parceiro assume o controle enviando uma mensagem para a conversa ou chamando Thread Control com a ação take (restrita ao parceiro de escalação configurado). Para devolver o controle, chame Thread Control com a ação release. Parar de enviar mensagens não libera o controle; o Endpoint release deve ser chamado explicitamente.
Para uma análise mais detalhada das mudanças no roteamento de conversas, veja o que muda na sua integração BSP. Como BSP gerenciando a infraestrutura da WhatsApp Business API para contas de clientes, a 360Dialog, um Official Meta Solution Partner, oferece suporte ao caminho completo de ativação do MBA para números gerenciados pela sua plataforma.
Se a sua plataforma está pronta para a configuração do MBA, começar a usar a API para construir sobre a infraestrutura de WhatsApp Business API da 360Dialog.
Configurar conhecimento, skills e connectors do agente
Configure o agente em três estágios de API: Onboard, Configure e Operate. O mínimo para ativar o agente é chamar o Endpoint de Onboarding e depois o Endpoint de configurações.[1]
Comece com a API de Onboarding: envie POST /{entity_id}/agent_onboarding com um corpo vazio para WhatsApp.[2] Isso retorna um agent_id e cria a configuração do agente. Até que essa chamada seja bem-sucedida, todos os outros Endpoints do MBA reportam que nenhum agente existe para a entidade.
Após o Onboarding, configure o conhecimento pelos Endpoints dedicados: Skills (instruções do sistema), informações de negócio (horários, localizações, políticas), FAQs, websites (URLs para o agente rastrear), arquivos (fontes de conhecimento carregadas), Connectors (definições de API externas) e ferramentas de Connector.[1] O catálogo de produtos é gerenciado separadamente no Meta Commerce Manager.
Configure o comportamento de transferência pelo Endpoint de configurações. O booleano handoff.enabled controla se o agente libera o controle da Thread após uma mensagem de transferência. O campo message_selection suporta três modos: CUSTOM (o negócio fornece a mensagem), AGENT (a IA compõe conforme a conversa) e DEFAULT (mensagem padrão fixa).[3]
Testar o Meta Business Agent antes de ir para produção
Teste com uma audiência restrita antes de expor o agente a clientes reais. A sequência correta é: adicionar consumidores de teste à lista de permissões, definir ai_audience como ALLOWLISTED_ONLY e então ativar o agente.[1] Ativar o agente antes de restringir a audiência o expõe a conversas ao vivo.
Adicione números de telefone de teste chamando POST /{entity_id}/agent_config/allowlist com consumer_phone_number no formato E.164.[1] Liste as entradas com GET e remova com DELETE no mesmo Endpoint.
Ative o agente chamando PUT /{entity_id}/agent_config/settings com rollout.enabled definido como true.[3] A Meta também fornece uma Agent Test API em /{entity_id}/agent_test que envia mensagens de teste por todo o pipeline de forma síncrona, sem necessidade de ativar o agente e sem cobrar os tokens consumidos.[5]
Antes de mudar ai_audience para EVERYONE, confirme as inscrições de Webhook com GET /{WABA_ID}/subscribed_apps, verifique as configurações com GET /{entity_id}/agent_config/settings, vincule um método de pagamento no Billing Hub e valide a lógica de transferência disparando uma escalação pela Agent Test API.[1] Monitore o Endpoint de Agent Insights para revisar quais fontes de conhecimento e skills o agente usa durante as conversas de teste. Desativar o agente interrompe as respostas em todas as threads ativas; reativar faz com que ele responda apenas a novas threads.[3]
Clientes 360Dialog contam com suporte dedicado de parceiro em cada etapa da configuração do MBA, da configuração do token ao go-live. Começar a usar a API para começar a construir.
Perguntas frequentes
Posso usar o Meta Business Agent com um número gerenciado por BSP?
Sim. O Meta Business Agent funciona com números gerenciados por um BSP ou Tech Provider, desde que o número use Cloud API. O BSP ou Tech Provider deve aceitar os Termos de Serviço do Tech Provider no Facebook Developer Portal, e o token BISU deve incluir as permissões whatsapp_business_messaging e whatsapp_business_management.
O Meta Business Agent funciona em todos os segmentos?
O MBA suporta todos os segmentos, exceto Finanças, Governo, Saúde, Álcool, Jogos de Azar, medicamentos de venda livre e serviços matrimoniais. O número de telefone também deve ter uma categoria de negócio válida configurada no WhatsApp Manager. Confirme a elegibilidade chamando GET /{phone_number_id}/agent_eligibility com o header X-API-Version: 2.0.0 antes de iniciar o processo de configuração.
O que acontece se o token BISU estiver sem uma permissão?
Um token BISU que não tenha a permissão whatsapp_business_messaging ou whatsapp_business_management retorna um erro 401 Unauthorized nas chamadas de API do MBA. Gere novamente o token com ambas as permissões selecionadas. Este é o ponto de falha mais comum durante a configuração do MBA, portanto verifique ambos os escopos antes de fazer qualquer requisição de API.
Preciso configurar o faturamento antes de testar?
Ativar o agente com ai_audience definido como ALLOWLISTED_ONLY não requer método de pagamento. Um método de pagamento é necessário somente ao mudar ai_audience para EVERYONE para tráfego de produção. A Agent Test API em /{entity_id}/agent_test também envia mensagens de teste sem cobrar os tokens consumidos.
Qual é a diferença entre as ações release, pass e take do Thread Control?
A ação release devolve o controle do app de parceiro para o MBA. A ação pass transfere o controle para o parceiro de escalação, ou para o MBA quando control_pass.target_role está definido como ai_agent. A ação take é restrita ao parceiro de escalação configurado e assume o controle da conversa diretamente.
Sources
[1] “Get started,” Meta for Developers, accessed September 14, 2026, https://developers.facebook.com/documentation/meta-business-agent/get-started.
[2] “Agent Onboarding,” Meta for Developers, accessed September 14, 2026, https://developers.facebook.com/documentation/meta-business-agent/reference/onboard/agent-onboarding.
[3] “Agent Settings,” Meta for Developers, accessed September 14, 2026, https://developers.facebook.com/documentation/meta-business-agent/reference/onboard/agent-settings.
[4] “Overview,” Meta for Developers, accessed September 14, 2026, https://developers.facebook.com/documentation/meta-business-agent/overview.
[5] “Quickstart,” Meta for Developers, accessed September 14, 2026, https://developers.facebook.com/documentation/meta-business-agent/quickstart.
