Como integrar a API do WhatsApp Business: tutorial passo a passo

A API oficial do WhatsApp Business permite que sistemas enviem e recebam mensagens por meio da plataforma da Meta. Ela não deve ser confundida com automação do WhatsApp Web. Uma integração confiável exige conta empresarial, número configurado, permissões, webhooks verificados, templates aprovados e tratamento de consentimento.

Resposta direta

Crie ou use uma conta Meta for Developers, adicione o produto WhatsApp, associe o portfólio empresarial e o número, gere credenciais apropriadas no servidor, envie uma mensagem de teste pela Graph API, configure um endpoint HTTPS para webhook, valide o desafio, verifique a assinatura dos eventos e modele estados de envio, resposta e erro.

1. Prepare contas e ativos

Você precisará de acesso administrativo aos ativos empresariais, um aplicativo na Meta e um número elegível. Para produção, revise verificação empresarial, nome de exibição e método de pagamento conforme exigido no painel. As telas e requisitos podem mudar; siga o painel e a documentação oficial atual.

Não use número pessoal importante em testes sem entender a migração. Comece com os recursos de teste oferecidos pela plataforma.

2. Proteja o token

O token é uma credencial de servidor. Nunca o coloque em JavaScript enviado ao navegador, aplicativo móvel, print ou repositório. Armazene-o em variável de ambiente ou cofre de segredos e conceda apenas permissões necessárias.

Exemplo de variáveis:

WHATSAPP_PHONE_NUMBER_ID=...
WHATSAPP_ACCESS_TOKEN=...
WHATSAPP_VERIFY_TOKEN=segredo-definido-por-voce
WHATSAPP_APP_SECRET=...

O verify token é escolhido por você para confirmar a configuração do webhook; ele não substitui a verificação criptográfica da assinatura recebida.

3. Envie uma mensagem de teste

Use a versão atual da Graph API indicada no painel:

curl -X POST "https://graph.facebook.com/VERSAO/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "55DDDNUMERO",
    "type": "template",
    "template": {"name": "hello_world", "language": {"code": "en_US"}}
  }'

Não copie versão, ID ou token de tutorial antigo. Registre o ID da mensagem retornado e acompanhe seus status posteriores pelo webhook.

4. Configure o webhook

O endpoint precisa ser público e HTTPS. Na verificação inicial, a Meta envia parâmetros de desafio. Compare o token e devolva o desafio quando válido. Depois, eventos chegam por POST.

Fluxo recomendado:

receber -> validar assinatura -> registrar ID -> responder 200 rápido
       -> enfileirar -> processar -> atualizar conversa/status

Valide X-Hub-Signature-256 usando HMAC SHA-256 com o app secret e o corpo bruto. Faça comparação resistente a timing. Rejeite assinatura inválida. O framework não deve modificar o corpo antes da verificação.

5. Garanta idempotência

Webhooks podem ser repetidos. Armazene o identificador único do evento ou mensagem e não processe novamente o mesmo efeito. Responda rapidamente e mova regras demoradas para fila. Mantenha dead-letter e retentativa com limite.

6. Entenda janela e templates

Mensagens iniciadas pela empresa normalmente usam templates aprovados. Dentro da janela de atendimento aberta por interação do usuário, outras mensagens podem ser permitidas conforme as regras atuais. Categorias, preços, limites e políticas mudam; consulte a documentação oficial antes de desenhar custo e operação.

Um template deve ser claro e corresponder ao uso aprovado. Não transforme mensagem transacional em marketing disfarçado. Registre idioma, versão e variáveis para que mudanças sejam auditáveis.

7. Modele estados

Não marque uma mensagem como entregue apenas porque o POST retornou sucesso. Modele ao menos:

Guarde o payload mínimo necessário e defina retenção. Relacione cada mensagem à conversa e ao tenant correto.

8. Trate consentimento e atendimento

Colete opt-in claro para a finalidade, ofereça saída e respeite preferências. Não importe listas sem base operacional. Oriente atendentes sobre transferência, horário, histórico e dados sensíveis. A LGPD exige finalidade, transparência e segurança proporcionais; consulte orientação jurídica para seu caso.

9. Monitore erros e qualidade

Registre request ID, código normalizado, template, destino mascarado e latência, nunca token completo. Crie alertas para aumento de falhas, webhook sem eventos, fila acumulada e credencial perto de expirar. Um painel deve separar aceitação, entrega e leitura.

O artigo integração via API explica o desenho geral, e automatização de integrações mostra controles contra erros manuais.

Checklist de produção

• ativos pertencem à conta da empresa;
• token fora do cliente e do repositório;
• webhook HTTPS e assinatura validada;
• eventos idempotentes e processados em fila;
• templates e idiomas versionados;
• opt-in e saída registrados;
• logs sem dados e segredos excessivos;
• alertas e painel de status ativos;
• política e preço revisados na documentação atual;
• procedimento de rotação e incidente documentado.

Perguntas frequentes

Posso usar uma biblioteca que controla WhatsApp Web?

Isso não equivale à API oficial e pode criar riscos de estabilidade e política. Para operação empresarial, use a plataforma oficial.

O retorno 200 significa que a mensagem foi entregue?

Não. Ele informa aceitação da requisição; entrega é confirmada por eventos de status.

Fontes primárias

• Meta: documentação da WhatsApp Cloud API
• Meta: webhooks da plataforma
• Meta: visão geral de templates