{"id":1726,"date":"2026-09-07T08:34:15","date_gmt":"2026-09-07T08:34:15","guid":{"rendered":"https:\/\/360dialog.com\/blog\/?p=1726"},"modified":"2026-09-07T08:53:13","modified_gmt":"2026-09-07T08:53:13","slug":"o-que-acontece-integracao-bsp-meta-business-agent","status":"publish","type":"post","link":"https:\/\/360dialog.com\/blog\/br\/o-que-acontece-integracao-bsp-meta-business-agent\/","title":{"rendered":"O que acontece com sua integra\u00e7\u00e3o de BSP quando o Meta Business Agent \u00e9 ativado"},"content":{"rendered":"\n

Quando o Meta Business Agent \u00e9 ativado em um n\u00famero 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\u00e9m o controle, e o app recupera o controle enviando uma mensagem ou, como parceiro de escalonamento configurado, chamando o Thread Control com a a\u00e7\u00e3o take.<\/strong>[1] Tr\u00eas campos de webhook carregam o tr\u00e1fego, dois Termos de Servi\u00e7o controlam cada chamada de API, e a Meta cobra a empresa diretamente a US$ 2,00 por 1 milh\u00e3o de tokens. O mecanismo est\u00e1 documentado nas p\u00e1ginas de desenvolvedores da Meta e pode ser testado em n\u00fameros na allowlist antes que um consumidor real chegue ao agente.<\/p>\n\n\n\n

<\/p>\n\n\n\n

Principais conclus\u00f5es<\/h2>\n\n\n\n
    \n
  1. O Meta Business Agent exige tr\u00eas assinaturas de campos de webhook (messages, standby e messaging_handovers), e as mensagens do consumidor migram para standby enquanto o agente mant\u00e9m o controle.<\/li>\n\n\n\n
  2. Seu app assume o controle ao enviar qualquer mensagem e o mant\u00e9m at\u00e9 chamar o Thread Control com a a\u00e7\u00e3o release; nas palavras da Meta, “Stopping message sends does not release control” (parar de enviar mensagens n\u00e3o libera o controle).<\/li>\n\n\n\n
  3. Dois Termos de Servi\u00e7o controlam cada chamada de API: o do cliente no WhatsApp Manager e o do BSP no Facebook Developer Portal.<\/li>\n\n\n\n
  4. Solution Partners e Tech Providers se autenticam com um token de Business Integration System User (BISU) que possui as duas permiss\u00f5es exigidas, al\u00e9m do header X-API-Version: 2.0.0.<\/li>\n\n\n\n
  5. Um agente configurado com ai_audience ALLOWLISTED_ONLY pode ser ativado sem um m\u00e9todo de pagamento, ent\u00e3o testar com consumidores na allowlist vem antes da cobran\u00e7a.<\/li>\n<\/ol>\n\n\n\n

    <\/p>\n\n\n\n

    O que muda na configura\u00e7\u00e3o do seu webhook quando o Meta Business Agent est\u00e1 ativo?<\/h2>\n\n\n\n

    O Meta Business Agent exige tr\u00eas 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\u00e9m o controle: standby enquanto o agente o det\u00e9m, messages enquanto seu app o det\u00e9m. Um evento messaging_handovers dispara sempre que o controle muda de m\u00e3os, e standby \u00e9 o padr\u00e3o para novas conversas assim que o agente \u00e9 ativado.[4]<\/p>\n\n\n\n

    O payload de standby cont\u00e9m um dos tr\u00eas objetos: standby.messages para a mensagem recebida do consumidor, standby.message_echoes para cada mensagem enviada pelo agente, e standby.statuses para as confirma\u00e7\u00f5es de envio, entrega e leitura dessas mensagens.[3] O conte\u00fado recebido usa a mesma estrutura de payload de um webhook de mensagem recebida padr\u00e3o, e suas pr\u00f3prias mensagens enviadas nunca s\u00e3o ecoadas de volta para voc\u00ea.<\/p>\n\n\n\n

    O guia completo do Meta Business Agent<\/a> resume esse modelo de roteamento. Para uma integra\u00e7\u00e3o constru\u00edda por um BSP, a mudan\u00e7a de c\u00f3digo \u00e9 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.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    Como funciona o Thread Control entre o Meta Business Agent e seu app?<\/h2>\n\n\n\n

    Thread Control \u00e9 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\u00e1tico. Pass transfere o controle para o parceiro de escalonamento configurado para o n\u00famero de telefone, ou para o agente quando control_pass.target_role \u00e9 “ai_agent”. Ambos exigem que quem chama j\u00e1 detenha o controle. Take adquire o controle do detentor atual e \u00e9 restrito ao parceiro de escalonamento configurado; outros apps recebem um erro e assumem o controle enviando uma mensagem.<\/p>\n\n\n\n

    A p\u00e1gina Get Started da Meta (atualizada em 25 de agosto de 2026) documenta POST https:\/\/graph.facebook.com\/v21.0\/<\/a>\/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\u00eancia do Thread Control (Cloud API) (atualizada em 4 de setembro de 2026) documenta as mesmas tr\u00eas a\u00e7\u00f5es em https:\/\/api.facebook.com\/business\/whatsapp\/phone_numbers\/{phone_number_id}\/thread_control<\/a> com X-API-Version 1.0.0, ent\u00e3o teste release primeiro no seu pr\u00f3prio ambiente.[2]<\/p>\n\n\n\n

    Ativar o Meta Business Agent n\u00e3o 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\u00e7\u00e3o. Nas palavras da Meta, “Your app retains control until you explicitly release it. Stopping message sends does not release control” (seu app mant\u00e9m o controle at\u00e9 que voc\u00ea o libere explicitamente; parar de enviar mensagens n\u00e3o libera o controle). Uma resposta autom\u00e1tica que dispara em uma mensagem de standby, portanto, silencia o agente at\u00e9 que seu app chame release.<\/p>\n\n\n\n

    Quando o controle \u00e9 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; \u00e9 o \u00fanico payload de messaging_handovers documentado nas p\u00e1ginas de desenvolvedores do Meta Business Agent. As p\u00e1ginas da Meta ainda n\u00e3o descrevem como o parceiro de escalonamento \u00e9 configurado nem se um app de BSP pode assumir esse papel.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    Quais Termos de Servi\u00e7o precisam ser aceitos para as chamadas de API funcionarem?<\/h2>\n\n\n\n

    Dois Termos de Servi\u00e7o controlam cada chamada de API do Meta Business Agent em um n\u00famero gerenciado por BSP: o cliente aceita os Termos de Servi\u00e7o do Meta Business Agent no WhatsApp Manager, e o Solution Partner ou Tech Provider aceita os Termos de Servi\u00e7o de Tech Provider no Facebook Developer Portal. At\u00e9 que ambos estejam em vigor, a Meta rejeita as chamadas com 403 Forbidden e um erro de Termos de Servi\u00e7o.<\/p>\n\n\n\n

    A aba do lado do cliente aparece no WhatsApp Manager somente quando pelo menos um n\u00famero de telefone na WhatsApp Account (anteriormente WhatsApp Business Account, ou WABA) \u00e9 eleg\u00edvel; o checklist de elegibilidade<\/a> cobre essas condi\u00e7\u00f5es, que incluem n\u00fameros da Cloud API gerenciados por um Solution Partner ou via Embedded Signup.[12]<\/p>\n\n\n\n

    O lado do parceiro exige o status de Tech Provider: um app da Meta com o caso de uso WhatsApp, verifica\u00e7\u00e3o de empresa, App Review com dois v\u00eddeos de demonstra\u00e7\u00e3o, e acesso avan\u00e7ado \u00e0s permiss\u00f5es whatsapp_business_messaging e whatsapp_business_management.[5] A 360Dialog, um Official Meta Solution Partner<\/a>, opera a infraestrutura de WhatsApp Business API e a Partner Platform que ISVs e revendedores integram; em um n\u00famero que ela gerencia, a aceita\u00e7\u00e3o de Tech Provider \u00e9 a etapa do lado do parceiro, e a aceita\u00e7\u00e3o no WhatsApp Manager \u00e9 a etapa da pr\u00f3pria empresa.<\/strong><\/p>\n\n\n\n

    <\/p>\n\n\n\n

    O que acontece com os tokens BISU e as permiss\u00f5es de system user?<\/h2>\n\n\n\n

    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\u00f3pria WABA. Ambos os tipos de token exigem whatsapp_business_messaging e whatsapp_business_management. Um token BISU permite que uma \u00fanica plataforma atue em nome de v\u00e1rias WABAs de clientes sob uma \u00fanica credencial e \u00e9 gerado via Embedded Signup com Facebook Login for Businesses.[6] Um token sem uma das permiss\u00f5es retorna 401, segundo o Quickstart da Meta.[11]<\/p>\n\n\n\n

    Toda requisi\u00e7\u00e3o da API da Plataforma tamb\u00e9m precisa do header X-API-Version: 2.0.0; sem ele, as requisi\u00e7\u00f5es assumem o padr\u00e3o 1.0.0, no qual o endpoint Skills n\u00e3o est\u00e1 dispon\u00edvel. O system user de uma integra\u00e7\u00e3o direta precisa ter o papel de Admin e ter a WABA atribu\u00edda com “View and manage phone numbers” habilitado.<\/p>\n\n\n\n

    Pronto para rodar o Meta Business Agent no seu pr\u00f3prio n\u00famero de WhatsApp Business API? Come\u00e7ar a usar a API<\/a>.<\/strong><\/p>\n\n\n\n

    <\/p>\n\n\n\n

    As respostas do agente aparecem no seu dashboard ou inbox do BSP?<\/h2>\n\n\n\n

    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\u00e7\u00e3o enviada para POST \/{phone-number-id}\/messages, com confirma\u00e7\u00f5es de entrega e leitura em standby.statuses. A Meta n\u00e3o documenta o comportamento do inbox de nenhum BSP, ent\u00e3o pergunte ao seu provedor e teste em um n\u00famero na allowlist.<\/p>\n\n\n\n

    O handoff humano do lado do agente \u00e9 regido por dois campos de Agent Settings: handoff.enabled controla se o agente libera o controle da thread ap\u00f3s enviar uma mensagem de handoff, e handoff.message_selection escolhe DEFAULT, AGENT ou CUSTOM como origem dessa mensagem.[8] A documenta\u00e7\u00e3o da Meta n\u00e3o especifica o que dispara um handoff; a resposta do endpoint Agent Test traz um campo handoff_reason para observ\u00e1-lo.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    Quais mensagens s\u00e3o cobradas pela Meta e quais pelo seu BSP?<\/h2>\n\n\n\n

    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 \u00fanica de US$ 2,00 por 1 milh\u00e3o de tokens; uma mensagem t\u00edpica consome de 20.000 a 25.000 tokens, aproximadamente 4 a 5 centavos de d\u00f3lar, j\u00e1 que \u00e9 uma \u00fanica cobran\u00e7a 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\u00e3o isentam as mensagens do agente. Uma mensagem que n\u00e3o \u00e9 template \u00e9 cobrada como mensagem de agente ou como mensagem de servi\u00e7o, nunca como as duas, ent\u00e3o uma resposta humana ap\u00f3s um handoff \u00e9 uma mensagem de servi\u00e7o: gratuita at\u00e9 1\u00ba de outubro de 2026, depois cobrada por mensagem.<\/p>\n\n\n\n

    A Meta n\u00e3o entrega mensagens do agente para uma empresa sem um m\u00e9todo de pagamento em sua conta de Business Agent: uma linha de cr\u00e9dito da Meta faturada mensalmente ou, a partir de 8 de setembro de 2026, um cart\u00e3o de cr\u00e9dito ou d\u00e9bito Visa ou Mastercard. Linhas de cr\u00e9dito, cart\u00f5es, moedas e faturas s\u00e3o abordados em quem cobra pelas mensagens do Meta Business Agent<\/a>.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    O que voc\u00ea deve testar antes de ativar o Meta Business Agent?<\/h2>\n\n\n\n

    Teste em um n\u00famero ativo com o agente restrito a consumidores na allowlist; sob o ai_audience padr\u00e3o de EVERYONE, o agente responde a todos os consumidores. A ordem documentada pela Meta \u00e9 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\u00f3 ent\u00e3o definir rollout.enabled como true.[9] Um agente ativado com ai_audience definido como ALLOWLISTED_ONLY n\u00e3o exige um m\u00e9todo de pagamento, ent\u00e3o um cliente de BSP pode testar de ponta a ponta antes de configurar a cobran\u00e7a; ativ\u00e1-lo para EVERYONE, ou expandir para EVERYONE depois, exige um m\u00e9todo de pagamento e retorna 400 at\u00e9 que ele seja associado.[10]<\/p>\n\n\n\n

    Antes de fazer a mudan\u00e7a, execute estas verifica\u00e7\u00f5es:<\/p>\n\n\n\n