Indicadores

Visão geral

A rota de indicadores entrega, numa única chamada, o retrato do atendimento de um período: quantos atendimentos abriram e encerraram, quanto a IA resolveu sozinha, quanto o cliente esperou pela primeira resposta e pela fila, quanto durou cada atendimento e como o cliente avaliou. Os tempos seguem as mesmas regras da tela de Relatórios: contam só o horário de atendimento e descontam a espera de retorno do cliente.

Casos típicos:

• BI e painéis de gestão: alimentar Power BI, Metabase, Grafana ou uma planilha com a série diária, semanal ou mensal.
• Fechamento do mês: exportar os números por departamento e por atendente para o relatório da diretoria ou para a remuneração variável.
• Acompanhamento de meta: conferir todo dia se a primeira resposta média está dentro do combinado.

A permissão Indicadores ("Volumes, tempos em horário útil, satisfação e números por departamento e atendente") é marcada na chave, em Integrações, card API do ChatISP. Ela dá acesso apenas a números agregados: nomes de atendentes e departamentos aparecem, mas nenhuma mensagem nem dado de cliente.

A chamada

curl -s -G "https://atendimento.seuprovedor.com.br/api_publica.php" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  --data-urlencode "r=relatorios/resumo" \
  --data-urlencode "de=2026-09-01" \
  --data-urlencode "ate=2026-09-30"

<?php
$url = 'https://atendimento.seuprovedor.com.br/api_publica.php?' . http_build_query([
    'r' => 'relatorios/resumo',
    'de' => '2026-09-01',
    'ate' => '2026-09-30',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE')],
]);
$resposta = json_decode(curl_exec($ch), true);

import os, requests

resposta = requests.get(
    "https://atendimento.seuprovedor.com.br/api_publica.php",
    params={"r": "relatorios/resumo", "de": "2026-09-01", "ate": "2026-09-30"},
    headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
    timeout=30,
).json()

{
  "ok": true,
  "periodo": {"de": "2026-09-01T00:00:00-03:00", "ate": "2026-09-30T23:59:59-03:00"},
  "departamento_id": null,
  "conversas": {
    "abertas": 2184,
    "encerradas": 2161,
    "em_andamento_agora": 37,
    "resolvidas_pela_ia": 912
  },
  "mensagens": {
    "recebidas": 25390,
    "enviadas": 27713,
    "pela_ia": 11240,
    "pelos_atendentes": 12988
  },
  "tempos": {
    "primeira_resposta_media_seg": 41.7,
    "espera_fila_media_seg": 318.2,
    "duracao_media_seg": 1146.9
  },
  "satisfacao": {
    "pesquisas_enviadas": 1240,
    "respostas": 433,
    "media": 4.62
  },
  "por_departamento": [
    {"departamento_id": 3, "departamento": "Suporte técnico", "abertas": 1402, "encerradas": 1381},
    {"departamento_id": 2, "departamento": "Financeiro", "abertas": 611, "encerradas": 609},
    {"departamento_id": 1, "departamento": "Comercial", "abertas": 171, "encerradas": 168}
  ],
  "por_atendente": [
    {
      "atendente_id": 7,
      "atendente": "Carlos Lima",
      "atendidas": 402,
      "encerradas": 398,
      "duracao_media_seg": 1310.4,
      "satisfacao_media": 4.71,
      "avaliacoes": 151
    },
    {
      "atendente_id": 4,
      "atendente": "Paula Andrade",
      "atendidas": 377,
      "encerradas": 377,
      "duracao_media_seg": 1022.0,
      "satisfacao_media": 4.55,
      "avaliacoes": 138
    }
  ]
}

Bloco conversas

Para a taxa de resolução pela IA, divida resolvidas_pela_ia por encerradas.

Bloco mensagens

Mensagens criadas dentro do período. Notas internas da equipe não entram em nenhum número.

A diferença entre enviadas e a soma de pela_ia com pelos_atendentes é o volume automático (fluxos, avisos, campanhas, integrações).

Bloco tempos

Horário útil

Os três tempos contam só o que cai dentro do horário de atendimento: vale a grade de horário do departamento da conversa quando ele tem uma; senão, a grade geral. Madrugada, almoço fechado e fim de semana não entram. Sem nenhuma grade cadastrada, o relógio corre 24 horas. Exemplo: com expediente das 08:00 às 18:00, um cliente que chama às 19:50 e é atendido às 08:05 do dia seguinte conta 5 minutos de espera, não 12 horas. A regra completa está em Tempos contados só no horário de atendimento.

Espera de retorno descontada

Quando o atendente marca a conversa como aguardando retorno do cliente (por exemplo, "reinicie o roteador e me avise"), o tempo até o cliente voltar não pesa na duração do atendimento. Cada intervalo de espera é descontado, também só na parte que cai dentro do horário útil. Uma espera ainda aberta no encerramento é descontada até o encerramento.

Bloco satisfação

Vem da pesquisa de satisfação enviada ao fim do atendimento (quando ligada em Configurações), com nota de 1 a 5. Veja Pesquisa de satisfação.

Taxa de resposta: respostas dividido por pesquisas_enviadas.

Por departamento

por_departamento lista os departamentos que tiveram atendimentos abertos no período, do maior volume para o menor. Departamento sem nenhum atendimento no período não aparece.

O departamento considerado é o atual da conversa: um atendimento que começou no Comercial e foi transferido para o Suporte conta no Suporte.

Por atendente

por_atendente lista as pessoas que são responsáveis por atendimentos abertos no período, de quem atendeu mais para quem atendeu menos.

O atendimento conta para quem é o responsável atual. Se a conversa foi transferida de uma pessoa para outra, ela conta só para quem ficou com ela.

Filtro por departamento

Com departamento_id, todos os números passam a considerar só aquele departamento: conversas, mensagens, tempos, a lista por departamento (que fica com uma linha só) e os volumes e durações por atendente consideram os atendimentos que estão hoje no departamento; a satisfação (geral e por atendente) usa o departamento registrado na pesquisa.

Para montar uma tabela com todos os departamentos lado a lado, chame uma vez sem filtro (o total da casa) e uma vez por departamento, com os ids de departamentos/listar. A receita Exportar indicadores mensais faz isso.

Boas práticas

• Feche períodos completos. Para a série histórica, consulte dias, semanas ou meses já encerrados e grave o resultado no seu BI. O mês corrente muda a cada atendimento.
• Prefira várias chamadas curtas a uma longa. Um ano inteiro é aceito, mas uma série mensal (12 chamadas) dá mais informação e cada chamada é mais leve.
• Não consulte em laço curto. Os números são calculados na hora; uma consulta a cada 5 ou 15 minutos é suficiente para um painel ao vivo. Respeite a cota da chave (X-RateLimit-Remaining).
• Fuso. Datas sem fuso são lidas no fuso do servidor (veja servidor.fuso_horario em chave/info). Ao montar o período a partir de outro fuso, mande a data em ISO 8601 com o fuso explícito.
• Médias de médias. Para juntar períodos, não tire a média das médias: pondere pelo volume (por exemplo, duracao_media_seg vezes encerradas).

Erros

Além dos erros comuns a toda a API, descritos em Erros:

{"ok": false, "error": "periodo_invalido", "maximo_dias": 366}