Análise de visitantes e clientes

Métricas, funil, origem do tráfego, temas das conversas e a linha do tempo de cada cliente.

A Nevox junta duas coisas que normalmente ficam separadas: quem visita o seu site ou app e o que essas pessoas conversam com o atendente. Assim você responde perguntas como:

• De onde vêm os visitantes que viram lead?
• Quantos visitantes abrem o chat, quantos conversam e quantos agendam?
• O que as pessoas mais perguntam, e o que o agente não soube responder?
• Qual foi o caminho de um cliente específico até fechar?

Os mesmos números aparecem em Painel → Análise. A API serve para levar esses dados ao seu próprio painel, planilha ou ferramenta de BI.

Para os visitantes do site aparecerem, ative o rastreamento. As conversas de todos os canais são medidas automaticamente.

Definições

Parâmetros comuns

Todos os endpoints de análise usam o escopo analytics:read e aceitam:

O período máximo por consulta é de 366 dias e respeita a retenção do seu plano (Pro: 90 dias; Ultimate: 13 meses).

Visão geral

GET /v1/analytics/overview

curl "https://api.nevox.ai/v1/analytics/overview?from=2026-10-01&to=2026-10-31&compare=previous_period" \
  -H "Authorization: Bearer $NEVOX_API_KEY"

{
  "period": { "from": "2026-10-01", "to": "2026-10-31", "timezone": "America/New_York" },
  "metrics": {
    "visitors": 8420,
    "sessions": 11903,
    "pageviews": 30117,
    "widget_opens": 1210,
    "conversations": 964,
    "leads": 311,
    "appointments_requested": 142,
    "handoffs": 88,
    "conversions": 61,
    "conversion_value": 543900,
    "resolution_rate": 0.91,
    "avg_first_response_seconds": 3.2,
    "unanswered_questions": 37,
    "feedback_incorrect": 9
  },
  "previous": {
    "visitors": 7105,
    "conversations": 802,
    "leads": 240
  },
  "currency": "USD"
}

conversion_value soma o value dos eventos de conversão, em centavos.

Série temporal

GET /v1/analytics/timeseries?metric=conversations&interval=day

{
  "interval": "day",
  "data": [
    { "date": "2026-10-01", "conversations": 28, "leads": 9 },
    { "date": "2026-10-02", "conversations": 35, "leads": 12 }
  ]
}

Quebra por dimensão

GET /v1/analytics/breakdown?dimension=utm_source&metrics=visitors,leads,conversions&limit=10

{
  "dimension": "utm_source",
  "data": [
    { "value": "google", "visitors": 3120, "leads": 140, "conversions": 31 },
    { "value": "instagram", "visitors": 2210, "leads": 96, "conversions": 14 },
    { "value": "(none)", "visitors": 2004, "leads": 51, "conversions": 12 }
  ]
}

Funil

GET /v1/analytics/funnel

O funil padrão mostra quantos visitantes do site ou app (medidos pelo rastreamento) passaram por cada etapa e por todas as anteriores no período:

{
  "steps": [
    { "step": "visited", "count": 8420, "rate_from_previous": null },
    { "step": "opened_chat", "count": 1210, "rate_from_previous": 0.144 },
    { "step": "conversed", "count": 690, "rate_from_previous": 0.570 },
    { "step": "lead", "count": 311, "rate_from_previous": 0.451 },
    { "step": "converted", "count": 61, "rate_from_previous": 0.196 }
  ]
}

Passe steps=visited,opened_chat,lead,conversion:consulta_paga para montar o seu próprio funil (até 8 etapas). Use conversion:<nome> para etapas com seus eventos.

Temas e lacunas

GET /v1/analytics/topics

A IA dá um tema curto a cada conversa e a lista junta as conversas por tema, com quantas o agente resolveu sem passar para a sua equipe. Também lista as perguntas que o agente não soube responder (conversas que foram para a equipe por falta de informação), juntando as escritas de jeitos diferentes. É a lista de prioridade para ensinar o agente.

• O tema é dado uma vez, meia hora depois da última mensagem da conversa, e reaproveita os temas que você já tem.
• Só conversas do ambiente live recebem tema: com uma chave de teste, topics vem vazio.
• limit (1 a 100, padrão 20) vale para as duas listas.

{
  "topics": [
    { "topic": "Remarcação de consulta", "conversations": 212, "resolution_rate": 0.97 },
    { "topic": "Preço da consulta", "conversations": 180, "resolution_rate": 0.99 },
    { "topic": "Reembolso", "conversations": 41, "resolution_rate": 0.22 }
  ],
  "unanswered": [
    {
      "question": "Vocês atendem crianças?",
      "occurrences": 14,
      "last_seen_at": "2026-10-30T19:12:00Z",
      "example_conversation_id": "conv_k2m1"
    }
  ]
}

Qualidade

A visão geral já traz resolution_rate, handoffs, avg_first_response_seconds e feedback_incorrect. Para detalhar:

• GET /v1/analytics/breakdown?dimension=handoff_reason&metrics=handoffs: por que as conversas foram para humano.
• GET /v1/analytics/breakdown?dimension=topic&metrics=conversations,resolution_rate: em que temas o agente vai melhor ou pior.
• GET /v1/analytics/breakdown?dimension=channel&metrics=conversations,resolution_rate: em que canal o agente resolve mais.

Visitantes

{
  "id": "vis_92hd1",
  "identified": true,
  "contact": { "id": "ctc_4hq81", "external_id": "paciente_1042" },
  "first_seen_at": "2026-09-14T17:55:00Z",
  "last_seen_at": "2026-11-03T14:28:00Z",
  "sessions_count": 6,
  "pageviews_count": 23,
  "first_touch": {
    "source": "paid_search",
    "utm_source": "google",
    "utm_campaign": "consulta-online",
    "landing_page": "/consulta-online"
  },
  "last_touch": { "source": "direct", "landing_page": "/" },
  "device": "mobile",
  "country": "US",
  "region": "FL",
  "conversations": ["conv_7mk2p9"],
  "is_lead": true
}

Visitantes que não deram consentimento entram nas contagens, mas não aparecem individualmente nesta lista.

Linha do tempo do contato

GET /v1/contacts/{external_id}/timeline

Tudo o que aconteceu com um cliente, em ordem: visitas, páginas, conversas em qualquer canal, passagens para humano, agendamentos e conversões.

{
  "contact": { "id": "ctc_4hq81", "external_id": "paciente_1042", "name": "Maria Souza" },
  "data": [
    { "at": "2026-09-14T17:55:00Z", "type": "session_started", "source": "paid_search", "landing_page": "/consulta-online" },
    { "at": "2026-09-14T17:57:10Z", "type": "conversation_started", "conversation_id": "conv_1a2b", "channel": "widget" },
    { "at": "2026-09-14T18:02:00Z", "type": "lead" },
    { "at": "2026-09-14T18:03:30Z", "type": "appointment_requested", "conversation_id": "conv_1a2b" },
    { "at": "2026-09-15T12:00:00Z", "type": "conversion", "name": "consulta_paga", "value": 8900, "currency": "USD" },
    { "at": "2026-11-03T14:30:00Z", "type": "conversation_started", "conversation_id": "conv_7mk2p9", "channel": "api" }
  ],
  "has_more": false,
  "next_cursor": null
}

Exportar

Disponível no plano Ultimate.

POST /v1/analytics/exports

{
  "dataset": "conversations",
  "from": "2026-10-01",
  "to": "2026-10-31",
  "format": "csv"
}

Valores de dataset: conversations, messages, visitors, sessions, events, contacts.

A exportação roda em segundo plano e responde 202 na hora:

{
  "id": "exp_5f0c9a1e2b7d4c3a8e6f1b2c3d4e5f60",
  "dataset": "conversations",
  "from": "2026-10-01",
  "to": "2026-10-31",
  "status": "queued",
  "row_count": null,
  "failure_reason": null,
  "download_url": null,
  "expires_at": null,
  "created_at": "2026-11-01T12:00:00Z"
}

Acompanhe em GET /v1/analytics/exports/{id} ou espere o webhook analytics.export_ready. O status passa por queued, running e termina em ready (com download_url) ou failed (com failure_reason). O link de download vale por 24 horas; depois o arquivo é apagado e o status vira expired.

• O arquivo é CSV em UTF-8, separado por vírgula, com cabeçalho na primeira linha. Abre direto no Excel e no Google Planilhas.
• Datas em UTC (ISO 8601); o período (from, to) segue o fuso da conta, ou o timezone que você passar.
• Até 100 mil linhas por arquivo: acima disso a exportação falha pedindo um período menor.
• Até 20 exportações a cada 24 horas.