Lead Scoring

Sistema de pontuacao de leads baseado em eventos. Cada regra define um tipo de evento (mensagem recebida, resposta, mudanca de estagio, etc.) e quantos pontos adicionar ao score.

Como Funciona

O lead score e 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

Nome	Tipo	Obrigatorio	Descricao
`event_type`	`string`	Sim	Tipo 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
`points`	`integer`	Sim	Pontos a adicionar/remover quando o evento ocorre
`name`	`string`	Nao	Nome descritivo da regra
`description`	`string`	Nao	Descricao detalhada
`event_subtype`	`string`	Nao	Subtipo do evento para filtros mais especificos
`conditions`	`object`	Nao	Condicoes adicionais para aplicar a regra
`enabled`	`boolean`	Nao	Regra ativa (padrao: true)
`priority`	`integer`	Nao	Prioridade de execucao (padrao: 0)
`cooldown_minutes`	`integer`	Nao	Tempo minimo entre aplicacoes da regra (padrao: 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 padrao de scoring para a conta.

Regras Padrao

Cria um conjunto inicial de regras baseadas em melhores praticas: valor do deal, velocidade de resposta, engajamento e tempo no estagio.

Score do Card

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

Atualiza o checklist de qualificacao do card (afeta o score).

Body

Nome	Tipo	Obrigatorio	Descricao
`qualification_checklist`	`object`	Sim	Objeto onde cada chave e um criterion_id e o valor e 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

Forca o recalculo do lead score de um card.

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards/5/recalculate_score" \
  -H "api_access_token: YOUR_TOKEN"

Override Manual

Para definir manualmente o score de um card, use o endpoint de atualizacao do card com o campo lead_score.

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

Define manualmente o lead score via atualizacao do card.

Body

Nome	Tipo	Obrigatorio	Descricao
`lead_score`	`integer`	Sim	Score manual (0-100)

bash

curl -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards/5" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "lead_score": 85 }'

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

Distribuicao de scores em todo o pipeline.

200Distribuicao de scores

json

{
  "data": {
    "ranges": [
      { "range": "0-25", "count": 15, "label": "Frio" },
      { "range": "26-50", "count": 22, "label": "Morno" },
      { "range": "51-75", "count": 18, "label": "Quente" },
      { "range": "76-100", "count": 8, "label": "Muito Quente" }
    ],
    "average_score": 52.3,
    "median_score": 48
  }
}

Logs de Score

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

Historico de mudancas de score.

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

Detalhes de uma mudanca de score.

Relatorios 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

Distribuicao detalhada de scores.

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

Tendencias 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

Historico de mudancas 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.