Atualizado em 25/10/2026
O token permanente da API do WhatsApp é um token de acesso de usuário do sistema, criado nas configurações do portfólio empresarial da Meta, com as permissões whatsapp_business_messaging, whatsapp_business_management e business_management. Na geração, você escolhe se ele nunca expira ou se vale por 60 dias e precisa ser renovado. É ele que deve ir para produção, no lugar do token temporário do painel do app, que expira em poucas horas.
Este guia mostra o passo a passo no painel, os ativos que o usuário do sistema precisa receber, como gerar, renovar e revogar o token pela API e os cuidados de segurança.
Os três tipos de token da API do WhatsApp
A documentação de tokens de acesso da Meta separa três tipos:
| Tipo | Para quem | Duração |
|---|---|---|
| Token de usuário (user access token) | Desenvolvimento e testes; é o que aparece no painel “Configuração da API” do app | Expira rápido, precisa ser gerado de novo a cada poucas horas |
| Token de usuário do sistema (system user access token) | Empresa que acessa os próprios dados, integração direta | Longa duração; nunca expira ou 60 dias, conforme a escolha na geração |
| Token de integração empresarial (business integration system user) | Provedores de tecnologia e parceiros que conectam clientes pelo Cadastro Incorporado (Embedded Signup) | Gerado pela troca do código do Cadastro Incorporado |
Quem integra a própria empresa direto com a Cloud API usa o segundo. Quando o seu sistema começa a receber erros 190 (token expirado) ou 0 (não foi possível autenticar) depois de algumas horas no ar, quase sempre é porque o token temporário foi parar em produção. A lista desses códigos está em erros da API do WhatsApp.
Antes de começar
Você vai precisar de:
- acesso de administrador ao portfólio empresarial (antigo Business Manager);
- um app no painel de desenvolvedores da Meta, com o produto WhatsApp adicionado;
- a conta do WhatsApp Business (WABA) e o número já criados no portfólio.
Se ainda não chegou nessa etapa, o artigo como conseguir acesso à API do WhatsApp cobre portfólio, app, WABA e número.
Passo a passo: criar o usuário do sistema e gerar o token
Os passos abaixo seguem a documentação oficial. Os nomes de menu podem variar um pouco conforme o idioma e a versão do Meta Business Suite.
- Abra as Configurações do negócio do portfólio e clique em Usuários do sistema.
- Clique em + Adicionar, dê um nome (ex.:
integracao-whatsapp-prod) e escolha a função Funcionário ou Administrador. - Clique no nome do usuário criado e depois em Atribuir ativos.
- Selecione o seu app, conceda a permissão Gerenciar app e confirme.
- Recarregue a página até o app aparecer com controle total. A Meta avisa que a atribuição pode levar alguns minutos.
- Ainda no usuário do sistema, clique em Gerar token, selecione o app e escolha a preferência de expiração.
- Marque as três permissões:
business_management,whatsapp_business_managementewhatsapp_business_messaging. - Clique em Gerar token e copie o valor. Ele só é exibido uma vez.
Não esqueça de dar acesso à conta do WhatsApp
Gerar o token com as permissões certas não basta. O usuário do sistema também precisa de acesso parcial ou total aos ativos do WhatsApp que ele vai consultar. Pela documentação, muitos endpoints exigem esse acesso tanto na conta do WhatsApp quanto na conta de mensagens vinculada, e sem ele a API devolve erro de código 200.
No Meta Business Suite, vá em Configurações → Contas, abra a conta do WhatsApp, entre na aba Pessoas, clique em + Adicionar pessoas, selecione o usuário do sistema e escolha o nível de acesso. Repita para a conta de mensagens. A Meta observa que, pelo Business Suite, uma atribuição não se propaga para a outra conta: atribua as duas explicitamente.
Funcionário ou administrador?
Um usuário do sistema administrador tem acesso total a todas as contas do portfólio por padrão. Um funcionário só acessa o que foi atribuído a ele. Para uma integração, a escolha mais segura é funcionário, com acesso só ao app e às contas do WhatsApp necessárias. A visão geral de usuários do sistema recomenda criar um usuário do sistema por tipo de acesso e proteger com cuidado o token do administrador, porque um token vazado com escopo pequeno causa menos estrago.
Expiração: “nunca” ou 60 dias
Na hora de gerar, a Meta oferece duas opções, descritas na página Install Apps, Generate, Refresh, and Revoke Tokens:
| Opção | Validade | Renovação | Quando usar |
|---|---|---|---|
| Sem expiração | Nunca expira por tempo | Não precisa | Quando você aceita o risco de vazamento em troca de não ter rotina de renovação |
| Expiração em 60 dias | 60 dias a partir da geração ou da última renovação | Obrigatória dentro do prazo | Quando quer limitar o impacto de um token vazado. É a opção marcada como recomendada |
O nome “token permanente” vem da primeira opção. Mesmo assim, ele pode deixar de funcionar por outros motivos: o usuário do sistema perde o acesso ao app, as permissões são retiradas ou alguém revoga o token. Trate a falha de autenticação como evento a ser monitorado, não como algo impossível.
Com a opção de 60 dias, se o token não for renovado dentro do prazo, ele é perdido e você precisa gerar outro. Coloque a renovação num job agendado, não num lembrete de calendário.
Gerar, renovar e revogar pela API
Tudo o que o painel faz também pode ser feito por chamadas à Graph API. Isso é útil para automatizar a rotação.
Gerar
O usuário do sistema precisa ter o app instalado (POST /SYSTEM_USER_ID/applications). Depois, a geração é feita no endpoint access_tokens, com set_token_expires_in_60_days=true para o token de 60 dias:
curl -X POST "https://graph.facebook.com/vXX.X/SYSTEM_USER_ID/access_tokens" \
-d "business_app=APP_ID" \
-d "scope=business_management,whatsapp_business_management,whatsapp_business_messaging" \
-d "set_token_expires_in_60_days=true" \
-d "appsecret_proof=APPSECRET_PROOF" \
-d "access_token=TOKEN_ATUAL"O appsecret_proof é o HMAC-SHA256 do token, usando o segredo do app como chave. Ele prova que a chamada vem do seu servidor:
import crypto from 'node:crypto';
const appsecretProof = crypto
.createHmac('sha256', process.env.META_APP_SECRET)
.update(process.env.META_ACCESS_TOKEN)
.digest('hex');Renovar
A renovação usa o endpoint oauth/access_token com grant_type=fb_exchange_token. A resposta traz o novo access_token e o expires_in em segundos:
curl -G "https://graph.facebook.com/vXX.X/oauth/access_token" \
-d "grant_type=fb_exchange_token" \
-d "client_id=APP_ID" \
-d "client_secret=APP_SECRET" \
-d "set_token_expires_in_60_days=true" \
-d "fb_exchange_token=TOKEN_ATUAL"Revogar
curl -G "https://graph.facebook.com/vXX.X/oauth/revoke" \
-d "client_id=APP_ID" \
-d "client_secret=APP_SECRET" \
-d "revoke_token=TOKEN_ANTIGO" \
-d "access_token=TOKEN_NOVO"A resposta de sucesso é {"success":"true"}. O app do client_id precisa ser o mesmo dos dois tokens.
Rotação sem derrubar a integração
A Meta descreve uma rotação sem indisponibilidade em três passos:
- Renovar: gere o novo token. O antigo continua válido até o fim do prazo dele.
- Publicar: atualize o token no cofre de segredos e faça o deploy ou o recarregamento da configuração.
- Revogar: só depois de confirmar que tudo usa o token novo, revogue o antigo. A revogação vale na hora.
Um job semanal que verifica a idade do token e renova quando passar de, por exemplo, 45 dias deixa margem para falhas de deploy.
Cuidados de segurança
- Guarde em cofre de segredos ou variável de ambiente. Nunca em repositório, planilha ou mensagem de chat.
- Não interprete o formato do token. A Meta pede para tratá-lo como valor opaco e para armazená-lo em campo de tamanho variável, sem limite fixo de caracteres.
- Envie no cabeçalho
Authorization: Bearer, nunca na URL, onde ele acaba em logs. - Escopo mínimo. Um usuário do sistema funcionário por integração, com acesso só às contas necessárias.
- Proteja o segredo do app. Com ele e um token, é possível renovar e revogar tokens.
- Verifique o token na ferramenta de depuração de tokens de acesso da Meta, que mostra permissões e expiração.
O artigo segurança da conta business no WhatsApp trata de PIN, acessos ao portfólio e golpes.
Como isso funciona na Vectalk
Na Vectalk, você não precisa criar usuário do sistema nem gerenciar o token da Meta. Ao conectar o número pelo Cadastro Incorporado, a Vectalk importa o phone_number_id, o waba_id e o token de acesso, segundo o guia rápido. Sua aplicação usa um token da própria Vectalk:
- Token de organização: acessa todas as instâncias e exige
phone_number_idno envio. - Token de instância: limitado a um número, necessário para mídia e templates.
Pela documentação de tokens, os tokens da Vectalk não expiram automaticamente, valem até serem revogados, são exibidos uma única vez e ficam armazenados como hash. A criação e a revogação também podem ser feitas por API, em POST /api/auth/api-tokens e DELETE /api/auth/api-tokens/{id}, descritas em Autenticação. A mesma rotina de rotação descrita acima vale aqui: crie o novo, publique, revogue o antigo.
Para começar, crie sua conta em apps.vectalk.com.br/register. O contexto completo da plataforma está no guia da API oficial do WhatsApp, e o próximo passo natural é enviar a primeira mensagem.
Perguntas frequentes
O token temporário do painel do app serve para produção?
Não. É um token de usuário pensado para testes e expira em poucas horas. Para produção, use um token de usuário do sistema.
O token permanente do WhatsApp nunca expira mesmo?
Se você escolher a opção sem expiração, ele não expira por tempo. Mas pode ser invalidado se o usuário do sistema perder acesso ao app ou às permissões, ou se for revogado.
Quais permissões o token precisa ter?
business_management, whatsapp_business_management e whatsapp_business_messaging. Além disso, o usuário do sistema precisa de acesso à conta do WhatsApp e à conta de mensagens.
Por que recebo erro 200 mesmo com o token certo?
Normalmente porque o usuário do sistema não recebeu acesso parcial ou total aos ativos do WhatsApp. Atribua a conta do WhatsApp e a conta de mensagens ao usuário do sistema.
Perdi o token. Consigo ver de novo?
Não. O token aparece só no momento da geração. Gere um novo e revogue o anterior.
Fontes oficiais consultadas em 25/10/2026: Access tokens (WhatsApp Business Platform), Install Apps, Generate, Refresh, and Revoke Tokens, Visão geral de usuários do sistema, Códigos de erro da Cloud API, Guia rápido da Vectalk, Tokens na documentação da Vectalk, Autenticação na documentação da Vectalk.