Smart Campaigns IA

Smart Campaigns são campanhas WhatsApp 100% gerenciadas por IA que reativam leads frios automaticamente.

## Intensidades

• Leve (10.000 leads max): max 3 msgs, intervalo 5-10d, dias úteis 10-17h, $5/dia cap
• Moderada (5.000 leads max, recomendado): max 5 msgs, 2-5d, 9-18h, $25/dia
• Agressiva (1.000 leads max, hard): max 8 msgs, 1-2d, 8-20h, $100/dia, modelo Sonnet

## O que a IA faz automaticamente

• Aprende voz da empresa via brand_voice_anchor (cached prompt)
• Decide horário ideal por lead (timezone via DDD, business hours, feriados)
• Atribui ao agente humano disponível com menos conversas abertas
• Para automaticamente se lead responder
• Escolhe variant A/B/C via Thompson sampling (futuro)

## Custo

Tokens consumidos da quota mensal. Estimativa exibida ANTES de iniciar. Sandbox mode obrigatório no primeiro envio.

Quando você cria uma Nova Smart Campaign, a IA envia mensagens apenas para leads que passam por uma série de filtros. Esses leads são chamados de "qualificados para receber a campanha".

## Filtros configuráveis (campo target_filter)

Você pode combinar qualquer um destes filtros. Quanto mais filtros, menor e mais preciso o público.

1. Status de esfriamento (cooling_status)

Classifica cada deal com base em quanto tempo o lead está sem responder:

• active — respondeu nos últimos 7 dias
• cooling — 7 a 14 dias sem resposta inbound
• cold — mais de 14 dias sem resposta (default do wizard atual)

Atualizado automaticamente por job horário (update_deal_cooling_status()).

2. Score de qualificação (score_range: [min, max])

Faixa do lead_score (0-100) calculado pelo AI Lead Qualifier (BANT + SPIN):

• 0-39 — frio, pouco qualificado
• 40-69 — morno
• 70-100 — quente, alta prontidão de compra

Ex.: score_range: [60, 100] envia só para leads morno/quente.

3. Estágios do pipeline (stages: [stage_id, ...])

Lista de stage_id. Só envia para deals que estão em algum desses estágios. Útil para focar em "Qualificado", "Proposta Enviada", etc.

4. Dias sem interação (days_inactive)

Número inteiro. Filtra deals cujo last_inbound_at é mais antigo que N dias. Complementa cooling_status quando você quer um corte mais fino (ex.: "30 dias exatos").

5. Tags (tags: ["...", "..."])

Array de tags customizadas. Só envia para deals que contêm todas as tags listadas.

## Filtros fixos aplicados pelo engine (não editáveis)

Mesmo que você não configure nada, alguns filtros sempre rodam para proteger o tenant e o número:

• status = 'active' — descarta deals com status won (ganho), lost (perdido) ou paused
• Deal precisa ter contact_phone válido — sem telefone, não entra
• Cap por intensidade — Leve: 10.000 · Moderada: 5.000 · Agressiva: 1.000 (hard cap)
• Opt-out check no momento do envio — se o contato pediu para parar, a execução é pulada
• Janela de 24h do WhatsApp — fora da janela, só envia template aprovado
• Emergency stop de tokens — se o tenant estourou a quota, toda a fila é pausada
• Business hours + timezone — respeita horário comercial do tenant e timezone inferido do DDD
• Feriados — respeita tenant_calendar_blocks
• Stop on reply — se o lead responder durante a campanha, a cadência para automaticamente para aquele deal

## O que o wizard atual envia (estado da implementação)

No formulário Nova Smart Campaign hoje, o target_filter enviado é fixo:

{ "cooling_status": "cold" }

Ou seja, por padrão, todos os deals ativos com mais de 14 dias sem inbound entram na campanha (limitados pelo cap da intensidade escolhida). Os demais filtros (score, stages, tags, days_inactive) existem no backend mas ainda não têm UI no wizard — só podem ser configurados via API direta.

## Endpoint de estimativa

Antes de criar, use "Estimar" no wizard ou chame POST /api/crm/smart-campaigns/estimate com o mesmo target_filter. Retorna:

• estimated_targets — quantos deals entrarão
• estimated_messages — total (targets × max_messages da intensidade)
• estimated_tokens e estimated_cost_usd
• will_exceed — se vai estourar a quota do tenant
• warning — aviso se o cap da intensidade foi atingido