Quais leads são "qualificados" para receber a campanha

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