Métricas

Cada instância tem métricas de atendimento calculadas pela OnZap a partir dos eventos do número: quantas mensagens entraram e saíram, quantas conversas os clientes começaram, quanto tempo levou a primeira resposta, quem está esperando resposta agora e quantas vezes a conexão caiu. Os mesmos números aparecem no painel (aba Métricas da instância e página Métricas), na API e no servidor MCP.

• Por número: as rotas ficam sob /v1/instances/{id} e usam o token da própria instância.
• Sem texto: as métricas usam só os metadados dos eventos (ids, direção, tipo, horários e status). O conteúdo das mensagens não é guardado para isso.
• Sem configurar nada: valem para todo evento do número, com ou sem webhook assinando.
• Fuso da conta: "hoje", "ontem" e cada dia seguem o fuso escolhido em Configurações (padrão: horário de Brasília).

Rotas

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/metrics?period=yesterday" \
  -H "X-Instance-Token: SEU_TOKEN"

Parâmetros de GET /metrics

Resposta

{
  "instance": { "id": "i01j...", "name": "Vendas", "provider": "onzap", "status": "WORKING" },
  "period": { "from": "2026-09-30", "to": "2026-09-30", "label": "Ontem (30/09/2026)", "timezone": "America/Sao_Paulo", "granularity": "day" },
  "responseMinutes": 60,
  "includeGroups": false,
  "totals": {
    "received": 102, "sent": 180, "sentApi": 155, "sentPhone": 25,
    "delivered": 171, "read": 140, "failed": 2,
    "conversations": 24, "businessInitiated": 9,
    "answeredWithin": 21, "unansweredWithin": 2, "pending": 1, "responseRate": 0.913,
    "firstResponse": {
      "medianSeconds": 168, "p90Seconds": 960, "samples": 21,
      "api": { "medianSeconds": 4, "p90Seconds": 9, "samples": 8 },
      "phone": { "medianSeconds": 410, "p90Seconds": 1320, "samples": 13 }
    },
    "fromAds": 6, "unansweredNow": 3,
    "downtimeSeconds": 0, "stoppedSeconds": 0, "drops": 0, "availability": 1
  },
  "series": [{ "date": "2026-09-30", "received": 102, "sent": 180, "conversations": 24, "responseRate": 0.913 }],
  "origin": [{ "headline": "Promo de setembro", "sourceType": "ad", "conversations": 6, "answeredWithin": 6, "responseRate": 1 }],
  "dataSince": "2026-09-12T14:03:00Z"
}

dataSince é o primeiro evento medido do número. Antes dessa data o número é desconhecido, não zero.

Quando as métricas começam num número que já existia, a OnZap importa sozinha o histórico guardado: até 7 dias de eventos, se algum webhook da instância assinava as mensagens nesse período.

Quem está sem resposta agora

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/metrics/unanswered?minutes=60" \
  -H "X-Instance-Token: SEU_TOKEN"

Parâmetros: minutes (espera mínima, padrão 60), lookbackDays (até quantos dias para trás, padrão 7), limit (padrão 50) e includeGroups.

{
  "minutes": 60, "lookbackDays": 7, "total": 3,
  "items": [{
    "chatId": "[email protected]", "phone": "5511999990002", "name": "Bia",
    "waitingSince": "2026-10-01T13:05:00Z", "lastReceivedAt": "2026-10-01T13:09:00Z",
    "waitingMinutes": 187, "messages": 3
  }]
}

Definições

O que conta

• Mensagens vêm só de message.any (nunca de message, para não contar duas vezes).
• Ficam de fora: status (stories), listas de transmissão, canais, conversa consigo mesmo, histórico importado, reações e mensagens de sistema.
• Grupos ficam de fora por padrão (includeGroups=true inclui). Entrega e leitura não são medidas em grupo.

Mensagens

Na API oficial, a mensagem enviada pela API não gera message.any: ela passa a contar no primeiro status que chegar.

Conversas e resposta

• Conversa: sequência de mensagens de um chat sem um intervalo de 24 horas ou mais. Começa na primeira mensagem depois de 24 horas de silêncio, nos dois sentidos.
• conversations conta as iniciadas pelo cliente. As iniciadas pela empresa (disparos, follow-up) ficam em businessInitiated.
• Primeira resposta: numa conversa iniciada pelo cliente, o tempo da primeira mensagem recebida até a primeira enviada depois dela. Sai como mediana e p90, em segundos, com o número de amostras, no total e separado por origem (api e phone). Assim um robô que responde na hora não esconde o tempo do atendimento humano.
• Taxa de resposta: conversas iniciadas pelo cliente e respondidas em até N minutos (answeredWithin), dividido pelas que já tiveram N minutos para serem respondidas. As abertas há menos de N minutos e ainda sem resposta ficam em pending, fora da conta. unansweredWithin é o complemento.
• Sem resposta agora (unansweredNow e /metrics/unanswered): chats cuja última mensagem veio do cliente, sem nenhuma enviada depois, esperando há mais de N minutos. "Esperando desde" é a primeira mensagem recebida depois da última enviada.
• Origem por anúncio: conversas cuja primeira mensagem veio de um anúncio ou post (Click to WhatsApp), agrupadas pelo título do anúncio.

Saúde da conexão

Atualização

Os números são recalculados continuamente, com alguns segundos a um minuto de atraso em relação aos eventos. Um recibo de leitura que chega atrasado corrige o dia do envio, não o dia em que chegou.