API do WhatsApp

Documentação interna para desenvolvedores. Esta página aborda a integração da API do WhatsApp Business: ciclo de vida da sessão, arquitetura de webhook e padrões de roteamento. Não se destina a usuários finais.

​

Mapa de rotas

​

Visão geral da arquitetura

WhatsApp Business API (Meta)
        ↓ (webhook POST)
/api/whatsapp/webhook
        ↓
Message routing middleware
        ↓
┌─────────────────────────────┐
│ AI Employee handles message │
│   (via @zappway/lib/...    │
│    conversation engine)     │
└─────────────────────────────┘
        ↓ (if AI replies)
Send message via WABA API

​

Ciclo de vida da sessão

​

1. Emparelhamento (código QR ou número de telefone)

POST /api/whatsapp/create-session
  → Initializes WhatsApp session
  → Returns session token

GET /api/whatsapp/qr-code?sessionId=...
  → Returns QR code as image/JSON
  → Frontend polls until scanned or expired

POST /api/whatsapp/start-pairing { phoneNumber }
  → Initiates WhatsApp phone number pairing
  → Returns pairing code

​

2. Estados de sessão

​

3. Desconecte

// POST /api/whatsapp/disconnect { sessionId }
// Gracefully terminates WhatsApp session
// Marks session as disconnected in DB

​

Processamento de eventos de webhook

• URL HTTPS público
• Verificado com o handshake desafio-resposta do Meta

const signature = req.headers.get('x-hub-signature-256');
// Verify using HMAC-SHA256 with WHATSAPP_APP_SECRET

​

Atribuição de agente

// POST /api/whatsapp/assign { sessionId, agentId }
// Associates a WhatsApp session with a specific AI Employee
// From that point, all incoming messages go to that agent

​

Resolução de conversa

// POST /api/whatsapp/resolve { conversationId }
// Marks conversation as resolved in ZappWay
// Does NOT send any message to WhatsApp

​

Retorno de chamada Meta OAuth

User clicks "Connect WhatsApp" in settings
→ Redirect to Meta OAuth
→ Meta redirects to GET /api/whatsapp/callback?code=...&state=...
→ Server exchanges code for access token
→ Token stored encrypted in DB
→ Redirect to dashboard

​

Variáveis ​​de ambiente necessárias

​

Problemas conhecidos/pegadinhas

• Reentrega do webhook: Meta tenta novamente a entrega do webhook se o seu servidor retornar diferente de 2xx. Garanta o processamento de mensagens idempotentes usando whatsapp_message_id como chave de desduplicação.
• Expiração da sessão: As sessões do WhatsApp (para números pessoais via API não oficial) expiram após 20 dias de inatividade. As sessões da Business API não expiram, mas os números de telefone podem ser desconectados.
• Pesquisa de código QR: O código QR tem vida curta (cerca de 60 segundos). O front-end deve ser regenerado se expirar antes da verificação.
• Limites de taxas: A API do WhatsApp Business impõe limites de taxas por número de telefone para mensagens enviadas. Monitore erros 131056 (limite de taxa de spam).
• Janela de mensagens de 24 horas: As empresas só podem enviar mensagens proativamente aos usuários que enviaram mensagens nas últimas 24 horas (sem modelos pré-aprovados).