Métricas de Atendimento

O endpoint de Métricas de Atendimento devolve os mesmos números da aba Analytics → Atendimento do painel, para você levar a um BI, uma planilha ou um painel próprio. A conta é feita uma vez só, no SquadOS: a tela e a API leem a mesma definição, então os números batem.

O endpoint exige o header Authorization: Bearer pk_.... A organização é sempre a dona do token; nenhum parâmetro escolhe outra.

Base URL: https://api.squados.io/v1

Consulte Autenticação para obter sua chave, e Erros para a referência de códigos.

Como os números são contados

Só entram conversas com clientes. Conversas internas do time ficam de fora.
Um atendimento é uma conversa em que o cliente mandou mensagem dentro do período.
Com IA conta atendimentos em que um agente respondeu no período; com humano, os que tiveram mensagem de uma pessoa do time no período. Atribuir a conversa sem responder não conta. Uma conversa pode contar nos dois.
A primeira resposta usa os ciclos de primeira resposta humana concluídos no período. Os tempos contam só o horário de atendimento da agenda da caixa de entrada e vêm como p50 (metade das respostas saiu até esse tempo) e p95 (95% saíram até esse tempo).
A fila (first_response_sla.queue) é a situação de agora e não depende do período.
As datas from e to são interpretadas no fuso da organização e incluem os dois dias.
Tempos vêm em segundos. Quando não há base para calcular (nenhuma resposta, nenhuma avaliação), percentuais, tempos e médias vêm como null, nunca 0.

`GET /metrics/support`

Parâmetros de query

Nome	Tipo	Obrigatório	Descrição
`from`	date (`YYYY-MM-DD`)	sim	Primeiro dia do período.
`to`	date (`YYYY-MM-DD`)	sim	Último dia do período, inclusive. Precisa ser igual ou posterior a `from`.

O período pode ter até 400 dias (to menos from).

curl -X GET "https://api.squados.io/v1/metrics/support?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "period": { "from": "2026-09-01", "to": "2026-09-30", "timezone": "America/Sao_Paulo" },
  "conversations": { "total": 1000, "ai_handled": 800, "human_handled": 600, "ai_only": 400 },
  "resolutions": { "total": 900, "by_ai": 300 },
  "first_response_sla": {
    "responded": 200,
    "within_sla": 150,
    "breached": 50,
    "compliance_pct": 75.0,
    "p50_seconds": 240,
    "p95_seconds": 3900,
    "queue": { "pending": 7, "overdue": 3, "at_risk": 2, "unassigned": 1 }
  },
  "satisfaction": { "rated": 120, "average_score": 4.35 },
  "by_inbox": [
    {
      "inbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "WhatsApp Oficial",
      "conversations": 700,
      "ai_handled": 500,
      "human_handled": 450,
      "sla_responded": 120,
      "sla_compliance_pct": 80.0,
      "sla_p50_seconds": 180
    }
  ],
  "attendants": [
    {
      "user_id": "9b2c1f0e-8d7a-4c3b-a1e2-5f6d7c8b9a01",
      "name": "Ana",
      "email": "[email protected]",
      "is_active_member": true,
      "responded": 80,
      "within_sla": 70,
      "breached": 10,
      "compliance_pct": 87.5,
      "p50_seconds": 200
    }
  ],
  "topics": [{ "topic": "cancelamento", "conversations": 24 }],
  "contact_tags": {
    "in_period": [{ "tag": "Renovação", "contacts": 12 }],
    "all_time": [{ "tag": "VIP", "contacts": 340 }]
  }
}

Campo	Descrição
`period`	O período pedido e o fuso da organização usado para interpretá-lo.
`conversations`	`total` de atendimentos; `ai_handled` (com IA), `human_handled` (com humano) e `ai_only` (só IA).
`resolutions`	Conversas resolvidas no período (`total`) e quantas pela IA (`by_ai`).
`first_response_sla`	Primeiras respostas humanas concluídas no período: `responded`, `within_sla`, `breached`, `compliance_pct` (uma casa decimal), `p50_seconds`, `p95_seconds`, e a `queue` de agora (`pending`, `overdue`, `at_risk`, `unassigned`).
`satisfaction`	Conversas avaliadas no período (`rated`) e a nota média de 1 a 5 (`average_score`).
`by_inbox`	Uma linha por caixa de entrada com atendimento ou resposta no período. Atendimentos sem caixa contam no total, mas não aparecem aqui.
`attendants`	Uma linha por atendente, com mais violações primeiro. `user_id` vem `null` para respostas sem atendente reconhecido; `is_active_member` é `false` para quem saiu da organização.
`topics`	Até 15 assuntos mais frequentes nos atendimentos do período.
`contact_tags`	Até 50 tags dadas no período (`in_period`) e até 50 com o total de contatos de cada uma (`all_time`).

Erros

Status	`code`	Quando
400	`invalid_request`	`from` ou `to` ausente, fora do formato `YYYY-MM-DD` ou inexistente no calendário; `to` antes de `from`; período acima de 400 dias.
401	`unauthorized`	Token ausente, inválido ou desativado.
500	`internal_error`	Falha ao calcular as métricas. Tente de novo.