Skip to main content

​
Credenciais da Meta

O Switchbord se comunica com a WhatsApp Business Platform através da Graph API da Meta. Antes que qualquer mensagem possa fluir, cinco coisas precisam estar em ordem:
  1. Meta access token (token de System User)
  2. App Secret (assinatura de webhook)
  3. Verify token (handshake de webhook)
  4. Phone Number ID (de qual número enviar)
  5. WhatsApp Business Account ID (WABA ID — a conta que é proprietária do número)
Você pode colar todos os cinco na página de Channel Settings ou no assistente de boas-vindas dentro do app, em /welcome. Cada campo tem um alternador “Onde encontro isso?” com o caminho exato no Meta Business Suite e um deep-link que leva você diretamente até lá.

​
1 · Meta access token

  1. Abra Meta Business Settings → Users → System Users.
  2. Selecione o System User atribuído à sua WABA (crie um caso ainda não tenha — ele precisa ter controle total sobre a WABA).
  3. Clique em Generate new token, escolha seu app do WhatsApp e conceda:
    • whatsapp_business_management
    • whatsapp_business_messaging
  4. Copie a longa string EAAG… e cole em Channel settings → Provider credentials → Meta Access Token.
O Switchbord criptografa o token em repouso no Supabase Vault. Ele nunca aparece nos logs da aplicação.

​
2 · App Secret

  1. Abra o Meta App Dashboard e selecione seu app do WhatsApp.
  2. Navegue até App settings → Basic.
  3. Clique em Show ao lado de App secret, autentique-se e copie o valor.
  4. Cole em Channel settings → Webhook Signing Secret.
O App Secret é como o Switchbord verifica que os payloads de webhook recebidos realmente vieram da Meta (HMAC-SHA256 sobre o corpo bruto da requisição).

​
3 · Verify token

Este você mesmo inventa — o Switchbord pode gerá-lo para você.
  1. No passo 3 do assistente de boas-vindas (ou em Channel settings → Meta verify token), clique em Generate.
  2. Copie o token gerado, no formato swb_….
  3. No Meta App Dashboard → WhatsApp → Configuration → Webhooks, clique em Edit, cole o mesmo token e defina a Callback URL para a que é exibida no assistente.
A Meta chama GET {callbackUrl}?hub.verify_token=… uma vez — o Switchbord responde com o challenge correspondente se os tokens coincidirem.

​
4 · Phone Number ID

  1. Abra WhatsApp Manager — Phone Numbers.
  2. Selecione a empresa proprietária da sua WABA.
  3. Encontre a linha do número de WhatsApp do qual você quer enviar.
  4. Copie o valor numérico longo na coluna ID (normalmente 15 dígitos).
  5. Cole em Channel settings → WhatsApp phone ID.
Depois de salvar, o Switchbord chama GET https://graph.facebook.com/v25.0/{phone_number_id} para confirmar que o ID é real e pertence ao escopo do seu access token. Você verá uma linha verde “Verified with Meta” em caso de sucesso, ou uma linha vermelha “Meta rejected this ID” com o código de erro exato em caso de falha (tipicamente meta_graph_100 se o ID estiver errado, ou meta_graph_190 se o token não tiver acesso).

​
5 · WhatsApp Business Account ID (WABA ID)

  1. Abra Business Settings → Accounts → WhatsApp Accounts.
  2. Selecione sua WABA.
  3. O ID numérico é exibido abaixo do nome da conta (e na URL — business.facebook.com/settings/whatsapp-business-accounts/<WABA_ID>).
  4. Cole em Channel settings → WhatsApp Business Account ID.
O WABA ID é usado para enviar templates e ler metadados em nível de conta. O Switchbord o valida contra GET https://graph.facebook.com/v25.0/{waba_id} imediatamente após salvar.

​
Solução de problemas

​
Alternativa: Meta Embedded Signup

Os cinco passos acima são o caminho traga seu próprio token — sempre disponível e o único caminho para implantações auto-hospedadas. Se sua implantação tiver o Embedded Signup habilitado (NEXT_PUBLIC_EMBEDDED_SIGNUP_ENABLED=1 mais as credenciais do app Meta), /welcome também oferece um fluxo de login hospedado pela Meta que pula completamente os passos 1, 4 e 5 acima — a Meta retorna o WABA ID e o Phone Number ID diretamente, e o Switchbord troca um código de uso único pelo access token no lado do servidor. Ele também suporta, de forma transparente, integrar uma segunda WABA ao mesmo workspace sem alterar o token armazenado da primeira WABA. Veja Meta Embedded Signup & Multi-WABA para o fluxo completo.

​
Referência

  • packages/whatsapp/validate-meta-ids.ts — valida em tempo real o Phone Number ID e o WABA ID contra a Graph API da Meta.
  • apps/app/app/api/settings/meta/validate-ids/route.ts — o endpoint que a interface chama.
  • As configurações de canal residem em channels.phone_number_id e channels.waba_id (veja packages/database/src/adapters/messages.ts).
  • apps/app/app/api/onboarding/meta/exchange/route.ts — o endpoint de troca de código do Embedded Signup (veja Meta Embedded Signup & Multi-WABA).