Skip to main content

​
O que é o analytics agregado

O analytics agregado (GET /v1/analytics/*) entrega os mesmos números dos dashboards de Conversas e Talk da plataforma, mas em um formato pronto para o seu BI: linhas agregadas por período × dimensão, calculadas a partir dos seus dados de conversas e tickets. Diferente dos relatórios operacionais, aqui as linhas já vêm agregadas — uma linha por balde de tempo e combinação de dimensões, não uma linha por evento.
São três endpoints: conversas, tickets e um endpoint barato de frescor para consultar quando os dados foram atualizados pela última vez.

​
O princípio dos componentes aditivos

A regra central do analytics: entregamos numerador e denominador; você faz a divisão. Nenhuma taxa, média ou percentual chega pré-calculado. Uma taxa de resposta, por exemplo, não vem como 0.83. Vêm as duas contagens — conversations_answered e conversations_started — e você computa SUM(conversations_answered) / SUM(conversations_started) no seu BI, sobre o recorte que quiser.
Nunca calcule uma taxa fazendo a média das taxas diárias. Isso dá peso igual a dias com volumes diferentes e produz um número errado. Some os componentes e divida as somas: SUM(numerador) / SUM(denominador).
O mesmo vale para as médias de SLA do Talk. Cada média chega como um par soma+contagem, e a soma carrega a unidade no nome — em segundos (por exemplo first_response_sum_seconds e first_response_count). A média é SUM(sum) / SUM(count) em segundos; divida ainda por 60 para minutos.

​
Grão: dia de São Paulo × dimensão

O grão canônico é o dia do calendário de São Paulo (America/Sao_Paulo) do timestamp que dirige cada métrica. Cada linha combina esse dia com as dimensões que você pedir em group_by.
  • tz controla o fuso do agrupamento por dia. O padrão é America/Sao_Paulo; UTC também é aceito.
  • group_by é uma lista separada por vírgulas de dimensões permitidas por métrica (por exemplo agent_type,source em conversas). Cada dimensão agrupada aparece como uma chave adicional em cada linha.

​
Dia, semana e mês

day é o grão canônico. week (segunda-feira ISO) e month são o mesmo rollup somado sobre os dias — sem armazenamento separado, sem grão sub-diário. Isso só é válido porque toda métrica exposta é aditiva (uma contagem ou uma soma): semana e mês são apenas SUM sobre os dias.
Não há paginação por cursor no analytics: uma atualização de ETL no meio da paginação mudaria os valores dos baldes e quebraria a estabilidade do cursor. Em vez disso, as chamadas são limitadas por um teto rígido de intervalo (366 dias sem agrupamento, 92 dias com agrupamento) e por um limite máximo de linhas. Para períodos maiores, quebre em várias chamadas.

​
Escopo padrão de conversas (agent_type)

Sem parâmetros, o endpoint de conversas retorna o mesmo recorte que os painéis mostram por padrão — as conversas do seu agente de IA no WhatsApp. Assim os números batem com a plataforma sem nenhuma configuração. Para ampliar (ou restringir) esse recorte, informe o filtro agent_type com uma lista separada por vírgulas dos tipos de agente que você quer incluir. Os valores válidos são os mesmos que aparecem na dimensão agent_type dos próprios resultados (agrupe por agent_type para vê-los). agent_type sobrescreve o padrão.
Se os seus números não baterem com o painel, verifique primeiro o agent_type: o padrão é o que garante a paridade. Só amplie quando quiser deliberadamente incluir outros tipos de agente.

​
Frescor: as_of e stale

O data_lake é atualizado por ETL a cada 6 horas. Por isso toda resposta de analytics carrega o frescor:
  • as_of — o momento (ISO 8601) da última execução de ETL bem-sucedida daquele metricset. null quando desconhecido.
  • stale — true quando os dados estão defasados (mais que ~2× a cadência de 6h, ou seja, quando uma execução foi pulada/falhou) ou quando o frescor é desconhecido.
  • O header X-Data-As-Of repete o as_of da resposta.
A política é servir com aviso, nunca falhar: mesmo defasada, a resposta volta com 200 e stale: true. Um carimbo ausente é lido como { as_of: null, stale: true } — nunca como atualizado. Use o endpoint de frescor para consultar o as_of de cada metricset de forma barata antes de puxar.
Cada metricset carrega o seu próprio as_of: uma execução parcial de ETL pode deixar conversas atualizado e tickets defasado. Por isso os endpoints nunca combinam duas fontes carimbadas independentemente.

​
Métricas NÃO aditivas

Nem tudo o que os dashboards mostram pode ser somado livremente. Estas métricas exigem cuidado — sempre reconstrua a partir dos componentes exportados, nunca some o resultado final:
Taxa de resposta, taxa de agendamento, taxa de transferência, médias de SLA (tempo de atribuição, primeira resposta, handle time), CSAT. Recompute como SUM(numerador) / SUM(denominador) — nunca faça a média das taxas diárias.
tickets_in_service e status_id refletem o estado no instante do snapshot do ETL — um ticket pode mudar de balde numa execução posterior. São aditivos apenas dentro de um mesmo snapshot.
Quando uma conversa tem vários produtos/empreendimentos (ou vários skills), ela aparece em mais de um balde da dimensão. Somar ao longo dessa dimensão superconta o total distinto — a aditividade só vale no eixo do tempo dentro de um mesmo balde.
Contagens de conversas distintas (razões de transferência), dias ativos e etapas de funil (iniciada → transferida → qualificada → respondida) são subconjuntos aninhados, não partições. Reconstrua a partir das flags/componentes exportados; não some o resultado.
Rankings de melhor/pior atendente ou empreendimento e cortes Top-N são derivados. Exportamos a dimensão completa (sem corte) com os pares soma+contagem por entidade — o seu BI aplica o limite mínimo e ordena.
Deltas entre períodos e taxas normalizadas por dias ativos nunca são entregues. Junte os componentes e calcule no BI.

​
Referência e playground

Consulte Conversas, Tickets e Frescor para todos os parâmetros, as métricas expostas, os formatos de resposta e os códigos de erro — e para testar as chamadas direto no playground.