NooviChatDocs

Lead Scoring

Sistema de pontuação de leads baseado em eventos. Cada regra define um tipo de evento (mensagem recebida, resposta, mudança de estágio, etc.) e quantos pontos adicionar ao score.

Como Funciona

O lead score é calculado automaticamente com base em regras de eventos. Cada regra define um event_type (ex: message_received, first_response, stage_changed) e ospoints a aplicar quando o evento ocorre. O score acumulado vai de 0 a 100.

Regras de Score

GET/api/v1/accounts/{account_id}/lead_score_rules

Lista todas as regras de lead scoring.

bash
curl -s "https://chat.seudominio.com/api/v1/accounts/1/lead_score_rules" \
  -H "api_access_token: YOUR_TOKEN" | jq .
200Lista de regras
json
[
  {
    "id": 1,
    "event_type": "message_received",
    "event_subtype": null,
    "points": 5,
    "enabled": true,
    "priority": 0,
    "cooldown_minutes": 0,
    "name": "Message Received",
    "description": null,
    "conditions": {}
  },
  {
    "id": 3,
    "event_type": "first_response",
    "event_subtype": null,
    "points": 10,
    "enabled": true,
    "priority": 0,
    "cooldown_minutes": 0,
    "name": "First Response",
    "description": null,
    "conditions": {}
  }
]
POST/api/v1/accounts/{account_id}/lead_score_rules

Cria uma nova regra de scoring.

Body

NomeTipoObrigatorioDescricao
event_typestringSimTipo de evento: message_received, message_sent, first_response, stage_changed, card_created, card_assigned, label_added, label_removed, conversation_opened, conversation_resolved, conversation_reopened, contact_profile_updated, contact_email_added, contact_phone_added, agent_assigned, agent_replied, custom_event
pointsintegerSimPontos a adicionar/remover quando o evento ocorre
namestringNaoNome descritivo da regra
descriptionstringNaoDescrição detalhada
event_subtypestringNaoSubtipo do evento para filtros mais específicos
conditionsobjectNaoCondições adicionais para aplicar a regra
enabledbooleanNaoRegra ativa (padrão: true)
priorityintegerNaoPrioridade de execução (padrão: 0)
cooldown_minutesintegerNaoTempo mínimo entre aplicações da regra (padrão: 0)
bash
curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/lead_score_rules" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "first_response",
    "points": 10,
    "name": "Primeira resposta rapida",
    "enabled": true
  }'
PATCH/api/v1/accounts/{account_id}/lead_score_rules/{id}

Atualiza uma regra.

DELETE/api/v1/accounts/{account_id}/lead_score_rules/{id}

Remove uma regra.

POST/api/v1/accounts/{account_id}/lead_score_rules/create_defaults

Inicializa regras padrão de scoring para a conta.

Regras Padrão

Cria um conjunto inicial de regras baseadas em melhores práticas: valor do deal, velocidade de resposta, engajamento e tempo no estágio.

Score do Card

PATCH/api/v1/accounts/{account_id}/pipeline_cards/{id}/update_qualification_checklist

Atualiza o checklist de qualificação do card (afeta o score).

Body

NomeTipoObrigatorioDescricao
qualification_checklistobjectSimObjeto onde cada chave é um criterion_id e o valor é um objeto com campos: id, name, checked (boolean), points (integer), required (boolean), category, notes
bash
curl -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards/5/update_qualification_checklist" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "qualification_checklist": {
      "budget_confirmed": {
        "id": "budget_confirmed",
        "name": "Orcamento confirmado",
        "checked": true,
        "points": 20,
        "required": true,
        "category": "qualification"
      },
      "decision_maker": {
        "id": "decision_maker",
        "name": "Decisor identificado",
        "checked": false,
        "points": 15,
        "required": false,
        "category": "qualification"
      }
    }
  }'
POST/api/v1/accounts/{account_id}/pipeline_cards/{id}/recalculate_score

Força o recálculo do lead score de um card (rota legacy). Síncrona: a resposta já traz o score recalculado.

bash
curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards/5/recalculate_score" \
  -H "api_access_token: YOUR_TOKEN"
200Score recalculado (resposta direta, sem wrapper)
json
{
  "id": 5,
  "lead_score": 78,
  "lead_score_category": "hot",
  "qualification_score": 40,
  "lead_score_factors": {
    "conversation_activity": 20,
    "message_volume": 15,
    "time_in_pipeline": 15,
    "profile_completeness": 10,
    "stage_position": 8,
    "recent_activity": 10
  },
  "lead_score_updated_at": "2026-08-10T14:32:10.000Z",
  "updated_at": "2026-08-10T09:15:44.000Z",
  "card_updated_at": "2026-08-10T09:15:44.000Z"
}

Campos adicionados em 2026-08

Esta resposta ganhou id, lead_score_category, updated_at e card_updated_at. A mudança é aditiva: lead_score, qualification_score, lead_score_factors e lead_score_updated_at continuam com o mesmo nome e o mesmo significado.

Nesta rota, updated_at e card_updated_at trazem o mesmo valor: o do card. Repare que ele é mais antigo que lead_score_updated_at — recalcular o score grava direto nas colunas de score e não toca no updated_at do card. Um card_updated_at"parado" logo após um recálculo é o comportamento esperado, não um bug.

Override Manual

Para definir manualmente o lead score de um card use o endpoint dedicado de override. O campo lead_score não é aceito no PATCH do card — ele é calculado pelo motor de scoring e só pode ser sobrescrito por esta rota.

POST/api/v1/accounts/{account_id}/pipeline/cards/{card_id}/lead_scores/override

Sobrescreve manualmente o lead score de um card.

Body

NomeTipoObrigatorioDescricao
scoreintegerSimScore manual a aplicar. Inteiro entre 0 e 100 — valor ausente ou fora da faixa retorna 422.
bash
curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/5/lead_scores/override" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "score": 85 }'
200Score sobrescrito
json
{ "lead_score": 85, "manual_override": true }
POST/api/v1/accounts/{account_id}/pipeline/cards/{card_id}/lead_scores/recalculate

Recalcula o score do card (rota canônica do namespace pipeline). Mesmo efeito do /recalculate_score legacy.

200Score recalculado (resposta direta, sem wrapper)
json
{
  "lead_score": 78,
  "lead_score_factors": {
    "conversation_activity": 20,
    "message_volume": 15,
    "time_in_pipeline": 15,
    "profile_completeness": 10,
    "stage_position": 8,
    "recent_activity": 10
  },
  "lead_score_category": "hot",
  "updated_at": "2026-08-10T14:32:10.000Z",
  "lead_score_updated_at": "2026-08-10T14:32:10.000Z",
  "card_updated_at": "2026-08-10T09:15:44.000Z"
}

updated_at não significa a mesma coisa nas duas rotas

Nesta rota canônica, updated_at sempre carregou o timestamp do cálculo do score, não o do card. O nome ficou como estava para não quebrar quem já consome esse campo, e os dois timestamps ganharam nome próprio:

  • lead_score_updated_at — quando o score foi calculado. Nesta rota é idêntico a updated_at.
  • card_updated_at — quando o card foi atualizado. Existe nas duas rotas de recálculo, com o mesmo significado. Normalmente é mais antigo que lead_score_updated_at: o recálculo grava direto nas colunas de score e não toca no updated_at do card.

Na rota legacy /pipeline_cards/{id}/recalculate_score, updated_at carrega o timestamp do card. Se você chama as duas rotas, leia card_updated_at e lead_score_updated_at — são os únicos campos que significam a mesma coisa em ambas.

GET/api/v1/accounts/{account_id}/pipeline/lead_scores/distribution

Distribuição de scores dos cards visíveis ao usuário (categorias hot/warm/cold).

200Distribuição de scores (resposta direta, sem wrapper data)
json
{
  "hot": 8,
  "warm": 18,
  "cold": 16,
  "total": 42,
  "average": 52.3
}

Logs de Score

GET/api/v1/accounts/{account_id}/lead_score/logs

Histórico de mudanças de score.

GET/api/v1/accounts/{account_id}/lead_score/logs/{id}

Detalhes de uma mudança de score.

Relatórios de Lead Score

GET/api/v1/accounts/{account_id}/lead_score/reports/dashboard

Dashboard de lead scoring.

GET/api/v1/accounts/{account_id}/lead_score/reports/distribution

Distribuição detalhada de scores.

GET/api/v1/accounts/{account_id}/lead_score/reports/trends

Tendências de scoring ao longo do tempo.

GET/api/v1/accounts/{account_id}/lead_score/reports/top_leads

Ranking dos leads com maior score.

GET/api/v1/accounts/{account_id}/lead_score/reports/category_changes

Histórico de mudanças de categoria (frio, morno, quente).

POST/api/v1/accounts/{account_id}/lead_score/reports/bulk_recalculate

Recalcula o score de todos os cards da conta.