SE
Sumário Executivo
O SalesHelix é o AI Social Sales CRM da DNAi. O motor de canais é o Chatwoot (self-hosted, licença MIT), que agrega WhatsApp e Instagram DM num inbox unificado. Por cima do Chatwoot, o SalesHelix adiciona a camada que o concorrente genérico não tem: IA de vendas (NADIA/Claude) conduzindo qualificação, score de lead e playbooks de SDR, com handoff limpo para o operador humano.
A interface própria — Next.js — consome a API do Chatwoot e expõe o CRM, o Kanban de pipeline e a ficha do lead enriquecida.
O plano está organizado em 6 fases sequenciais. O MVP vendável (Fases 0–3) é atingível em 8–10 semanas com 1–2 devs. As fases seguintes adicionam diferencial competitivo e abrem o modelo multi-tenant.
01
Visão de Arquitetura
1.1 Diagrama de Componentes
Componentes do sistema — visão completa
┌─────────────────────────────────────────────────────────────────────┐
│ CANAIS DE ENTRADA │
│ │
│ [WhatsApp não-oficial] [WhatsApp Cloud API] [Instagram DM] │
│ QR Code / multi-device Meta Business API Graph API Meta │
│ │ │ │ │
│ ▼ │ │ │
│ [Evolution API] │ │ │
│ Ponte WABA↔Chatwoot │ │ │
│ │ │ │ │
└─────────┼──────────────────────────┼──────────────────────┼─────────┘
│ │ │
└──────────────┬───────────┘ │
▼ │
┌────────────────────────────────────────────────────────────────────┐
│ CHATWOOT (self-hosted, Docker) │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Rails app │ │ Sidekiq │ │ Action Cable │ │
│ │ (API REST + │ │ (jobs, filas, │ │ (WebSocket │ │
│ │ webhooks) │ │ retries) │ │ realtime) │ │
│ └────────┬────────┘ └──────────────────┘ └──────────────────┘ │
│ │ │
│ ┌────────▼────────┐ ┌──────────────────┐ │
│ │ PostgreSQL │ │ Redis │ │
│ │ (conversations, │ │ (cache, jobs, │ │
│ │ contacts, │ │ sessions) │ │
│ │ messages) │ └──────────────────┘ │
│ └─────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ AGENT BOT — webhook endpoint │ │
│ │ Chatwoot dispara POST pra cada msg recebida │ │
│ │ → URL do serviço NADIA configurada no painel │ │
│ └───────────────────────────┬────────────────────────────────┘ │
└──────────────────────────────┼──────────────────────────────────────┘
│ POST (mensagem + contexto)
▼
┌──────────────────────────────────────────────────────────────────┐
│ NADIA SERVICE (Node.js / Python) │
│ │
│ ┌────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │
│ │ Webhook │ │ Claude API │ │ Handoff Engine │ │
│ │ receiver │ │ (Anthropic) │ │ (score ≥ X │ │
│ │ valida, │ │ qualificação + │ │ → assign SDR) │ │
│ │ formata, │ │ resposta + │ │ POST Chatwoot │ │
│ │ enriquece │ │ próxima ação │ │ /assign/:id │ │
│ └────────┬───────┘ └────────┬────────┘ └──────────────────┘ │
│ └───────────────────┘ │
│ │ │
│ ┌─────────────────▼──────────────────────────────────────┐ │
│ │ SalesHelix DB (PostgreSQL separado) │ │
│ │ leads, scores, playbook_state, pipeline_stage │ │
│ │ pgvector pra embeddings de histórico de conversa │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│ POST resposta via API REST
▼
[Chatwoot] → [Canal original] → [Lead]
┌──────────────────────────────────────────────────────────────────┐
│ SALESHELIX APP (Next.js 15 + Prisma) │
│ │
│ Consome Chatwoot API REST (conversations, contacts, messages) │
│ Consome SalesHelix DB (scores, pipeline, playbooks) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ Inbox view │ │ Kanban CRM │ │ Ficha do Lead │ │
│ │ (espelho │ │ pipeline │ │ score, histórico, │ │
│ │ Chatwoot) │ │ de vendas │ │ próxima ação IA │ │
│ └──────────────┘ └──────────────┘ └─────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
1.2 Fluxo de uma Mensagem — do Lead à Resposta
Fluxo completo de mensagem
Lead manda "oi" no WhatsApp
│
▼
Evolution API (não-oficial) OU Cloud API (oficial)
│ converte pra formato Chatwoot
▼
Chatwoot cria/atualiza Conversation
│ dispara webhook Event: message_created
▼
NADIA Service recebe POST
│ lê histórico da conversa (via Chatwoot API)
│ lê ficha do lead no SalesHelix DB (score, estágio)
│ monta contexto + playbook ativo
▼
Claude API — responde, classifica intenção, atualiza score
│
├── Score < threshold handoff
│ │ POST /api/v1/accounts/{id}/conversations/{id}/messages
│ │ Chatwoot entrega a resposta no canal
│ └── Lead recebe a resposta da NADIA
│
└── Score ≥ threshold handoff
│ POST /api/v1/accounts/{id}/conversations/{id}/assignments
│ Chatwoot notifica SDR humano (app/notificação)
└── SDR assume com contexto completo: resumo, score, intenção
1.3 Ponto de Handoff IA → Humano
O handoff acontece quando qualquer uma das condições for verdadeira:
- → Score de lead calculado pela NADIA atinge o threshold configurado (ex: ≥ 70/100)
- → Lead faz pergunta explícita sobre preço ou pede proposta formal
- → Lead demonstra objeção complexa (detectada por classificador Claude)
- → Timeout: NADIA não consegue avançar qualificação em N turnos
O SDR recebe a conversa já com: resumo do lead, score, histórico resumido, intenção detectada e próxima ação recomendada — tudo calculado pela NADIA antes do handoff.
02
Fases de Implementação
0
Infra Base + Chatwoot Self-hosted
Semana 1 · 2–3 dias · 1 dev
Entregáveis
- Docker Compose: chatwoot, sidekiq, postgres, redis
- Domínio configurado com HTTPS (Nginx + Let's Encrypt ou Caddy)
- Painel admin Chatwoot acessível, conta super admin criada
- .env.example documentado no repositório
Dependências do Daniel
- Decisão do subdomínio onde o Chatwoot vai rodar
- Acesso SSH ou sudo na VPS Hetzner (portas 80/443)
- (Opcional) Certificado wildcard Cloudflare ou Cloudflare Tunnel
Testável ao final: acessar painel Chatwoot, criar inbox, criar agente. Fluxo interno funcionando.
1
Conexão de Canais
Semanas 1–4 · WhatsApp não-oficial → oficial → Instagram DM
1A — WhatsApp não-oficial (validação)
- Evolution API rodando em Docker na VPS
- Inbox WhatsApp criado no Chatwoot via Evolution API
- QR Code escaneado, mensagens chegando no inbox
- Documentação de reconexão (QR expira)
1B — WhatsApp Cloud API (produção)
- App no Facebook Developers com produto WhatsApp
- Número verificado no WhatsApp Business Manager
- Webhook Cloud API → Chatwoot configurado
- 1 template aprovado pela Meta (ex: abertura de conversa)
1C — Instagram DM (Graph API)
- App Facebook Developers com Instagram Messaging
- Página Facebook conectada à conta Instagram Business
- Permissões instagram_manage_messages configuradas
- Inbox Instagram criado no Chatwoot, recebendo DMs
Dependências críticas
- Número dedicado pra testes (chip separado, não o principal)
- Conta Meta Business verificada com CNPJ
- App criado em developers.facebook.com
- App Review Instagram: submeter assim que o app existir (1–4 semanas)
Testável ao final: mensagens WhatsApp e Instagram chegam no inbox Chatwoot. Agente humano consegue responder via painel. Já é uma ferramenta de atendimento funcional.
2
NADIA como Agent Bot
Semanas 5–6 · 1.5–2 semanas · 1 dev
Entregáveis
- Serviço NADIA (Node.js ou Python) em Docker com HTTPS
- Agent Bot configurado no Chatwoot → webhook NADIA
- Lógica de qualificação: detecta intenção e classifica
- Score baseado em regras (heurístico no início)
- Handoff automático: score ≥ threshold → atribui SDR
- SDR recebe: resumo NADIA + intenção + score
Estrutura do serviço
nadia-saleshelix/ ├── src/ │ ├── webhook/ # eventos Chatwoot │ ├── claude/ # Anthropic SDK │ ├── qualification/ # score + playbooks │ ├── handoff/ # atribuição de agente │ └── chatwoot/ # cliente API REST ├── prisma/ # schema SalesHelix DB └── docker-compose.yml
Dependências do Daniel
- API key Anthropic (já existe na operação atual)
- Definição dos playbooks iniciais de qualificação
- Threshold de handoff (score mínimo para chamar SDR)
Testável ao final: mandar "oi" no WhatsApp de teste → NADIA responde → qualifica com 2–3 perguntas → atribui pra SDR com resumo. Fluxo completo de ponta a ponta.
3
Interface SalesHelix (Next.js)
Semanas 7–10 · 3–4 semanas · 1–2 devs
Entregáveis
- Next.js 15 (App Router) + autenticação Better-Auth
- Tela Inbox — conversas ativas, filtros, badge de score
- Tela Kanban — pipeline drag-and-drop, estágios configuráveis
- Tela Ficha do Lead — score, intenção, próxima ação IA, notas SDR
- Tela Responder — chat integrado via API Chatwoot
- Prisma + PostgreSQL para dados do SalesHelix
Dependências do Daniel
- Aprovação do design/UX antes de implementar
- Decisão do domínio da interface (ex: app.saleshelix.dnai.global)
- Definição dos estágios de pipeline
Testável ao final: operador entra no SalesHelix, vê inbox unificado, move lead no Kanban, abre ficha com histórico e score, responde pelo app. Produto pronto pra demo com cliente.
4
Scoring Avançado, Playbooks e Automações
Pós-MVP · 3–4 semanas · 1–2 devs
Entregáveis
- Scoring com embeddings: histórico → pgvector + HNSW
- Playbooks configuráveis no painel por produto/segmento
- Automações: follow-up automático, reengajamento
- Dashboard de performance: taxa qualificação, tempo handoff
- Integração de templates aprovados Meta
Dependências
- Dados históricos de conversas para calibrar o score
- Definição de playbooks por segmento de produto
5
Multi-tenant, White-label e Billing
Produto vendável · 4–6 semanas · 2 devs
Entregáveis
- Row Level Security (RLS) no PostgreSQL por tenant
- Onboarding novo tenant em menos de 30 minutos
- Painel admin DNAi: gerenciar tenants, planos, uso
- White-label: logo, cores, domínio customizado por cliente
- Billing: integração Stripe pra assinatura mensal
Dependências
- Definição do modelo de preços e planos
- Conta Stripe configurada
- Decisão sobre white-label: Chatwoot visível ou interface própria completa?
03
O que Precisa do Daniel
| Item | Fase | Urgência | Observação |
|---|---|---|---|
| Decisão do subdomínio Chatwoot | Fase 0 | Alta | Define a URL base de tudo |
| Número WhatsApp dedicado pra testes | Fase 1A | Alta | Chip separado, número descartável. Nunca o principal. |
| Conta Meta Business verificada | Fase 1B | Alta | Verificação com CNPJ pode levar dias |
| App criado no Facebook Developers | Fase 1B | Alta | Daniel cria, dev configura dentro |
| Número comercial dedicado (Cloud API) | Fase 1B | Alta | Não pode estar em nenhum app WhatsApp comum |
| Template de mensagem aprovado pela Meta | Fase 1B | Média | Submeter logo — pode demorar até 7 dias |
| Conta Instagram Business + Página Facebook | Fase 1C | Média | Se já tem, só vincular |
| App Review Meta (instagram_manage_messages) | Fase 1C | Crítica | Pode levar 1–4 semanas. Submeter assim que o app existir. |
| Playbooks de qualificação definidos | Fase 2 | Alta | O que a NADIA pergunta, em que ordem, o que qualifica |
| Threshold de handoff (score mínimo) | Fase 2 | Média | Pode começar com regra simples e ajustar |
| Aprovação do design/UX da interface | Fase 3 | Alta | Não codar sem aprovação visual |
| Domínio da interface SalesHelix | Fase 3 | Média | Ex: app.saleshelix.dnai.global |
| Estágios do pipeline | Fase 3 | Média | Novo Lead / Qualificado / Proposta / Negociando / Fechado |
Burocracia Meta — atenção ao prazo: dois itens têm prazo imprevisível e não dependem do dev. Aprovação de templates WhatsApp: 24h a 7 dias. App Review Instagram (instagram_manage_messages): 1 a 4 semanas. Submeter o App Review assim que o app existir — o prazo corre em paralelo com o desenvolvimento.
04
Custos e Pré-requisitos
$15
–
$80
/ mês (MVP · Fases 0–3)
Piso de ~$15: VPS atual + ~200–300 conversas/mês. Basicamente só Claude para qualificação rotineira. WhatsApp próximo de zero porque o lead inicia.
Teto de ~$80: calculado para ~1200 conversas/mês com VPS atual. Acima de ~1500 conversas/mês, o custo sai da faixa e entra em $80–120.
Teto de ~$80: calculado para ~1200 conversas/mês com VPS atual. Acima de ~1500 conversas/mês, o custo sai da faixa e entra em $80–120.
4.1 Componente 1 — Infraestrutura
| Recurso | Spec | Custo |
|---|---|---|
| VPS atual (Hetzner) | Já existe na operação DNAi | $0 adicional |
| VPS dedicada CX32 | 4 vCPU AMD, 8 GB RAM, 80 GB NVMe | ~$17/mês (€16) |
| Cloudflare Tunnel | Já incluído no plano atual | $0 |
| Tráfego de saída Hetzner | Primeiros 20 TB incluídos | $0 para volume MVP |
[FALTA — confirmar com Daniel] Specs exatas da VPS atual (vCPU, RAM, uso atual). Se já estiver com carga alta (NADIA, outros serviços), pode ser necessária VPS dedicada.
4.2 Componente 2 — WhatsApp Cloud API (Meta)
| Tipo | Quem inicia | Janela | Custo |
|---|---|---|---|
| Service | Lead (usuário) | 24h a partir da última msg do usuário | Grátis |
| Utility | Empresa (notificações transacionais) | 24h | ~$0.01–0.02/conversa (Brasil) |
| Marketing (template) | Empresa (reengajamento) | Abre nova janela | ~$0.062/conversa (Brasil) |
| Authentication | Empresa (OTP) | 10 min | ~$0.04/conversa |
No MVP, o lead sempre inicia a conversa. 100% das conversas de qualificação são tipo service = $0. Custo de template só aparece pra reativar lead frio.
| Volume conversas/mês | Conversas service ($0) | Reengajamento (10%) | Custo WhatsApp |
|---|---|---|---|
| 100 conversas | 90 | 10 × $0,062 | ~$0,62 |
| 500 conversas | 450 | 50 × $0,062 | ~$3,10 |
| 2000 conversas | 1800 | 200 × $0,062 | ~$12,40 |
4.3 Componente 3 — Claude API (Anthropic)
| Modelo | Input | Output | Cache write | Cache read |
|---|---|---|---|---|
| Claude Haiku 3.5 | $1,00/MTok | $5,00/MTok | $1,25/MTok | $0,10/MTok |
| Claude Sonnet 4 | $3,00/MTok | $15,00/MTok | $3,75/MTok | $0,30/MTok |
Custo calculado por conversa completa (~10 turnos), com prompt caching ativo:
Cálculo de custo por conversa
Haiku — input (2k tokens cacheados) : $0,10/MTok × 0,002 = $0,0002
Haiku — input (2k tokens histórico) : $1,00/MTok × 0,002 = $0,0020
Haiku — output (0,8k tokens) : $5,00/MTok × 0,0008 = $0,0040
Sonnet — handoff input (3k tokens) : $3,00/MTok × 0,003 = $0,0090
Sonnet — handoff output (0,5k tokens): $15,00/MTok × 0,0005 = $0,0075
──────────────
TOTAL ~$0,0427 por conversa
Arredondando com margem: ~$0,038–$0,05 por conversa completa com prompt caching ativo.
| Volume | Claude (sem caching) | Claude (com caching) |
|---|---|---|
| 100 conversas | ~$5 | ~$4 |
| 500 conversas | ~$25 | ~$19 |
| 2000 conversas | ~$100 | ~$76 |
4.4 Resumo por Cenário de Volume
| Cenário | Conversas/mês | WhatsApp API | Claude API | Infra VPS atual | Infra VPS CX32 | Total (VPS atual) | Total (VPS CX32) |
|---|---|---|---|---|---|---|---|
| MVP inicial | 100 | $0,62 | $4 | $0 | $17 | ~$4/mês | ~$21/mês |
| Crescimento | 500 | $3,10 | $19 | $0 | $17 | ~$24/mês | ~$41/mês |
| Escala | 2000 | $12,40 | $76 | $0 | $17 | ~$101/mês | ~$118/mês |
4.5 Como Segurar o Custo
| Fator de risco | Impacto | Como segurar |
|---|---|---|
| Chamar Sonnet no grosso das interações | Alto | Haiku para qualificação de rotina. Sonnet APENAS para resumo de handoff. |
| System prompt longo sem caching | Médio | Ativar prompt caching desde o dia 1. Economiza ~80% no custo do context fixo. |
| Sem rate limit por conversa | Médio | Máximo N chamadas Claude por conversa ativa (ex: 15 turnos → forçar handoff humano) |
| Reengajamento excessivo com templates | Baixo | Templates marketing a $0,062 só quando há estratégia real. Não usar como fallback. |
| Click-to-WhatsApp não aproveitado | Oportunidade | Usar Free Entry Point (72h) em anúncios Meta — evita pagar template na 1ª abordagem. |
Alertas de gasto recomendados: Anthropic Console: alertas em $30 e $60/mês. Meta Business Manager: alerta quando templates excederem 100 conversas/semana. Hetzner: alerta de CPU/tráfego acima de 70%.
4.6 Ferramentas Sem Custo Adicional
| Ferramenta | Custo | Observação |
|---|---|---|
| Chatwoot Community | $0 | Licença MIT, self-hosted |
| Evolution API | $0 | Open-source, self-hosted (fase de validação) |
| Cloudflare DNS + Tunnel | $0 | Plano Free cobre o uso do SalesHelix |
| PostgreSQL + Redis | $0 | Incluídos no Docker Compose na mesma VPS |
| Prisma ORM | $0 | Open-source |
05
Riscos e Mitigações
ALTO
Risco 1 — Ban de número no WhatsApp não-oficial (Evolution API)
Probabilidade alta para números com comportamento de bot detectado pela Meta. Número banido permanentemente, conversas perdidas.
- Usar APENAS número de teste/descartável na Fase 1A. Nunca o número de negócio real.
- Migrar para Cloud API oficial (Fase 1B) assim que possível.
- Não enviar mensagens em massa ou comportamento atípico de bot.
MED
Risco 2 — App Review da Meta demorar ou reprovar (Instagram DM)
Meta reprova apps sem política de privacidade clara, sem URL funcional, sem vídeo demonstrativo. Impacto: Instagram DM bloqueado, atraso de semanas.
- Submeter o review assim que o app for criado — não esperar o dev terminar.
- Preparar política de privacidade real, URL funcional, vídeo demonstrativo do fluxo.
- Plano B: começar sem Instagram DM, focar em WhatsApp (sem App Review no mesmo grau).
BAIXO
Risco 3 — Chatwoot updates quebrando integração
Probabilidade baixa no curto prazo, média no longo prazo. Features quebradas após update, downtime para correção.
- Versionar a imagem Docker do Chatwoot (nunca usar latest em produção).
- Testar updates em staging antes de aplicar em produção.
- API REST do Chatwoot é versionada (/api/v1/) — mudanças de UI não afetam integração.
MED
Risco 4 — Custo de tokens escalar além do esperado
Probabilidade média se o volume crescer rápido sem controle.
- Usar Claude Haiku para a maior parte das interações de qualificação.
- Sonnet apenas para resumos de handoff e situações complexas.
- Implementar rate limiting por conversa (máximo N chamadas Claude).
- Monitorar custo semanal via dashboard Anthropic com alertas.
ALTO
Risco 5 — Depender de Evolution API em produção
Alta probabilidade de problemas se usado em produção com volume real. Instabilidade, desconexões frequentes, risco de ban.
- Evolution API é para validação de fluxo apenas. Produção usa Cloud API oficial.
- O plano já prevê isso: Fase 1A (não-oficial, validação) → Fase 1B (oficial, produção).
06
Marco de MVP
8–10
semanas para MVP vendável (Fases 0–3) · com 1–2 devs
- Receber mensagens de WhatsApp no inbox unificado
- Leads automaticamente qualificados pela NADIA com score visível
- Handoff com contexto completo quando o lead está quente
- Pipeline de vendas no Kanban com movimentação manual
- Ficha do lead com histórico e próxima ação recomendada
Cronograma com 1–2 devs
0
Fase 0 — Infra + Chatwoot
2–3 dias
Semana 1 — Chatwoot rodando na VPS com HTTPS
1A
Fase 1A — WhatsApp não-oficial
1–2 dias
Semana 1–2 — Validação rápida do fluxo, zero burocracia
1B
Fase 1B — Cloud API oficial
2–4 dias + burocracia Meta
Semana 2–3 — WhatsApp oficial, número de negócio seguro
1C
Fase 1C — Instagram DM
2–3 dias + App Review Meta
Semana 3–4 — Gargalo: App Review pode atrasar 1–4 semanas
2
Fase 2 — NADIA Agent Bot
1.5–2 semanas
Semana 5–6 — IA respondendo, qualificando e fazendo handoff
3
Fase 3 — Interface SalesHelix
3–4 semanas
Semana 7–10 — App Next.js com Inbox, Kanban e Ficha do Lead
Gargalo principal não é o dev — é a burocracia Meta. Se o App Review do Instagram atrasar, o MVP sem Instagram DM pode ser entregue antes. WhatsApp Cloud API + NADIA + interface já é produto funcional e vendável. Com 2 devs em paralelo (1 no Chatwoot/integrações + 1 no Next.js/CRM), é possível chegar em 6–7 semanas.
O que NÃO entra no MVP
- × Scoring por embeddings (Fase 4)
- × Playbooks configuráveis no painel (Fase 4)
- × Multi-tenant e billing (Fase 5)
- × White-label (Fase 5)
!
Ações Imediatas — 5 itens para Daniel
Sem esses itens, o desenvolvimento trava antes de sair da Fase 1.
1
Subdomínio do Chatwoot
Definir onde o inbox vai rodar. Ex: inbox.saleshelix.dnai.global
Trava: Fase 0 — sem isso, não tem HTTPS nem domínio base
2
Número WhatsApp Dedicado pra Testes
Um chip separado do número de negócio. Pode ser linha pré-paga. NUNCA o número principal.
Trava: Fase 1A — sem número, não tem teste de fluxo
3
Conta Meta Business Verificada + App no Facebook Developers
Conta Business com CNPJ verificado. App criado em developers.facebook.com.
Trava: Fases 1B e 1C — Cloud API + Instagram DM
4
Submissão do App Review Instagram
Submeter assim que o app existir — não esperar o dev. O prazo de revisão (1–4 semanas) corre em paralelo com o desenvolvimento.
Trava: Fase 1C — sem review aprovado, sem Instagram DM em produção
5
Definição dos Playbooks de Qualificação
O que a NADIA pergunta, em que ordem, o que qualifica um lead como "quente" pra passar pro SDR. Pode ser uma conversa de 30 minutos com o dev.
Trava: Fase 2 — sem playbook, a IA não sabe o que fazer