> ## 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.
# Configuração de Credenciais do Meta WhatsApp
> Guia operacional detalhado para configurar credenciais da Meta WhatsApp Business API — tokens de System User, atribuição de WABA, configuração de webhook e boas práticas de segurança.
# 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](/pt-BR/platform/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:
| Tipo de Token | Expiração | Vinculado a | Recomendado para |
| ----------------------------- | ---------------------------------- | ---------------------------------------- | --------------------------- |
| Token de User (curta duração) | 1–2 horas | Sessão de login de uma pessoa individual | Apenas testes |
| Token de User (longa duração) | 60 dias | Conta de uma pessoa individual | Nunca para produção |
| Token de Page | Varia | Página do Facebook + pessoa individual | Não aplicável para WhatsApp |
| Token de System User | Nunca (quando definido como Never) | Business Portfolio, não uma pessoa | **Produção — use este** |
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](https://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](/pt-BR/platform/connect-whatsapp) —
ele percorre a configuração completa do zero.
***
## Configuração de Credenciais Passo a Passo
Vá para [business.facebook.com/settings](https://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.
Navegue até: **Accounts → WhatsApp Accounts**
Encontre 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.
Navegue até: **Accounts → WhatsApp Accounts → \[sua WABA] → aba Phone Numbers**
Clique 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.
Navegue até: **Users → System Users → Add**
Configure:
* **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.
**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 Settings**
Role 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.
Navegue até: **Users → System Users → \[seu System User] → Generate new token**
No 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.
Vá para [developers.facebook.com](https://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.
Em [developers.facebook.com](https://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
| Credencial | Onde encontrar | Onde inserir no Switchbord |
| ------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| WABA ID | Business Settings → Accounts → WhatsApp Accounts → aba Settings → Account ID | Settings → Channel → WABA ID |
| Phone Number ID | Business Settings → WhatsApp Accounts → \[WABA] → Phone Numbers → \[número] | Settings → Channel → Phone Number ID |
| Token de acesso do System User | Business Settings → Users → System Users → Generate new token | Settings → Provider → Meta access token |
| App Secret | developers.facebook.com → App → Settings → Basic → App Secret | Settings → Provider → Meta App Secret |
| Verify Token | Gerado em Switchbord Settings → Provider | developers.facebook.com → App → WhatsApp → Configuration → Webhook → Verify Token |
***
## 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](/pt-BR/platform/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
* [Connect WhatsApp — Passo a Passo Completo](/pt-BR/platform/connect-whatsapp)
* [Webhooks](/pt-BR/operations/webhooks)
* [Secrets and Encryption](/pt-BR/security/secrets-and-encryption)
* [Operator Onboarding](/pt-BR/platform/onboarding)