## 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-256` de cada webhook recebido.

## Passo a passo

1. Em **Configurações → Caixas de Entrada**, crie uma nova caixa e escolha **WhatsApp**.
2. Selecione o provedor **WhatsApp Cloud** (modo manual, sem o login da Meta).
3. Preencha nome da caixa, número de telefone, **Phone Number ID**, **Business Account ID** e
   **API key**.
4. (Recomendado) Informe o **App Secret** para ativar a verificação de assinatura dos webhooks.
5. 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.
6. 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.
7. 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**.
8. 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.
9. 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 `messages` está 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.

## Veja também

- [WhatsApp Cloud com Embedded Signup](/hc/ajuda/articles/inboxes-channels-whatsapp-cloud-embedded-signup-pt-br)
- [WhatsApp Cloud Coexistence](/hc/ajuda/articles/inboxes-channels-whatsapp-coexistence-pt-br)
- [WhatsApp Inbox Suite: Templates, Flows e Chamadas](/hc/ajuda/articles/inboxes-channels-whatsapp-inbox-suite-pt-br)