Access Token

O Access Token é a chave de autenticação que permite ao CloudWhats se comunicar com a API do WhatsApp Cloud em nome da sua conta. Entenda como ele entra no produto, quando o CloudWhats tenta renová-lo e quando você precisa agir manualmente.

Tipos de token

A API do WhatsApp Cloud usa dois tipos principais de token:

Token OAuth de curta duração

Obtido durante a autorização OAuth da Meta. Ele não é o formato mais estável para a operação do dia a dia, por isso o CloudWhats tenta convertê-lo para um token de maior duração durante o Embedded Signup.

Token de longa duração

É o tipo mais comum para credenciais conectadas via Meta. No fluxo atual, o CloudWhats trabalha com a janela padrão da Meta e registra metadados de expiração para manter a conta observável.

System User Token (permanente)

Token permanente gerado através de um System User no Meta Business Manager. Não expira, mas requer configuração manual mais avançada e app próprio no Meta. É útil para operações que preferem controlar o setup técnico diretamente.

Geração automática via Embedded Signup

Quando você adiciona uma credencial via Embedded Signup, o CloudWhats:

Recebe o código de autorização OAuth do Meta
Troca o código por um access token de curta duração
Tenta converter automaticamente para um token de longa duração
Armazena o token de forma segura na sua credencial
Configura o webhook para receber mensagens

Todo o processo de troca de tokens é feito automaticamente. Você não precisa manipular tokens manualmente ao usar o Embedded Signup.

Renovação de token

Para credenciais conectadas pelo fluxo da Meta, o CloudWhats registra a validade do token e tenta renovar automaticamente credenciais elegíveis antes da expiração. Se a Meta invalidar o token, se a renovação falhar ou se você estiver em setup manual, pode ser necessário reconectar a conta ou atualizar o token manualmente.

Acesse Configurações → Credenciais
Identifique a credencial que precisa de atualização ou reconexão
Se a conexão foi via modal da Meta, refaça a autorização quando necessário
Se a conexão é manual, informe um novo token válido na credencial correspondente

Se o token expirar sem renovação, o CloudWhats não conseguirá enviar ou receber mensagens nesse número. Fique atento às notificações de expiração.

Configuração manual de token

Se preferir usar um System User Token permanente, siga estes passos no Meta Business Manager:

Acesse Meta Business Manager → Configurações → Usuários do sistema
Crie um System User (tipo Admin)
Gere um token com as permissões: whatsapp_business_messaging, whatsapp_business_management
Copie o token e cole na credencial correspondente no CloudWhats

Tokens de System User não expiram, mas o setup é mais técnico e faz mais sentido para operações BYOC manuais que já controlam app e permissões no Meta.

Segurança do token

O CloudWhats adota medidas de segurança para proteger seus tokens:

Isolamento multi-tenant — cada tenant só acessa suas próprias credenciais via RLS (Row Level Security)
Delegação de acesso — controle granular de quais usuários e times podem acessar cada credencial
Webhook Verify Token — token usado para validar a configuração do webhook quando o fluxo é manual
App Secret — opcional para validação HMAC das requisições recebidas

Nunca compartilhe seu Access Token com terceiros. Qualquer pessoa com acesso ao token pode enviar mensagens em nome do seu número de WhatsApp.

Versão da API

Cada credencial está vinculada a uma versão da Graph API do Meta (atualmente padrão v25.0). O CloudWhats atualiza a versão automaticamente conforme a configuração do ambiente. Você não precisa gerenciar isso manualmente no dia a dia, mas mudanças de versão da Meta continuam sendo responsabilidade do produto e da própria Meta.