WhatsApp Cloud API: como configurar direto na Meta

O que você precisa antes de configurar?

Uma conta no Facebook ou conta gerenciada da Meta, o cadastro de desenvolvedor feito, um aparelho com WhatsApp para receber os testes e um servidor público com HTTPS válido para o webhook. Certificado autoassinado não é aceito. Para produção, você também vai precisar de um número comercial próprio e de um portfólio empresarial.

Este guia é para quem vai integrar o número da própria empresa, sem intermediário. Se o plano é conectar números de clientes ao seu produto, o caminho é outro: veja como virar Tech Provider da Meta. E se você só quer o número funcionando no seu sistema, sem montar a parte da Meta, pule para o fim deste guia.

Passo 1: como criar o app no Painel de Apps da Meta?

No Painel de Apps, clique em Criar app, informe o nome do app e o seu e-mail e escolha o caso de uso "Conectar-se com clientes pelo WhatsApp". Selecione um portfólio empresarial existente ou crie um novo, confira os dados e clique em Criar app. O painel leva você para a tela de Início rápido do caso de uso.

O caminho completo dessa tela é Personalizar caso de uso, Conectar no WhatsApp, Início rápido. Pelo menu lateral do caso de uso você chega também à Configuração da API, onde ficam token, números e envio de teste, e à Configuração, onde fica o webhook.

Passo 2: como mandar a primeira mensagem com o número de teste?

Em Início rápido, clique em Começar a usar a API. Na Configuração da API, conecte o app a uma conta do WhatsApp Business existente ou crie uma. Depois clique em Gerar token de acesso, escolha o número de teste no campo De, adicione o seu celular no campo Para e clique em Enviar mensagem.

O número de teste é criado e registrado pela Meta automaticamente quando você segue o guia de introdução. Anote dois valores que aparecem nessa tela, porque todas as chamadas usam: o ID do número de telefone (Phone Number ID) e o ID da conta do WhatsApp Business.

Quando a mensagem chegar no seu celular, responda. A sua resposta abre a janela de atendimento de 24 horas, e só dentro dela a empresa pode mandar mensagem sem template.

Token temporário ou token de usuário do sistema: qual usar?

O token do botão Gerar token de acesso é um token de usuário: serve para o primeiro teste e expira em poucas horas. Para o seu sistema, crie um usuário do sistema nas configurações do negócio e gere um token com as permissões do WhatsApp. A Meta indica esse tipo para quem acessa só os dados da própria empresa.

Para gerar o token de usuário do sistema:

1. Abra as Configurações do negócio e clique em Usuários do sistema.
2. Clique em Adicionar e crie o usuário do sistema.
3. Em Atribuir ativos, dê ao usuário o seu app com Gerenciar app e a sua conta do WhatsApp com Gerenciar contas do WhatsApp Business, as duas em Controle total.
4. Clique em Gerar token, escolha o app, a validade e as permissões business_management, whatsapp_business_messaging e whatsapp_business_management.
5. Copie o token e guarde num cofre de segredos, nunca no código.

O token vai no header de toda chamada, como Authorization: Bearer seguido do token. A Meta pede para tratar o token como texto opaco: não decodifique e guarde num campo sem tamanho fixo. Com ele, o envio de texto dentro da janela é um POST como este:

POST https://graph.facebook.com/v25.0/<PHONE_NUMBER_ID>/messages

{"messaging_product": "whatsapp", "to": "<NUMERO>", "type": "text", "text": {"body": "Olá!"}}

Passo 3: como criar o endpoint e passar na verificação do webhook?

O endpoint precisa aceitar GET e POST em HTTPS. Ao salvar a URL no painel, a Meta manda um GET com hub.mode, hub.challenge e hub.verify_token. Se o hub.verify_token bater com a string que você escolheu, responda HTTP 200 com o valor de hub.challenge no corpo. Qualquer outra resposta deixa o webhook sem verificação.

Em Express, a rota de verificação cabe numa linha:

if (q["hub.verify_token"] === VERIFY_TOKEN) return res.status(200).send(q["hub.challenge"]);

Com o endpoint no ar, vá ao Painel de Apps, Casos de uso, Personalizar, Configuração (em apps criados com o caso de uso "Conectar-se com clientes pelo WhatsApp"; nos demais, WhatsApp, Configuração). Preencha o campo URL de retorno de chamada com o endereço do endpoint e o campo Verificar token com a sua string. Se a verificação passar, o painel salva e mostra a lista de campos para assinar.

Como validar a assinatura X-Hub-Signature-256?

Todo POST da Meta traz o header X-Hub-Signature-256 com sha256= seguido do HMAC-SHA256 do corpo, calculado com a chave secreta do app. Calcule o mesmo hash sobre o corpo cru, antes de qualquer parse de JSON, compare com o valor do header e só processe se bater. Se não bater, responda com erro e descarte.

Em Node.js:

const esperado = crypto.createHmac("sha256", APP_SECRET).update(corpoCru).digest("hex");

Compare esperado com o que vem depois de sha256= usando crypto.timingSafeEqual, que evita vazar a assinatura pelo tempo de resposta. Ela exige buffers do mesmo tamanho, então confira o tamanho antes. A chave secreta fica nas configurações básicas do app e não pode ir para o front nem para o repositório.

Se o seu framework já transformou o corpo em objeto, o hash não bate: configure a rota do webhook para receber o corpo como texto ou buffer.

Quais campos do webhook assinar?

Para receber mensagens e status de envio, assine o campo messages: ele traz o que o cliente manda e cada mudança de status do que você enviou. Os outros campos cobrem templates, qualidade do número, limites e alertas da conta. Assine só os que o seu sistema trata, para não processar evento que ninguém usa.

O campo messages depende da permissão whatsapp_business_messaging; os demais, de whatsapp_business_management. Cada POST pode trazer até 3 MB e agrupar várias atualizações. Um detalhe que derruba muita gente: a Meta avisa que alguns webhooks não são enviados com o app em modo de desenvolvimento. Para produção, publique o app.

O que a Meta faz quando o seu webhook falha?

Se o endpoint não responder 200, a Meta tenta de novo na hora e depois com frequência decrescente por até 7 dias, e então descarta. Os reenvios podem chegar duplicados, então deduplique pelo id da mensagem. E não existe API para buscar webhooks antigos: o que você não gravou na hora não volta.

O desenho que aguenta produção é simples de explicar e trabalhoso de manter: o endpoint confere a assinatura, grava o evento numa tabela com o id como chave única, responde 200 e deixa o processamento para uma fila. Assim um fluxo lento não estoura o tempo de resposta e um reenvio da Meta não vira ação repetida. Quando o problema é o evento que não chega, os diagnósticos estão em webhook do WhatsApp Cloud API.

Como levar a configuração para produção?

Troque o número de teste por um número comercial seu, registrado na Cloud API e com nome de exibição. Use o token de usuário do sistema, publique o app, mantenha o endpoint próprio no ar e deixe um meio de pagamento na conta do WhatsApp Business. Sem verificação da empresa, o portfólio começa falando com 250 pessoas novas por dia.

• Número: seu, com código de país e de área, recebendo SMS ou ligação, e fora do WhatsApp comum. Adicionar pela Configuração da API confirma que o número é seu, mas o registro na Cloud API se completa com POST /<PHONE_NUMBER_ID>/register, enviando messaging_product e um pin.
• Nome de exibição: obrigatório no registro; a Meta verifica o nome quando o número sobe de limite.
• Limites: 250 pessoas diferentes em 24 horas fora da janela, por portfólio, e até 2 números registrados. Verificar a empresa é um dos caminhos para 2 mil pessoas e 20 números.
• Custo: a Meta cobra por mensagem entregue; no Brasil, desde 1º de outubro de 2026, R$ 0,035 para utilidade e autenticação e R$ 0,3217 para marketing. A resposta de atendimento (serviço) tem 1.000 grátis por número por mês e custa R$ 0,035 da 1.001ª em diante.

Um aviso antes de investir no caminho direto: a Meta não permite selecionar no Cadastro Incorporado uma conta do WhatsApp Business criada pelo app de desenvolvedor. Se depois você quiser levar o número para um hub, essa conta não entra pelo fluxo de conexão dele. E a coexistência com o app do celular não existe para desenvolvedor direto: a Meta só a oferece por Tech Provider ou Solution Partner.

Existe um jeito mais rápido de configurar a Cloud API?

Existe. Tudo o que este guia montou à mão, o Omnique entrega pronto. Você conecta o número pelo Cadastro Incorporado dentro do painel, sem criar app nem gerar token. A URL que a Meta chama, o token de verificação e a conferência da X-Hub-Signature-256 são configurados sozinhos. Você só informa para onde os eventos vão.

O custo é R$ 50 por número por mês de 1 a 4 números, sem taxa de ativação, e a mensagem você continua pagando direto à Meta. Veja o passo a passo com o Omnique, a tabela em preços ou teste grátis por 3 dias, sem cartão. Para comparar todos os caminhos, volte ao guia da API oficial do WhatsApp.