Visão geral
Além do Embedded Signup (login guiado da Meta), o canal WhatsApp Cloud também pode ser conectado no modo manual: você informa as credenciais do seu próprio app Meta (API key, Phone Number ID e Business Account ID) e configura o webhook diretamente no Painel de Apps da Meta (WhatsApp → Configuração → Webhook). Esse modo é ideal para quem já tem um app Meta próprio, precisa de controle total sobre as assinaturas de webhook ou usa um token com permissões limitadas.
A plataforma oferece uma única URL de callback em nível de app que atende todos os seus números e contas WhatsApp Business (WABAs): cada evento é roteado automaticamente pelo conteúdo do payload. Também há uma URL alternativa por número, se preferir configurar número a número.
Pré-requisitos
- Perfil de administrador na plataforma.
- Um app Meta com o produto WhatsApp habilitado e acesso ao Painel de Apps.
- API key (token de acesso permanente), Phone Number ID e Business Account ID do número.
- Opcional, mas recomendado: o App Secret do app Meta (Configurações do app → Básico), usado para
validar a assinatura
X-Hub-Signature-256de cada webhook recebido.
Passo a passo
- Em Configurações → Caixas de Entrada, crie uma nova caixa e escolha WhatsApp.
- Selecione o provedor WhatsApp Cloud (modo manual, sem o login da Meta).
- Preencha nome da caixa, número de telefone, Phone Number ID, Business Account ID e API key.
- (Recomendado) Informe o App Secret para ativar a verificação de assinatura dos webhooks.
- Escolha se a plataforma deve registrar o webhook automaticamente via Graph API. Desative essa opção se você prefere configurar o webhook manualmente no Painel de Apps da Meta.
- Ao criar a caixa, a tela exibe a URL de callback (nível de app e por número) e o token de verificação, com botões de copiar.
- No Painel de Apps da Meta, abra WhatsApp → Configuração → Webhook, cole a URL de callback e o token de verificação e clique em Verificar e salvar.
- Assine os campos de webhook: no mínimo
messages; recomendamos assinar também os campos de templates, qualidade do número, conta e segurança para receber os eventos administrativos em tempo real. - Envie uma mensagem de teste para o número e confirme que ela chega na caixa de entrada.
Configurações & opções
- Aba Saúde da Conta (Configurações da caixa → Saúde da conta): mostra o painel de configuração manual do webhook com a URL, o token (mascarado, com revelar/copiar), o status do registro, o estado da verificação de assinatura (HMAC) e o modo de registro (automático ou manual).
- Reassinar: refaz o registro do webhook via Graph API (disponível quando o registro automático está ativo).
- Rotacionar token: gera um novo token de verificação. No modo manual, cole o novo valor no Painel de Apps da Meta depois de rotacionar.
- Eventos recentes da conta: a mesma aba lista os últimos eventos administrativos recebidos — status de templates, qualidade do número, alertas de conta, capacidade do negócio e segurança — com selos de severidade.
Casos de uso
- Empresas com app Meta próprio que não querem (ou não podem) usar o Embedded Signup.
- Operações com múltiplos números e WABAs no mesmo app Meta: uma única URL de callback atende todos; os lotes de eventos com várias entradas são processados por completo.
- Tokens com permissões limitadas (sem
whatsapp_business_management): com o registro automático desativado, a plataforma nunca chama as APIs de assinatura da Meta.
Dicas, limites e boas práticas
- Configure sempre o App Secret: sem ele, os webhooks são aceitos sem verificação de assinatura (a plataforma registra um aviso em log). O operador da instalação pode exigir assinatura em todas as caixas de forma global.
- Assine os campos de templates e qualidade no Painel de Apps: os status de templates (aprovado/rejeitado/pausado) passam a refletir na plataforma em tempo real, sem esperar a sincronização periódica.
- Se o Painel da Meta rejeitar algum campo de webhook, salve com um conjunto menor — o mínimo
indispensável é
messages. - Ao rotacionar o token com o registro automático desativado, lembre de atualizar o valor no Painel de Apps da Meta, senão a verificação do webhook falha na próxima validação.
Solução de problemas
- "Verificar e salvar" falha na Meta: confira se a URL de callback foi copiada por completo e se o token de verificação é exatamente o exibido na plataforma (sem espaços).
- Mensagens não chegam: confirme que o campo
messagesestá assinado no Painel de Apps e que o número não está listado como inativo pela operação. - Webhook marcado como divergente na aba Saúde da Conta: a URL registrada na Meta é diferente da esperada — use Reassinar (registro automático) ou corrija a URL manualmente no Painel de Apps.
- Eventos administrativos não aparecem: os campos correspondentes (templates, qualidade, conta, segurança) precisam estar assinados no webhook do app Meta.