Como integrar o WhatsApp ao seu sistema: passo a passo com a API oficial

Integrar o WhatsApp deixou de ser gambiarra de QR Code: a Cloud API oficial é gratuita para começar e bem documentada. Este guia mostra o passo a passo real — e onde ele costuma travar.

Antes de começar: o que você vai precisar

• Conta no Meta for Developers e um portfólio de negócios (Business Manager)
• Um número de telefone dedicado, que não esteja registrado no app do WhatsApp
• Uma aplicação sua com URL pública HTTPS para receber webhooks

Passo 1 — Criar o app na Meta

No painel do Meta for Developers, crie um app escolhendo o caso de uso "Connect with customers through WhatsApp". O assistente vincula o app ao seu portfólio de negócios e cria automaticamente um número de teste com uma WABA de testes — você pode enviar mensagens para até 5 números cadastrados antes de ter número próprio.

Passo 2 — Enviar a primeira mensagem

Na seção API Setup, copie o token temporário e o PHONE_NUMBER_ID e faça a primeira chamada:

curl -X POST "https://graph.facebook.com/v25.0/SEU_PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Olá! Primeira mensagem via API oficial." }
  }'

Dois detalhes que causam metade dos erros de iniciante: o campo to usa o formato E.164 sem o sinal de mais (ex.: 5511999999999), e a resposta "message_status": "accepted" significa apenas que a Meta aceitou a mensagem — a confirmação de entrega chega depois, via webhook.

Passo 3 — Trocar o token temporário por um definitivo

O token do painel expira em 24 horas. Para produção, crie um System User no Business Manager, atribua o app e a WABA a ele e gere um token de longa duração com as permissões whatsapp_business_messaging e whatsapp_business_management. Integração que "parou de funcionar no dia seguinte" quase sempre é token temporário esquecido.

Passo 4 — Configurar o webhook

Sem webhook, sua integração é surda: você envia, mas não recebe respostas nem status de entrega. A configuração exige uma URL HTTPS que responda ao desafio de verificação da Meta e valide a assinatura das notificações — o processo completo está no nosso guia de webhook do WhatsApp.

Passo 5 — Registrar número próprio e templates

Com o fluxo validado no número de teste:

1. Registre seu número definitivo na WABA e aprove o display name
2. Faça a verificação da empresa para subir o limite de 250 para 2.000 conversas/dia
3. Crie templates para iniciar conversas fora da janela de 24 horas — mensagens livres só podem ser enviadas quando o cliente fala primeiro

A aprovação de templates é majoritariamente automática (minutos a 24h), mas a categoria precisa estar correta: template promocional cadastrado como "utilidade" é o motivo número 1 de rejeição.

Integração direta vs. plataforma: qual escolher

A regra prática: se o WhatsApp é parte do seu produto (um SaaS que notifica usuários, por exemplo), integre direto na API da Meta. Se o WhatsApp é o seu canal de vendas e atendimento, uma plataforma resolve em dias o que levaria meses — a Wizebot faz a aprovação assistida da conta na API oficial e ainda expõe webhooks e API própria com integrações prontas para Hotmart, Shopify, Pipedrive, Google Sheets e mais de 50 plataformas.

Perguntas frequentes

Integrar o WhatsApp é acessível — o que consome tempo é transformar a API crua em operação de atendimento e vendas. Se essa é a sua necessidade, a Wizebot entrega a API oficial integrada, com IA, CRM e campanhas funcionando desde o primeiro dia.