Coexistência WhatsApp Business App + Cloud API

Guia operacional para configurar a Meta, iniciar o Embedded Signup e transformar o retorno da tela principal em uma conexão funcional com webhook, WABA, número e token.

Voltar para ativação

Antes de começar

  • Use uma conta do Facebook com acesso ao negócio e aos apps no Meta for Developers.
  • Abra o app correto pelo botão Meta de cada projeto na tela principal.
  • Confirme se o fluxo configurado na Meta é de coexistência, não de migração total.
  • Tenha o Configuration ID do Facebook Login for Business para cada projeto.
  • Cadastre os segredos do Worker: META_APP_ID, META_APP_SECRET e META_WEBHOOK_VERIFY_TOKEN.

Ponto crítico

A coexistência é para números que continuam usando o WhatsApp Business App e também passam a usar a Cloud API. Se o fluxo escolhido na Meta for o fluxo comum de registro ou migração, o número pode deixar de funcionar no app móvel.

Como auditar se é coexistência

  1. Abra o app pelo botão Meta do projeto na tela principal.
  2. Entre na configuração do WhatsApp ou do Facebook Login for Business usada pelo Embedded Signup.
  3. Confirme se o fluxo informa que o cliente manterá o número no WhatsApp Business App, conectará a Cloud API ou operará em paralelo.
  4. Se houver escolha de modo, selecione ou confirme Coexistence. Não use Full Migration para números que precisam continuar no app.
  5. Depois do signup, valide no celular se o WhatsApp Business App continua conectado e se as mensagens novas também chegam ao webhook.

Checklist por projeto

  • BarberPilot: Configuration ID 828858436960835.
  • CandiPilot: Configuration ID 1503468177713790.
  • FinPilot: Configuration ID 965227462960525.
  • LeanPilot: Configuration ID 969858969076522.
  • ZapiensIA: Configuration ID 1337746088306086.

Links úteis

Todos os apps Meta Docs Embedded Signup Coleção Meta Postman

Fluxo sequencial recomendado

1

Preparar o app na Meta

Abra o app do projeto e configure o Facebook Login for Business, o domínio HTTPS da aplicação, as URLs de redirecionamento e as permissões necessárias para WhatsApp Business Platform.

2

Gerar ou localizar o Configuration ID

No produto de Login for Business, copie o configuration_id do fluxo correto de Embedded Signup. Cole esse valor no projeto correspondente da tela principal.

3

Iniciar pela tela principal

Selecione o projeto, confira App ID e Configuration ID, mantenha os extras padrão e clique em Iniciar Embedded Signup. O popup da Meta deve guiar o login, o negócio, a WABA e o número.

4

Capturar o retorno

Ao finalizar, copie o JSON do painel Resultado recebido da Meta. Guarde o code, eventos do Embedded Signup, WABA ID e Phone Number ID quando retornados.

5

Trocar code por token no backend

Envie o code para o Worker em /auth/meta/exchange. O Worker usa o App Secret no servidor e retorna o token sem expor o segredo no navegador.

6

Assinar webhooks e validar mensagens

Configure a URL https://api.artacho.dev/webhooks/meta/whatsapp, valide o verify token e assine eventos de mensagens da WABA ou do número conectado.

Exemplo prático

BarberPilot

O App ID já vem preenchido. Cole o Configuration ID do fluxo de coexistência desse app.

Cliente

O cliente escaneia o QR code ou abre o link do projeto e conclui o Embedded Signup com o número usado no WhatsApp Business App.

Tela

A tela mostra o callback do FB.login e os eventos WA_EMBEDDED_SIGNUP.

Worker

O Worker recebe o code, troca por token e fica pronto para webhook e chamadas da Cloud API.

{
  "project": "BarberPilot",
  "code": "AUTH_CODE_RETORNADO_PELA_META",
  "waba_id": "WABA_ID_RETORNADO",
  "phone_number_id": "PHONE_NUMBER_ID_RETORNADO",
  "webhook_url": "https://api.artacho.dev/webhooks/meta/whatsapp"
}