Skip to main content

​
Configuração de Credenciais do Meta WhatsApp

Este guia é destinado a operadores e administradores de plataforma configurando credenciais da Meta WhatsApp Business API para um workspace do Switchbord. Ele cobre todos os tipos de credencial, explica por que cada uma é necessária e percorre os caminhos exatos de navegação no Meta Business Suite.
Este guia cobre o lado do operador da configuração de credenciais — o que você faz na Meta. Para o lado do Switchbord (inserindo credenciais em Settings), veja Connect WhatsApp.

​
Por que Tokens de System User

O Switchbord requer um token de acesso de System User, e não um token pessoal de User ou um token de Page. Veja por que isso importa: A vantagem crítica dos tokens de System User: eles não estão vinculados à conta de nenhuma pessoa individual. Se a pessoa que criou um token de User saísse da organização, o token se tornaria inválido e sua integração de WhatsApp quebraria — frequentemente de forma silenciosa, só sendo descoberta quando as mensagens pararem de ser enviadas. Tokens de System User também suportam definir a expiração como Never, o que elimina a sobrecarga operacional de rotação de token em uma programação.

​
Pré-requisitos

Antes de começar, confirme que você tem:
  • Acesso de administrador a um Meta Business Portfolio em business.facebook.com
  • Uma WhatsApp Business Account (WABA) já criada ou reivindicada
  • Um número de telefone comercial verificado nessa WABA
  • Um Meta App (tipo: Business) com o produto WhatsApp adicionado
Se você não tem isso, complete primeiro o guia Connect WhatsApp — ele percorre a configuração completa do zero.

​
Configuração de Credenciais Passo a Passo

1

Acesse as Configurações de Negócios da Meta

Vá para business.facebook.com/settings.Toda a configuração de credenciais acontece a partir deste painel central. Salve-o nos favoritos — você retornará aqui com frequência.
Se você gerencia múltiplos Business Portfolios, confirme que está no correto verificando o nome do portfólio no dropdown superior esquerdo.
2

Localize seu WABA ID

Navegue até: Accounts → WhatsApp AccountsEncontre sua WABA na lista e clique nela. Na aba Settings, copie o Account ID.Esta é uma string numérica de 15 dígitos — seu WABA ID. Salve-o em algum lugar acessível; você precisará dele ao configurar Switchbord Settings → Channel.
3

Localize seu Phone Number ID

Navegue até: Accounts → WhatsApp Accounts → [sua WABA] → aba Phone NumbersClique no seu número de telefone. Copie o Phone Number ID — novamente, uma string numérica de 15 dígitos.
O Phone Number ID não é o número de telefone formatado como +1 555 123 4567. É um ID numérico interno que se parece com 123456789012345. Usar o número formatado causará erros meta_graph_100 no Switchbord.
4

Crie um System User

Navegue até: Users → System Users → AddConfigure:
  • Name: Escolha algo descritivo, ex.: switchbord-prod ou switchbord-[nome-do-workspace]
  • Role: Admin
Clique em Create System User.
Você pode criar múltiplos System Users para ambientes diferentes (staging, production) ou workspaces diferentes. Cada System User pode ter seu próprio token com seu próprio conjunto de scopes.
5

Atribua o System User à sua WABA

Não pule esta etapa. Esta é a causa mais comum de erros meta_graph_190 (OAuthException). A mensagem de erro diz “token invalid”, mas o token está correto — o System User simplesmente não tem permissão para agir sobre a WABA.Mesmo um token de System User válido, permanente e com o escopo correto retornará meta_graph_190 até que o System User seja atribuído à WABA.
Navegue até: Accounts → WhatsApp Accounts → [sua WABA] → aba SettingsRole até Assigned system users e clique em Add people.
  1. Pesquise e selecione seu System User pelo nome
  2. Defina a permissão como Full control
  3. Clique em Save
Confirme que o System User agora aparece na lista de usuários atribuídos.Por que full control? O Switchbord precisa enviar mensagens (write), ler recibos de entrega (read) e gerenciar inscrições de webhook (admin). Permissões parciais causarão falhas intermitentes.
6

Gere o token de acesso do System User

Navegue até: Users → System Users → [seu System User] → Generate new tokenNo diálogo de geração de token:
  1. Select app: escolha seu Meta App (App ID: 1485717133228319 para o app do Switchbord)
  2. Select permissions — conceda no mínimo:
    • whatsapp_business_messaging — necessário para enviar mensagens
    • whatsapp_business_management — necessário para gerenciamento de WABA, consultas de número de telefone e analytics de billing da WABA
    • ads_read — necessário para consulta de campanha/anúncio da Meta em Insights
    • read_insights — necessário para analytics de preço/billing do WABA da Meta
    • paid_marketing_messages — necessário para analytics de mensagens de marketing pago onde aplicável
  3. Token expiry: defina como Never
  4. Clique em Generate Token
Copie a string completa do token imediatamente e armazene em um gerenciador de credenciais seguro.
Esta é a única vez que a Meta mostra o token completo. Depois de fechar este diálogo, você não pode recuperá-lo — apenas gerar um novo (o que invalida o antigo). Copie agora.
Gere o token depois de completar a atribuição de WABA na etapa anterior. A geração de token não retroage sobre novas atribuições de WABA em todos os casos. Se você já gerou um token antes de atribuir, gere um novo agora.
7

Recupere o App Secret

Vá para developers.facebook.com → My Apps → seu app → Settings → Basic.Clique em Show ao lado do campo App Secret. Copie o secret.O Switchbord usa isso para validar a assinatura HMAC nos payloads de webhook entrantes da Meta, garantindo que mensagens não possam ser falsificadas por terceiros.
O App Secret é diferente do token de System User. O token autentica chamadas de API de saída; o App Secret valida assinaturas de webhook de entrada. Ambos são necessários.
8

Configure o webhook da Meta

Em developers.facebook.com → My Apps → seu app → WhatsApp → Configuration → Webhook:
  • Callback URL: https://api.switchbord.ai/webhooks/meta
  • Verify Token: copie do campo Switchbord Settings → Provider → Verify Token
Clique em Verify and Save.A Meta fará imediatamente uma requisição GET para a callback URL com um parâmetro de challenge. O Switchbord responde com o challenge para confirmar que o endpoint está ativo e o verify token corresponde.
A verificação do webhook falhará se:
  • A WABA ainda não estiver conectada ao app da Meta
  • O verify token na Meta não corresponder exatamente ao salvo no Switchbord
  • Houver um espaço extra ou nova linha em qualquer um dos valores de token
Após a verificação ser bem-sucedida, clique em Manage e inscreva-se nestes campos de webhook:
  • messages — mensagens de entrada e atualizações de status
  • message_deliveries — recibos de entrega
  • messaging_optins — eventos de opt-in

​
Referência de Credenciais

​
Práticas de Segurança de Token

  • Armazene tokens em um gerenciador de senhas de equipe (1Password, Bitwarden, etc.), não em cofres pessoais
  • Restrinja os scopes do token apenas a whatsapp_business_messaging e whatsapp_business_management — não conceda permissões amplas
  • Rotacione tokens se comprometidos — gere um novo token de System User e atualize as Settings do Switchbord imediatamente
  • Nunca registre ou exponha tokens em logs de aplicação, mensagens de erro ou controle de versão
  • Use um System User por ambiente — tokens separados para staging e production simplificam a rotação e reduzem o raio de impacto

​
Configure a Meta Marketing API no Switchbord

Depois que o token existir na Meta, insira a configuração da Marketing API no Switchbord:
  1. Abra Settings → Integrations → Channels → WhatsApp.
  2. Em Provider credentials, localize o card Meta Ads / Marketing API.
  3. Escolha uma opção:
    • Reuse WhatsApp token se o token de WhatsApp existente do seu workspace já tiver ads_read, read_insights e whatsapp_business_management; ou
    • Cole um token de System User separado em Meta Ads token.
  4. Insira o ad account id da Meta no formato act_1234567890.
  5. Clique em Save & validate.
Para a GB Viaggi, o token de WhatsApp atual do workspace já tem os scopes necessários. Use Reuse WhatsApp token e o ad account id act_474265269673453.
Esta configuração desbloqueia:
  • Comparação de campanha/anúncio em Insights → Meta ads.
  • Ingestão de pricing_analytics e analytics do WABA em Insights → Billing.
  • Enriquecimento de anúncio, ad set e campanha do Click-to-WhatsApp quando referências de entrada incluírem um ad id.

​
Solução de Problemas

Veja a tabela completa de códigos de erro no guia Connect WhatsApp. Referência rápida para os problemas mais comuns: meta_graph_190 depois de inserir um token válido O System User não está atribuído à WABA. Complete a Etapa 5 acima. A verificação do webhook falha imediatamente Ou a WABA não está conectada ao app da Meta, ou os verify tokens não correspondem exatamente. Copie o verify token usando o botão de cópia no Switchbord para evitar problemas de espaços em branco. Mensagens são enviadas, mas nenhum recibo de entrega chega O campo de webhook message_deliveries não está inscrito. Vá para WhatsApp → Configuration → Manage → habilite message_deliveries.

​
Guias Relacionados