Skip to main content

​
Conectar WhatsApp

Este guia percorre o processo completo de conexão de um número do WhatsApp Business ao Switchbord. Ele cobre o que configurar no Meta Business Suite, o que inserir nas configurações do Switchbord e como diagnosticar os erros mais comuns.
Este processo envolve tanto a Meta (developers.facebook.com / business.facebook.com) quanto a UI de configurações do Switchbord. Mantenha ambas abertas em abas separadas. A configuração completa leva de 15 a 30 minutos na primeira vez.

​
Configuração Completa — Passo a Passo

Siga estes passos na ordem apresentada. Pular ou reordenar (especialmente os passos 5–7) é a fonte mais comum de erros.
1

Crie um App na Meta

Vá para developers.facebook.com → My Apps → Create App.
  • Tipo de app: Business
  • Adicione seu Business Portfolio quando solicitado
  • Após a criação, clique em Add Product → encontre WhatsApp → clique em Set Up
Se você já tem um app da Meta com WhatsApp adicionado, pode pular esta etapa. Apenas certifique-se de que está no modo Live (não Development) antes de ir para produção.
2

Crie ou conecte uma WhatsApp Business Account (WABA)

Durante a configuração do produto WhatsApp no seu app, a Meta solicitará que você selecione ou crie uma WhatsApp Business Account. Você pode:
  • Criar uma nova WABA — siga as instruções para configurar uma nova conta, ou
  • Conectar uma WABA existente — selecione-a no menu suspenso, se você já tiver uma
Uma vez conectada, a WABA aparecerá em Meta Business Settings em Accounts → WhatsApp Accounts.
3

Obtenha seu WABA ID

Em Meta Business Settings:Accounts → WhatsApp Accounts → [sua WABA] → aba SettingsCopie o Account ID — é uma string numérica de 15 dígitos. Este é o seu WABA ID.
Não insira o nome da WABA (por exemplo, “My Business”). Você precisa do Account ID numérico. Ele se parece com 123456789012345.
4

Obtenha seu Phone Number ID

Em Meta Business Settings:Accounts → WhatsApp Accounts → [sua WABA] → aba Phone NumbersClique no seu número de telefone e copie o Phone Number ID — uma string numérica de 15 dígitos.
Isso NÃO é o número de telefone de exibição, como +1 555 123 4567. É o ID interno da Meta para esse número, uma longa string numérica. Usar o número de exibição causará erros meta_graph_100.
5

Crie um System User

Em Meta Business Settings:Users → System Users → Add
  • Role: Admin
  • Name: algo reconhecível, por exemplo switchbord
Clique em Create System User.
Tokens de System User são permanentes (não expiram) e não estão vinculados à conta de nenhuma pessoa individual. É por isso que são fortemente preferidos em relação a tokens de usuário pessoal ou tokens de página para integrações de produção. Se a pessoa que criou um token de usuário sair da organização, o token deixa de funcionar. Tokens de System User não têm esse problema.
6

Atribua o System User à sua WABA

Esta é a etapa mais comumente esquecida. Pulá-la causa meta_graph_190 (OAuthException), mesmo quando seu token é válido, tem os escopos corretos e nunca expirou. O token está correto — o System User simplesmente ainda não está autorizado para a WABA.
Em Meta Business Settings:Accounts → WhatsApp Accounts → [sua WABA] → aba Settings → Assigned system users
  1. Clique em Add people
  2. Selecione seu System User (por exemplo, switchbord)
  3. Defina o nível de permissão como Full control
  4. Clique em Save
Você deve agora ver seu System User listado entre os usuários atribuídos à WABA.
7

Gere um access token de System User

Em Meta Business Settings:Users → System Users → [seu system user] → Generate new token
  • Selecione seu App da Meta (o que você criou no Passo 1)
  • Conceda estes escopos:
    • whatsapp_business_messaging
    • whatsapp_business_management
  • Defina a expiração do token como Never
  • Clique em Generate Token e copie o token completo imediatamente
Você só verá este token uma vez. Copie-o para um gerenciador de senhas seguro antes de fechar a caixa de diálogo. Se você perdê-lo, precisará gerar um novo.
Gere o token depois de atribuir o System User à WABA (Passo 6). Alguns usuários geram o token primeiro e depois fazem a atribuição — o próprio token não recebe automaticamente o novo acesso à WABA em todos os casos. Em caso de dúvida, gere um token novo após fazer a atribuição.
8

Obtenha seu App Secret

Vá para developers.facebook.com → My Apps → seu app → Settings → Basic → App Secret → Show.Copie o App Secret. Você vai precisar dele para a validação de assinatura de webhook no Switchbord.
9

Configure o Switchbord — Configurações de Channel

No Switchbord, abra Settings → Channel:
  • Phone Number ID: cole o ID numérico de 15 dígitos do Passo 4
  • WABA ID: cole o ID numérico de 15 dígitos do Passo 3
Salve as configurações do channel.
10

Configure o Switchbord — Credenciais de Provider

No Switchbord, abra Settings → Provider:
  • Meta access token: cole o token do System User do Passo 7
  • Meta App Secret: cole o App Secret do Passo 8
  • Verify Token: clique em Generate para criar um verify token aleatório (ou insira o seu próprio)
Salve as configurações do provider. Copie o Verify Token gerado — você vai precisar dele no próximo passo.
11

Configure o webhook da Meta

Vá para developers.facebook.com → My Apps → seu app → WhatsApp → Configuration → Webhook.
  • Callback URL: https://api.switchbord.ai/webhooks/meta
  • Verify Token: cole o valor exato de Switchbord Settings → Provider
Clique em Verify and Save. A Meta fará uma requisição de challenge para a URL do webhook, para confirmar que ela responde corretamente.
Se a verificação do webhook falhar, as causas mais prováveis são:
  1. A WABA ainda não está conectada (volte e complete os Passos 3–6)
  2. O Verify Token não corresponde exatamente (verifique espaços no início/fim)
  3. A callback URL tem um erro de digitação
12

Inscreva-se nos campos de webhook

Após verificar o webhook, clique em Manage ao lado das inscrições de webhook e habilite no mínimo:
  • messages
  • message_deliveries
  • messaging_optins
Clique em Done.
13

Valide a configuração no Switchbord

No Switchbord, abra Settings e execute Validate configuration.Todos os indicadores devem ficar verdes. Se algum estiver vermelho, veja a seção de Troubleshooting abaixo.
Envie uma mensagem de teste para o seu número de WhatsApp a partir de um telefone pessoal para confirmar a entrega de ponta a ponta antes de passar para o tráfego de produção.

​
Troubleshooting — Códigos de Erro

​
Erros Comuns

Até operadores experientes cometem esses erros. Não se sinta mal — a UI do Meta Business Suite facilita cometer todos eles por acidente.
  • Inserir o número de telefone de exibição (+1 555 123 4567) em vez do Phone Number ID (numérico de 15 dígitos). Eles parecem completamente diferentes; o ID não contém formatação de código de país.
  • Inserir o nome da WABA em vez do WABA Account ID. O nome é um rótulo legível; o ID é a string numérica.
  • Gerar o token do System User antes de atribuí-lo à WABA. Sempre atribua primeiro, depois gere. Se você fez na ordem errada, gere um token novo após atribuir.
  • Usar um token de User ou de Page em vez de um token de System User permanente. Tokens de User expiram ou quebram quando a conta do usuário muda. Tokens de System User são persistentes.
  • Deixar o app da Meta em modo Development. No modo Development, apenas números de teste podem enviar/receber mensagens. Mude o app para o modo Live para uso em produção.
  • Incompatibilidade do verify token por copiar e colar. Um espaço ou quebra de linha ao final do verify token fará a verificação do webhook falhar silenciosamente. Use o botão de copiar no Switchbord em vez de selecionar o texto manualmente.

​
O Que o Switchbord Não Vai Mostrar Para Você

Por segurança, o Switchbord não retorna os valores de segredo armazenados para o navegador. Você verá apenas:
  • Estado configurado ou ausente
  • Se o valor veio do Vault ou do fallback de ambiente
  • Dicas mascaradas, quando disponíveis
  • Status da última validação e código de erro

​
Manutenção Contínua

Após o go-live:
  • Rotacione tokens a partir de Settings, em vez de refazer o deploy do app
  • Execute a validação novamente após a rotação
  • Mantenha os valores de ambiente apenas como fallback de bootstrap ou emergência
  • Tokens de System User configurados para nunca expirar não precisam de rotação programada, mas rotacione-os se suspeitar de comprometimento

​
Leia a Seguir