agenciapsilmno/WHATSAPP_SETUP.md

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

# 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)

# 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:

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:

# 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:

# 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:

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:

-- 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):

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)

-- 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

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)