WhatsApp API Routes

Documentação de todas as rotas em /api/whatsapp/**.

---

POST /api/whatsapp/connect

Descrição: Inicia o fluxo de Facebook Embedded Signup para conectar um número WhatsApp.

Response:

• 200: { data: { url: string } }
• 403: Plano inativo ou limite de números atingido

Notas: Verifica plano ativo e limite de números. State no cookie: accountId:randomHex.

---

GET /api/whatsapp/callback

Descrição: Callback do Facebook Embedded Signup. Pipeline completo em 7 steps:

1. Troca code por short-lived token
2. Troca por long-lived token (60 dias)
3. Extrai WABA IDs e phone numbers
4. Registra número na Cloud API
5. Inscreve app nos webhooks da WABA
6. Verifica subscription
7. Salva perfil com token criptografado

Response:

• HTML com postMessage para o popup opener

---

POST /api/whatsapp/send

Descrição: Envia uma mensagem WhatsApp via conversa existente. Rate Limit: Preset “send”

Request:

• Body: { conversation_id, content: { type, body?, media_url?, template_name?, template_params? } }

Response:

• 200: { data: Message }
• 404: Conversa/Perfil/Contato não encontrado

---

POST /api/whatsapp/test-send

Descrição: Envia um template de teste. Admin-only.

Request:

• Body: { templateName, to, language?, variables?, accountId? }

---

GET /api/whatsapp/webhook

Descrição: Verificação do webhook Meta (challenge/response). Auth: Public

Response:

• 200: Retorna hub.challenge como texto plano
• 403: Verificação falhou

---

POST /api/whatsapp/webhook

Descrição: Recebe TODOS os eventos WhatsApp do Meta. Endpoint principal. Auth: Public (HMAC SHA-256) Rate Limit: 100/min por IP

Processamento:

Mensagens recebidas: Upsert contato, busca/cria conversa, insere mensagem, emite evento, dispara trigger message_received, aciona chatbot IA.

Status updates: Atualiza status (sent/delivered/read/failed), emite eventos correspondentes.

Template status updates: Atualiza meta_status, dispara trigger template_status_changed, cria notificação.

---

POST /api/whatsapp/webhook-test

Descrição: Envia webhook de teste para verificar pipeline end-to-end.

Request:

• Body: { mode?: "signature_only" | "full" }

Response:

• 200: { test, mode, webhook_url, latency_ms, hmac_valid, pipeline_ok, db_check }

---

GET /api/whatsapp/diagnose

Descrição: Diagnostica problemas de conexão. Verifica token, subscriptions e status do número.

Response:

• 200: { profiles: ProfileDiagnosis[], app_webhook_subscriptions }

---

POST /api/whatsapp/diagnose

Descrição: Repara subscriptions (reinscreve app e re-registra número).

Response:

• 200: { repaired: RepairResult[] }

---

GET /api/whatsapp/profiles

Descrição: Lista todos os perfis WhatsApp da conta.

Response:

• 200: { data: WhatsAppProfile[] }

Notas: Não retorna access_token_encrypted.

---

DELETE /api/whatsapp/profiles/[id]

Descrição: Desconecta e remove um perfil WhatsApp. Revoga token no Facebook. Audit: delete whatsapp_profile

Response:

• 204: No Content