# WhatsApp Setup — CRM de Conversas + Créditos + Automações

Guia end-to-end do subsistema de WhatsApp do AgenciaPSI. Cobre **WhatsApp Pessoal** (Evolution, gratuito), **WhatsApp Oficial AgenciaPSI** (Twilio com créditos), **Asaas** (gateway de pagamento), e todas as automações (auto-reply, lembretes, opt-out, tags, notas).

---

## 🎯 Arquitetura

### Dois provedores, escolha exclusiva por tenant

```
┌─────────────────────────────────────────────────┐
│  Tenant escolhe 1 canal em /configuracoes/whatsapp │
└─────────────────────────────────────────────────┘
         │                            │
         ▼                            ▼
┌────────────────────┐    ┌──────────────────────┐
│ WhatsApp Pessoal   │    │ WhatsApp Oficial     │
│ (Evolution)        │    │ AgenciaPSI (Twilio)  │
│                    │    │                       │
│ • Gratuito          │    │ • Consome créditos   │
│ • QR code            │    │ • API oficial Meta   │
│ • Celular real       │    │ • Zero ban risk      │
│ • Docker self-host   │    │ • Cloud gerenciado   │
│ • Tier free do SaaS  │    │ • Tier pago do SaaS  │
└────────────────────┘    └──────────────────────┘
         │                            │
         └───────────┬────────────────┘
                     ▼
         ┌─────────────────────────┐
         │   Edge Functions         │
         │                           │
         │ • send-whatsapp-message   │ ← rota por provider
         │ • send-session-reminders  │ ← idem
         │ • evolution-whatsapp-inbound (auto-reply, opt-out)
         │ • twilio-whatsapp-inbound (⚠ sem auto-reply ainda)
         │ • create-whatsapp-credit-charge (Asaas PIX)
         │ • asaas-webhook (credita saldo)
         └─────────────────────────┘
                     │
                     ▼
         ┌─────────────────────────┐
         │       PostgreSQL         │
         │                           │
         │ conversation_messages    │
         │ conversation_notes       │
         │ conversation_tags        │
         │ conversation_optouts     │
         │ conversation_autoreply_* │
         │ session_reminder_*       │
         │ whatsapp_credits_*       │
         │ whatsapp_credit_packages │
         └─────────────────────────┘
```

### Dedução de créditos

```
Usuário envia pelo drawer / lembrete dispara / auto-reply
     ↓
Edge function detecta provider do canal ativo
     ↓
  Evolution?              Twilio?
     ↓                       ↓
  Envia direto          deduct_whatsapp_credits(1) ← atômico, lock, valida saldo
     ↓                       ↓
  Registra msg       ┌──── OK ────┐      ┌── insufficient ──┐
                     ↓               ↓
                 send Twilio       return 402
                     ↓
              ┌── ok ──┐   ┌── fail ──┐
              ↓           ↓
          Registra   add_whatsapp_credits(1, 'refund')
           msg
```

---

## 🔧 Setup completo (dev local)

### 1. Supabase local + edge functions

```bash
# Subir stack Supabase local (Postgres + Auth + Storage + etc)
npx supabase start

# Em outro terminal: rodar edge functions
supabase functions serve --no-verify-jwt --env-file supabase/functions/.env
```

**Funções carregadas:**

| Função | URL | Uso |
|---|---|---|
| `evolution-whatsapp-inbound` | `?tenant_id=<uuid>` | Webhook Evolution: inbound msgs + auto-reply + opt-out |
| `evolution-webhook-provision` | — | Configura webhook na Evolution |
| `twilio-whatsapp-inbound` | `?tenant_id=<uuid>` | Webhook Twilio (inbound only; sem auto-reply ainda) |
| `send-whatsapp-message` | — | Envio unificado: detecta provider, deduz crédito se Twilio |
| `send-session-reminders` | — | Cron/manual: dispara lembretes 24h e 2h antes |
| `create-whatsapp-credit-charge` | — | Cria PIX Asaas pra compra de créditos |
| `asaas-webhook` | — | Recebe eventos Asaas e credita saldo |
| `deactivate-notification-channel` | — | Desativa canal (usado ao trocar provider) |

**Flag `--no-verify-jwt`:** necessária porque webhooks externos (Twilio, Evolution, Asaas) não mandam JWT.

### 2. Evolution API (WhatsApp Pessoal — tier gratuito)

```bash
# Subir Evolution + Postgres + Redis
docker compose -f evolution-api/docker-compose.yml up -d

# Verificar status
docker ps --filter name=evolution_api
```

Evolution roda em `http://localhost:8080` com API key `minha_chave_123` (ver `evolution-api/docker-compose.yml`).

### 3. Asaas (pagamentos — tier pago)

Ativa só em prod ou quando quiser testar compra de créditos end-to-end.

**Passo 1 — Criar conta sandbox:**
1. https://sandbox.asaas.com (gratuito, CPF qualquer)
2. Menu → Integrações → Integrações Avançadas → API → copia a API key (começa com `$aact_...`)

**Passo 2 — Configurar env:**

Edita `supabase/functions/.env`:
```env
ASAAS_API_KEY=$aact_sua_chave_aqui
ASAAS_API_URL=https://sandbox.asaas.com/api/v3
ASAAS_WEBHOOK_TOKEN=                  # opcional, pra autenticar webhook
```

**Passo 3 — Reiniciar functions serve:**
```bash
# Ctrl+C no terminal do serve
supabase functions serve --no-verify-jwt --env-file supabase/functions/.env
```

**Passo 4 — (Opcional) Expor webhook via ngrok pro Asaas alcançar:**
```bash
# Outro terminal
ngrok http 54321
# Copia a URL (ex: https://abc123.ngrok.app)
```

Configura no Asaas:
- Dashboard → Integrações → Webhooks → **Adicionar**
- URL: `https://abc123.ngrok.app/functions/v1/asaas-webhook`
- Eventos: marca **Cobranças** (PAYMENT_RECEIVED, PAYMENT_CONFIRMED, PAYMENT_OVERDUE, PAYMENT_DELETED, PAYMENT_REFUNDED)
- Token (opcional): cadastra o mesmo valor de `ASAAS_WEBHOOK_TOKEN`

**Em produção:**
```bash
supabase secrets set ASAAS_API_KEY="$aact_prod_key"
supabase secrets set ASAAS_API_URL="https://api.asaas.com/v3"
supabase secrets set ASAAS_WEBHOOK_TOKEN="token_seguro"
```

Webhook da prod aponta pro URL real do Supabase cloud (sem ngrok).

---

## 📋 Features & como testar

### A. Envio manual via drawer

**Onde:** drawer de qualquer conversa (clica no card do Kanban em `/therapist/conversas`)

**Fluxo:**
1. Compose no drawer → `store.sendMessage()` → chama `send-whatsapp-message` edge function
2. Function detecta provider ativo em `notification_channels`
3. Evolution: envia direto via `/message/sendText/{instance}`
4. Twilio: `deduct_whatsapp_credits(1)` → se OK envia via Twilio API → se falhar, refunda
5. Registra em `conversation_messages` (direction=outbound, delivery_status=sent/queued)

**Testar sem Twilio real** (valida dedução + rollback):
- Topup 100 créditos via SQL (ver seção 🧪 mais abaixo)
- Criar canal Twilio fake via SQL
- Enviar msg → deduz, tenta enviar, falha com 401, refunda → saldo volta ao original

### B. Lembretes automáticos de sessão (2.4)

**Onde:** `/configuracoes/lembretes-sessao`

**Config:**
- Toggle on/off
- Ativa lembretes 24h e/ou 2h antes da sessão
- Templates com variáveis: `{{nome_paciente}}`, `{{data_sessao}}`, `{{hora_sessao}}`, `{{modalidade}}`, `{{nome_clinica}}`
- Quiet hours (default 22h-8h SP)
- Respeitar opt-out (LGPD — recomendado ON)

**Como dispara:**
- Cron hit `send-session-reminders` a cada 15min (pg_cron comentado na migration; em prod configure via Supabase Dashboard → Database → Cron Jobs)
- Em dev: botão **"Testar agora"** na página dispara manualmente

**Query do worker:** busca `agenda_eventos` com `status='agendado'` dentro de:
- Janela 24h: `inicio_em` entre `now+23h45min` e `now+24h15min`
- Janela 2h: `inicio_em` entre `now+1h45min` e `now+2h15min`

**Anti-dup:** UNIQUE `(event_id, reminder_type)` no `session_reminder_logs`.

**Testar:**
```sql
-- Cria evento daqui a ~2h (no horário de SP)
-- Pelo UI da agenda é mais fácil; via SQL:
INSERT INTO agenda_eventos (tenant_id, owner_id, patient_id, inicio_em, fim_em, status, modalidade, tipo, titulo)
VALUES (
  '<tenant>',
  '<user>',
  (SELECT id FROM patients WHERE tenant_id='<tenant>' LIMIT 1),
  now() + interval '2 hours',
  now() + interval '3 hours',
  'agendado',
  'presencial',
  'session',
  'Teste lembrete'
);
```
Depois clica **"Testar agora"** em `/configuracoes/lembretes-sessao`.

### C. Auto-reply fora do horário (2.3)

**Onde:** `/configuracoes/conversas-autoreply`

**Config:**
- Toggle on/off + mensagem + cooldown (minutos entre auto-replies pra mesma thread)
- 3 modos:
  - **Seguir agenda** — usa `agenda_regras_semanais` dos membros ativos do tenant
  - **Horário de funcionamento** — janela semanal editável (armazena em JSONB `business_hours`)
  - **Custom** — janela específica pro auto-reply (`custom_window`)

**Como dispara:**
- Webhook Evolution `evolution-whatsapp-inbound` recebe msg
- Depois de inserir msg, chama `maybeSendAutoReply()`
- Checa: enabled, não está em horário útil, não está em cooldown
- Se OK → envia via Evolution (futuro: rotear pra Twilio se provider='twilio')

**⚠ Limitação:** atualmente **só funciona com Evolution**. Pra Twilio precisa implementar a mesma lógica em `twilio-whatsapp-inbound` (dívida técnica).

**Testar:**
- Ativa feature + define janela custom (ex: seg-sex 9h-18h)
- Fora dessa janela, paciente manda msg → chega no inbox + auto-reply é enviado de volta em ~1s

### D. Opt-out LGPD (5.2)

**Onde:** `/configuracoes/conversas-optouts`

**Como funciona:**
- Paciente envia "PARAR", "SAIR", "CANCELAR", "STOP", etc (keyword match case-insensitive sem acentos)
- Edge function `evolution-whatsapp-inbound` detecta → registra em `conversation_optouts` → envia msg de confirmação
- Paciente envia "VOLTAR" / "RETORNAR" → reativa (opted_back_in_at preenchido)
- Auto-reply e lembretes **respeitam opt-out** automaticamente (skip + log `opted_out`)
- Envio manual do terapeuta NÃO é bloqueado (relação terapêutica existe)

**Keywords padrão:** 10 palavras (configuráveis na página — pode adicionar custom do tenant).

**Testar:**
- Manda mensagem com "parar" pelo WhatsApp conectado
- Volta em `/configuracoes/conversas-optouts` → número aparece na lista
- Nova mensagem que dispararia auto-reply → não dispara mais

### E. Notas internas (3.3)

**Onde:** dentro do drawer de conversa, seção "Notas internas" collapsible

**Como funciona:**
- CRUD simples por thread
- Visível apenas pra membros ativos do tenant
- Edição/remoção só pelo criador (ou SaaS admin)
- Soft delete (`deleted_at`)
- **NÃO vai pro paciente** — apenas anotação interna da equipe

### F. Tags na conversa (3.1)

**Onde:**
- **Gestão:** `/configuracoes/conversas-tags` (CRUD de tags custom; system tags são read-only)
- **Aplicação:** dentro do drawer de conversa + pills visíveis nos cards do Kanban

**Tags system (seedadas):** Urgente (🔴), Primeira consulta (🔵), Remarcação (🟡), Confirmada (🟢), Follow-up (🟣)

**Custom:** tenant cria suas próprias com nome + slug + cor + ícone (primeicons).

### G. Mídia (áudio / imagem / vídeo / documento)

**Arquitetura:**
- Evolution manda URLs encriptadas do Meta CDN (não tocam direto)
- Edge function `evolution-whatsapp-inbound` chama `/chat/getBase64FromMediaMessage/{instance}` do Evolution → decripta
- Decoda base64 → faz upload no bucket **privado `whatsapp-media`**
- Path: `<tenant_id>/<yyyy>/<mm>/<msg_id>_<timestamp>.<ext>`
- Salva apenas o PATH em `media_url`, NÃO URL pública
- Frontend (`ConversationDrawer`) gera **signed URL on-demand** (1h TTL) ao renderizar

**LGPD:** bucket privado, RLS só permite membros ativos do tenant; path tenant-scoped; signed URLs expiram.

**Player de áudio:** `<audio min-w-[260px] controls>` + `preload="metadata"` pra mostrar duração sem baixar tudo.

**Preview de imagem:** `<Image preview>` do PrimeVue (fullscreen com zoom/rotate) + **botão download injetado via MutationObserver** (fetch blob → download attr → force download com nome do arquivo).

### H. Créditos WhatsApp (Marco B)

**Onde:** `/configuracoes/creditos-whatsapp`

**Fluxo de compra:**
1. User clica "Comprar" num pacote → `create-whatsapp-credit-charge` cria:
   - Customer Asaas (ou reutiliza via `externalReference=tenant_id`)
   - Pagamento PIX (`billingType=PIX`, value, dueDate)
   - Busca QR Code em `/payments/{id}/pixQrCode`
2. Dialog mostra QR + copia-cola + link cartão
3. User paga
4. Asaas → webhook `asaas-webhook` recebe `PAYMENT_RECEIVED`/`CONFIRMED`
5. Webhook chama `add_whatsapp_credits(tenant, credits, 'purchase')` → saldo atualiza

**Pacotes seedados:** Iniciante (100/R$49,90), Profissional (500/R$199,90, ⭐ featured), Clínica (1500/R$499,90), Enterprise (5000/R$1499,90) — editáveis via DB.

**RPCs atômicas (SECURITY DEFINER):**
- `add_whatsapp_credits(tenant, amount, kind, purchase_id, admin_id, note)` → retorna novo saldo
- `deduct_whatsapp_credits(tenant, amount, msg_id, note)` → atômico com `SELECT FOR UPDATE`; lança `insufficient_credits` se saldo < amount

**CPF:** fallback hardcoded `24971563792` em sandbox. Em produção, frontend deve coletar CPF real do user (TODO — adicionar input no dialog + salvar em profile/tenant).

---

## 🧪 Testar sem provedor real

### Pré-requisito: creditar saldo

No Supabase Studio (`http://localhost:54323`) → SQL Editor (**desativa LIMIT 100 no dropdown**):

```sql
SELECT public.add_whatsapp_credits(
    tm.tenant_id,
    100,
    'topup_manual',
    NULL,
    auth.uid(),
    'Topup de teste'
) AS novo_saldo
FROM public.tenant_members tm
JOIN auth.users u ON u.id = tm.user_id
WHERE u.email = 'SEU_EMAIL'
  AND tm.status = 'active'
LIMIT 1;
```

### Simular canal Twilio fake (pra testar dedução)

```sql
-- Desativa Evolution
UPDATE public.notification_channels
SET is_active = false, deleted_at = now()
WHERE tenant_id = (
    SELECT tm.tenant_id FROM public.tenant_members tm
    JOIN auth.users u ON u.id = tm.user_id
    WHERE u.email = 'SEU_EMAIL' AND tm.status = 'active' LIMIT 1
)
AND channel = 'whatsapp' AND deleted_at IS NULL;

-- Cria Twilio fake
INSERT INTO public.notification_channels (
    tenant_id, owner_id, channel, provider, is_active,
    twilio_subaccount_sid, twilio_phone_number, credentials
)
SELECT
    tm.tenant_id, u.id, 'whatsapp', 'twilio', true,
    'ACfake0000000000000000000000000000',
    '+15557775555',
    '{"subaccount_auth_token": "fake_token"}'::jsonb
FROM public.tenant_members tm
JOIN auth.users u ON u.id = tm.user_id
WHERE u.email = 'SEU_EMAIL' AND tm.status = 'active'
LIMIT 1;
```

Agora qualquer envio:
- Deduz 1 crédito (`usage -1`)
- Twilio API retorna 401 (creds fake)
- Refunda automaticamente (`refund +1`)
- Saldo final: igual ao inicial

Resultado esperado no extrato:
```
+1  Estorno   — Refund envio falhou: Twilio 401: ...
-1  Uso       — Envio manual WhatsApp
+100 Topup manual — Topup de teste
```

### Simular mensagem inbound via curl

```bash
curl -X POST "http://localhost:54321/functions/v1/evolution-whatsapp-inbound?tenant_id=<uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "messages.upsert",
    "data": {
      "key": { "remoteJid": "5516912345678@s.whatsapp.net", "fromMe": false, "id": "MSG_TEST" },
      "message": { "conversation": "parar" },
      "messageTimestamp": '"$(date +%s)"'
    }
  }'
```

Isso vai testar detecção de opt-out ("parar" é keyword) → registra na lista + envia ACK.

### Testar Twilio sandbox real (opcional)

1. Cria conta trial em https://www.twilio.com/try-twilio (US$15 grátis)
2. Dashboard → Messaging → Try it out → **Send a WhatsApp Message**
3. Segue instruções pra join sandbox (`join <frase>` do seu celular pro número Twilio)
4. Pega Account SID + Auth Token + From number do sandbox
5. Atualiza o canal Twilio no SQL com valores reais
6. Envia mensagem do drawer → chega no seu celular

---

## 🆘 Troubleshooting

| Sintoma | Causa provável | Fix |
|---|---|---|
| 404 no webhook | `supabase functions serve` não rodando OU function não carregada | Reinicia serve com `--env-file` |
| 502 edge function | Crash antes do `console.error` — erro de sintaxe, env var faltando, ou API externa timeout | Olha logs do serve; adiciona `console.log` em cada etapa |
| Asaas 400 "CPF obrigatório" | Customer existente sem CPF | Fix em `getOrCreateAsaasCustomer` faz PATCH com CPF quando falta |
| QR code PIX não aparece | Asaas sandbox sem PIX habilitado OU endpoint `/pixQrCode` falhou | Ativa PIX em Asaas → Recebimentos → Chaves PIX |
| Webhook Asaas não chega | URL não pública (localhost) | Usa ngrok OU deploy em prod |
| "insufficient_credits" no envio | Saldo zerado | Topup via `/configuracoes/creditos-whatsapp` ou SQL manual |
| Auto-reply não dispara | Tenant fora do modo horário configurado OU em cooldown OU opted-out | Checa banner de status em `/configuracoes/conversas-autoreply`; olha `conversation_autoreply_log` |
| Lembrete duplicado | Não acontece — UNIQUE `(event_id, reminder_type)` previne | — |
| Audio não toca (era o ponto inicial do Marco A-I) | URL encriptada do Meta salva direto | Fix: edge function agora decripta via `getBase64FromMediaMessage` + upload pro bucket |
| Mime `audio/ogg; codecs=opus` rejeitado pelo bucket | `allowed_mime_types` faz match exato | Fix: strip `;codecs=...` antes do upload |
| Dialog de confirmação aparece 2x | Dois `<ConfirmDialog>` montados (página + drawer global) | Fix: drawer usa `group="conversation-drawer"` pra isolar |

---

## 🔒 Segurança & Compliance

### RLS de `conversation_messages`
- **SELECT:** tenant members ativos OU saas_admin
- **INSERT direto:** bloqueado (só service_role via edge function)
- **UPDATE:** tenant members podem mudar `kanban_status`, `read_at`
- **DELETE:** bloqueado

### RLS de `whatsapp-media` bucket
- Privado
- Read: membros ativos do tenant cujo id é o primeiro segmento do path
- Write: apenas service_role
- Delete: apenas saas_admin

### RLS de `whatsapp_credits_*`
- Balance/transactions: tenant members leem
- Escrita: via RPCs `add_whatsapp_credits` / `deduct_whatsapp_credits` (SECURITY DEFINER)
- Packages: tenant members leem os ativos; saas_admin gerencia

### LGPD
- **Art. 18 §2 (direito de oposição):** opt-out implementado. Auto-reply + lembretes respeitam.
- **Dados clínicos:** canal Oficial (Twilio) recomendado em prod. Pessoal (Evolution) é uso informal, sem SLA, tenant assume risco.
- **Audit log:** toda transação de crédito fica em `whatsapp_credits_transactions` (append-only).

### Bot defense / Rate limiting
- `public_submission_attempts`, `submission_rate_limits` e `math_challenges` são tabelas do sistema de bot defense pro cadastro externo. Não relacionado ao WhatsApp, mas protege fluxo paralelo.

---

## 📚 Referência de arquivos

### Edge functions (`supabase/functions/`)
- `evolution-whatsapp-inbound/` — webhook Evolution (msgs inbound + auto-reply + opt-out + media)
- `evolution-webhook-provision/` — configura webhook na Evolution
- `twilio-whatsapp-inbound/` — webhook Twilio (inbound only, sem automações ainda)
- `twilio-whatsapp-provision/` — provisiona subconta Twilio (SaaS admin only)
- `send-whatsapp-message/` — envio unificado (Evolution ou Twilio com dedução)
- `send-session-reminders/` — worker de lembretes (chamado por cron)
- `create-whatsapp-credit-charge/` — cria PIX Asaas
- `asaas-webhook/` — recebe eventos Asaas e credita saldo
- `deactivate-notification-channel/` — soft-delete de canal (via service_role)

### Composables (`src/composables/`)
- `useConversations.js` — Kanban threads
- `useConversationNotes.js` — notas internas
- `useConversationTags.js` — tags CRUD + apply
- `useConversationOptouts.js` — opt-outs + keywords
- `useAutoReplySettings.js` — config auto-reply
- `useSessionReminders.js` — config lembretes + logs
- `useWhatsappCredits.js` — saldo + loja + extrato

### Páginas principais (`src/layout/configuracoes/`)
- `ConfiguracoesWhatsappChooserPage.vue` — landing/chooser
- `ConfiguracoesWhatsappPage.vue` — setup Evolution (Pessoal)
- `ConfiguracoesTwilioWhatsappPage.vue` — setup Twilio (Oficial, rebrandeado)
- `ConfiguracoesConversasTagsPage.vue` — CRUD tags
- `ConfiguracoesConversasOptoutsPage.vue` — lista opt-outs + keywords
- `ConfiguracoesConversasAutoreplyPage.vue` — auto-reply
- `ConfiguracoesLembretesSessaoPage.vue` — lembretes
- `ConfiguracoesCreditosWhatsappPage.vue` — saldo + loja + histórico

### Tabelas principais (database-novo/schema/)
Ver dashboard interativo: `database-novo/agenciapsi-db-dashboard.html` (regenerado via `node db.cjs dashboard`).

Domínios no dashboard:
- **CRM Conversas (WhatsApp)** — todas as tabelas de conversas, notas, tags, opt-outs, auto-reply, lembretes
- **Addons / Créditos** — créditos WhatsApp (balance, transactions, packages, purchases)
- **Comunicação / Notificações** — canais, templates, queue

---

## 📌 Dívidas técnicas conhecidas

1. **Auto-reply via Twilio** — hoje só funciona com Evolution. Precisa portar lógica pra `twilio-whatsapp-inbound`.
2. **Opt-out via Twilio** — idem (keyword detection no inbound Twilio).
3. **Admin SaaS UI de créditos** — topup manual + gestão de pacotes (hoje via SQL).
4. **Input de CPF real** no dialog de compra (hoje fallback hardcoded em sandbox).
5. **Alerta de saldo baixo** — estrutura DB pronta (`low_balance_threshold`, `low_balance_alerted_at`), falta trigger/notification.
6. **Reconnect Evolution automático** — Grupo 6.3 do roadmap (heartbeat + reconnect).
7. **pg_cron em prod** — migration tem bloco comentado; ativar via Supabase Dashboard → Database → Cron Jobs ou descomentar após setar `app.settings.service_role_key`.

---

**Última atualização:** 2026-04-21 (sessão de features CRM WhatsApp + Marco B Créditos)