Meta WhatsApp Cloud API

Integração oficial com a API de mensagens do WhatsApp via Meta Business Platform (também chamada de WABA — WhatsApp Business API).

Quando é usada

A Meta Cloud API é usada para:

• Envio de campanhas com templates aprovados
• Recebimento de mensagens via webhook
• Gerenciamento de templates (criar, editar, monitorar status)

Diferente do Evolution API, a WABA é a integração oficial, escalável e habilitada para volumes altos.

Credenciais

Variável	Descrição
accessToken	Bearer token — criptografado no banco (StoreWhatsappNumber.accessToken)
appSecret	Meta App Secret — valida HMAC dos webhooks recebidos
phoneNumberId	ID do número no Meta Dashboard
wabaId	WhatsApp Business Account ID
webhookVerifyToken	Token para validação inicial do webhook (SHA-256 no banco)

Webhooks recebidos

O backend expõe POST /webhooks/whatsapp/meta para receber eventos da Meta.

Verificação de segurança:

// Validação HMAC do payload
const signature = req.headers['x-hub-signature-256'];
const expected = crypto.createHmac('sha256', appSecret)
  .update(rawBody)
  .digest('hex');
// Comparação timing-safe

Eventos tratados:

Evento	Ação
message (inbound)	Cria/atualiza conversa no banco + repassa ao Chatwoot
message_template_status_update	Atualiza status do template no banco
Status updates (delivered, read, failed)	Atualiza WhatsappMessage.status

Envio de mensagens

O envio acontece via fila BullMQ whatsapp-send. O processor chama:

POST https://graph.facebook.com/v22.0/{phoneNumberId}/messages
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "nome_do_template",
    "language": { "code": "pt_BR" },
    "components": [...]
  }
}

Templates

Templates devem ser aprovados pela Meta antes do uso. Processo:

1. Criar template no CRM (POST /whatsapp/templates)
2. CRM envia para Meta via Graph API
3. Meta retorna metaTemplateId e status PENDING
4. Aprovação via webhook (message_template_status_update) → status muda para APPROVED
5. Template disponível para campanhas

Status possíveis: PENDING → APPROVED | REJECTED | DISABLED | PAUSED

Regra de edição: Template APPROVED pode ser editado, mas vai para status DRAFT localmente (hasDraftChanges = true). O novo envio à Meta cria versão pendente de reaprovação.

Tiers de envio

Tier	Limite diário
TIER_50	50 conversas
TIER_250	250 conversas
TIER_1K	1.000 conversas
TIER_10K	10.000 conversas
TIER_100K	100.000 conversas
UNLIMITED	Sem limite

O tier atual fica em StoreWhatsappNumber.messagingLimitTier e é atualizado via webhook.

Regra das 24 horas

Mensagens de texto livre (fora de template) só podem ser enviadas dentro de uma janela de 24 horas após a última mensagem do cliente. Fora dessa janela, é obrigatório usar template.

Ver Regras WhatsApp para detalhes completos.

Configuração no Meta Business Manager

1. Meta for Developers → criar App com produto "WhatsApp"
2. WhatsApp → configurar número → copiar phoneNumberId e wabaId
3. Webhooks → apontar para https://apicrm.galdix.com.br/webhooks/whatsapp/meta
   • Campos: messages, message_template_status_update, messaging_postbacks
   • hub.verify_token: valor de webhookVerifyToken
4. Token de acesso: gerar token permanente (não expira) e salvar criptografado

Preços

Cobrado por conversa (janela de 24h), não por mensagem. Tarifas por categoria e país ficam em WhatsappPricingRate. O sistema calcula e acumula o custo em CampaignMetric.cost.