Pular para o conteúdo principal

📱 WhatsApp Cloud API

O WhatsApp é conectado via API Cloud da Meta — a API oficial, disponível no nível gratuito, que permite enviar e receber mensagens do WhatsApp a partir do seu próprio servidor. Nenhum BSP (Provedor de Soluções Empresariais) terceirizado é necessário.

Pré-requisitos​

  1. Uma conta de desenvolvedor Meta em developers.facebook.com
  2. Uma Conta Meta Business (também conhecida como Business Manager)
  3. Um número de telefone para WhatsApp que não esteja registrado no WhatsApp pessoal (você pode usar um SIM, um número virtual ou um telefone fixo)

Passos de Configuração​

1. Criar um App Meta​

  1. Acesse developers.facebook.com/apps
  2. Clique em Create App
  3. Escolha o tipo Business
  4. Preencha um nome e conecte sua Conta Business

2. Adicionar o Produto WhatsApp​

  1. No painel do seu app, role até Add Products to Your App
  2. Clique em Set Up no WhatsApp
  3. Selecione sua Conta Business

3. Obter Suas Credenciais​

Navegue até WhatsApp → API Setup no painel do seu app:

CredencialOnde Encontrar
Phone Number IDListado na seção "From" — um ID numérico como 123456789012345
Access TokenO token temporário mostrado nesta página. Para produção, gere um token permanente via System Users.
App SecretPainel do App → Settings → Basic → App Secret
Verify TokenUma string que você inventa — qualquer string aleatória, ex. my_secret_verify_token_2024

4. Adicionar o Canal no PulseHub​

  1. Vá para Canais → Adicionar Canal
  2. Selecione WhatsApp
  3. Preencha os quatro campos
  4. Clique em Salvar Canal
  5. Copie a URL do Webhook mostrada no cartão do canal

5. Configurar o Webhook na Meta​

  1. No seu app Meta, vá para WhatsApp → Configuration
  2. Clique em Edit ao lado da seção Webhook
  3. Callback URL: cole sua URL de webhook do PulseHub
  4. Verify Token: insira a mesma string que colocou no PulseHub
  5. Clique em Verify and Save

A Meta fará uma requisição GET para sua URL de webhook com ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=.... O PulseHub verifica o token e retorna o challenge.

  1. Em Webhook Fields, inscreva-se em: messages

6. Testar​

Envie uma mensagem WhatsApp para seu número comercial. Ela deve aparecer como uma nova conversa na caixa de entrada do PulseHub em segundos.

Verificação de Assinatura​

A Meta inclui um header X-Hub-Signature-256 em cada webhook:

X-Hub-Signature-256: sha256=abc123...

O PulseHub verifica usando HMAC-SHA256 com seu App Secret. Se a verificação falhar, o webhook retorna 401 Signature mismatch.

Envio de Mensagens​

Quando um agente envia uma resposta pela caixa de entrada, o PulseHub chama a API do WhatsApp Cloud:

POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
  "messaging_product": "whatsapp",
  "to": "{recipient_phone}",
  "type": "text",
  "text": {"body": "Sua resposta aqui"}
}

Acesso à Produção​

O app Meta padrão está em modo Development — só pode enviar mensagens para números adicionados como números de teste. Para ir ao ar:

  1. Complete a Verificação de Negócio no Meta Business Manager
  2. Envie seu caso de uso do WhatsApp para revisão da Meta
  3. Uma vez aprovado, seu app obtém acesso para enviar mensagens a todos os usuários do WhatsApp

Problemas Comuns​

SintomaCausa Provável
Verificação falha durante a configuração do webhookO verify_token no PulseHub não corresponde ao que você inseriu na Meta
Erro de incompatibilidade de assinatura nos logsapp_secret incorreto — copie de App Settings → Basic, não de API Setup
Mensagens não chegamO campo de webhook messages não está inscrito no painel da Meta
Invalid phone number ao enviarO formato do número deve ser E.164 sem + (ex. 15551234567)
Erro de app em modo DevelopmentApenas números de teste verificados podem receber mensagens no modo dev