> ## Documentation Index > Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt > Use this file to discover all available pages before exploring further. # Conectar WhatsApp > Guia completo passo a passo para conectar um número do WhatsApp Business ao Switchbord — incluindo configuração na Meta, configuração de credenciais e troubleshooting. # 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. Vá para [developers.facebook.com](https://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. 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](https://business.facebook.com/settings) em **Accounts → WhatsApp Accounts**. Em [Meta Business Settings](https://business.facebook.com/settings): **Accounts → WhatsApp Accounts → \[sua WABA] → aba Settings** Copie 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`. Em [Meta Business Settings](https://business.facebook.com/settings): **Accounts → WhatsApp Accounts → \[sua WABA] → aba Phone Numbers** Clique 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`. Em [Meta Business Settings](https://business.facebook.com/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. **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](https://business.facebook.com/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. Em [Meta Business Settings](https://business.facebook.com/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. Vá para [developers.facebook.com](https://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. 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. 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. Vá para [developers.facebook.com](https://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 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**. 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 | Erro | Significado | Correção | | ------------------------------------------------------------ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `meta_graph_190` | OAuthException — System User não atribuído à WABA, ou token expirado | **Mais provável:** atribua o System User à WABA (Passo 6 acima). Se já estiver atribuído, verifique se o token não expirou. Se estiver usando um token de User em vez de um token de System User, gere um token de System User adequado. | | `meta_graph_100` | Phone Number ID inválido | Seu Phone Number ID em Settings → Channel está errado ou ainda é um placeholder. Obtenha o ID numérico real de 15 dígitos em Meta Business Settings → aba Phone Numbers. Não use o número de exibição (+1 555...). | | Falha de callback de webhook `#N/A:WBxP...` | A Meta não consegue completar o handshake de verificação | Verifique: (1) a URL do webhook é exatamente `https://api.switchbord.ai/webhooks/meta`, sem barra final; (2) o verify token na Meta corresponde exatamente ao que está salvo no Switchbord — sem espaços extras; (3) a WABA precisa estar conectada antes de inscrever o webhook. | | `workspace_secret_store_unavailable` | `SUPABASE_DB_URL` está faltando no ambiente da Vercel | Contate seu administrador do Switchbord — este é um problema de configuração de infraestrutura, não um problema de credencial da Meta. | | Token funciona no Meta API Explorer, mas falha no Switchbord | Incompatibilidade de tipo de token | O API Explorer usa um token de User temporário. O Switchbord requer um token de System User permanente. Gere um token de System User com os passos acima. | *** ## 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 * [Configuração de Credenciais da Meta — Guia do Operador](/pt-BR/operations/meta-credential-setup) * [Onboarding do Operador](/pt-BR/platform/onboarding) * [Arquitetura da Plataforma](/pt-BR/platform/architecture) * [API Interna](/pt-BR/api-reference/introduction)