# API de Analytics Geral

Disponibiliza os mesmos dados do dashboard Analytics → Geral da plataforma, para que você possa consumir e analisar os números no seu próprio BI ou planilha. Os valores retornados são os mesmos exibidos no dashboard para o mesmo período e filtros.

São cinco endpoints, um para cada bloco do dashboard:

Endpoint Bloco do dashboard
/general/metrics Indicadores (contatos, interações, mensagens…)
/general/timeline Evolução no tempo (gráfico de linhas)
/general/channels Distribuição por canal (gráfico de pizza)
/general/geo Mapa por estado (DDD) e por país
/general/menus Itens de menu ou hashtags mais escolhidos

# Autenticação

Requer um token de API (Personal Access Token), gerado na plataforma em Configurações → Tokens. Sessões de usuário do app não são aceitas nesses endpoints.

O grupo de permissões vinculado ao token precisa ter acesso de leitura à rota /v1/analytics/api.

Header Tipo Obrigatório Descrição
authorization Authorization Bearer Token ✔️ O seu token de API
accept application/json ✔️

# Limites

  • Período máximo: 90 dias por consulta. Para períodos maiores, faça consultas em janelas de até 90 dias.
  • Rate limit: 30 requisições por minuto por token. Todas as respostas trazem os headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos até a janela reiniciar). Ao exceder, a API responde 429 com o header Retry-After (em segundos).
  • Cache: as respostas ficam em cache por 5 minutos (header X-Cache-Status: HIT | MISS). Consultar o mesmo período com mais frequência não traz dados mais novos.

# Métodos Disponíveis

Todos os endpoints suportam apenas GET, com parâmetros na query string.

# Parâmetros comuns

Aceitos por todos os endpoints. Parâmetros não listados são rejeitados com 400.

Parâmetro Tipo Obrigatório Padrão Descrição
startDate String ✔️ Início do período. YYYY-MM-DD (o dia inteiro, a partir de 00:00:00) ou data-hora ISO 8601 (ex.: 2026-09-01T08:00:00-03:00)
endDate String ✔️ Fim do período. YYYY-MM-DD (o dia inteiro, até 23:59:59.999) ou data-hora ISO 8601. No máximo 90 dias após startDate, contando os dois dias
timezone String America/Sao_Paulo Fuso horário (IANA) usado para interpretar datas sem hora. Ex.: America/Manaus
units String IDs de unidades, separados por vírgula (máx. 50)
tags String IDs de tags, separados por vírgula (máx. 50)

Nota: o timezone define os limites do período. Os agrupamentos por hora, dia, dia da semana, semana e mês seguem o horário de Brasília (UTC−3), igual ao dashboard.

Todas as respostas seguem o formato:

{
  "status": "ok",
  "period": { "start": "2026-09-01T03:00:00.000Z", "end": "2026-10-01T02:59:59.999Z", "timezone": "America/Sao_Paulo" },
  "filters": { },
  "data": { }
}

# GET - Indicadores

  GET https://hermes.g121.io/v1/analytics/api/general/metrics

Os números do topo do dashboard. Considera apenas interações com pelo menos uma mensagem do contato.

Campo Descrição
uniqueContacts Contatos únicos no período
interactions Total de interações
liveInteractions Interações que passaram por atendimento humano
notLiveInteractions Interações que não passaram por atendimento humano
liveInteractionsPercentage % de interações com atendimento humano
messages Total de mensagens
messagesSent Mensagens enviadas pela empresa (bot ou atendente)
messagesReceived Mensagens recebidas dos contatos
averageMessagesPerContact Média de mensagens por contato
afterHoursMessagesPercentage % de mensagens fora do horário comercial
curl -X GET 'https://hermes.g121.io/v1/analytics/api/general/metrics?startDate=2026-09-01&endDate=2026-09-30' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

{
  "status": "ok",
  "period": { "start": "2026-09-01T03:00:00.000Z", "end": "2026-10-01T02:59:59.999Z", "timezone": "America/Sao_Paulo" },
  "filters": {},
  "data": {
    "uniqueContacts": 1500,
    "interactions": 2000,
    "liveInteractions": 500,
    "notLiveInteractions": 1500,
    "liveInteractionsPercentage": 25,
    "messages": 12000,
    "messagesSent": 7000,
    "messagesReceived": 5000,
    "averageMessagesPerContact": 8,
    "afterHoursMessagesPercentage": 12.34
  }
}

# GET - Evolução no tempo

  GET https://hermes.g121.io/v1/analytics/api/general/timeline

Uma série por canal, com o total de cada período.

Parâmetro Tipo Padrão Valores
metric String users users, interactions, messagesSent, messagesReceived
groupBy String days hours, days, daysOfWeek, weeks, months

Formato de period conforme o groupBy:

groupBy period
hours Número da hora, de 0 a 23
days Data YYYY-MM-DD
daysOfWeek Número do dia, de 0 (domingo) a 6 (sábado)
weeks Rótulo da semana do ano, ex.: "39ªw '26"
months Mês YYYY-MM
curl -X GET 'https://hermes.g121.io/v1/analytics/api/general/timeline?startDate=2026-09-01&endDate=2026-09-30&metric=interactions&groupBy=days' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

{
  "status": "ok",
  "period": { "start": "2026-09-01T03:00:00.000Z", "end": "2026-10-01T02:59:59.999Z", "timezone": "America/Sao_Paulo" },
  "filters": { "metric": "interactions", "groupBy": "days" },
  "data": [
    {
      "name": "Atendimento (whatsapp)",
      "data": [
        { "period": "2026-09-01", "value": 84 },
        { "period": "2026-09-02", "value": 97 }
      ]
    }
  ]
}

# GET - Por canal

  GET https://hermes.g121.io/v1/analytics/api/general/channels
Parâmetro Tipo Padrão Valores
metric String users users, interactions, messagesSent, messagesReceived
curl -X GET 'https://hermes.g121.io/v1/analytics/api/general/channels?startDate=2026-09-01&endDate=2026-09-30&metric=users' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

{
  "status": "ok",
  "period": { "start": "2026-09-01T03:00:00.000Z", "end": "2026-10-01T02:59:59.999Z", "timezone": "America/Sao_Paulo" },
  "filters": { "metric": "users" },
  "data": [
    { "name": "Atendimento (whatsapp)", "value": 1200 },
    { "name": "Site (widget)", "value": 300 }
  ]
}

# GET - Mapa

  GET https://hermes.g121.io/v1/analytics/api/general/geo

Distribuição por estado (pelo DDD) e por país. Considera apenas canais de WhatsApp.

Parâmetro Tipo Padrão Valores
metric String users users, interactions, messagesSent, messagesReceived
curl -X GET 'https://hermes.g121.io/v1/analytics/api/general/geo?startDate=2026-09-01&endDate=2026-09-30' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

{
  "status": "ok",
  "period": { "start": "2026-09-01T03:00:00.000Z", "end": "2026-10-01T02:59:59.999Z", "timezone": "America/Sao_Paulo" },
  "filters": { "metric": "users" },
  "data": {
    "brazil": {
      "total": 1180,
      "states": [
        { "state": "br-sp", "value": 700 },
        { "state": "br-rj", "value": 480 }
      ]
    },
    "countries": [{ "country": "br", "value": 1180 }]
  }
}

# GET - Menus e hashtags

  GET https://hermes.g121.io/v1/analytics/api/general/menus

Quantas vezes cada opção de menu (ou hashtag) foi escolhida, em ordem decrescente.

Parâmetro Tipo Padrão Valores
type String menu menu, hashtag
curl -X GET 'https://hermes.g121.io/v1/analytics/api/general/menus?startDate=2026-09-01&endDate=2026-09-30&type=menu' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

{
  "status": "ok",
  "period": { "start": "2026-09-01T03:00:00.000Z", "end": "2026-10-01T02:59:59.999Z", "timezone": "America/Sao_Paulo" },
  "filters": { "type": "menu" },
  "data": [
    { "menu": "Menu principal", "item": "Falar com atendente", "total": 320 },
    { "menu": "Menu principal", "item": "2ª via de boleto", "total": 210 }
  ]
}

# Erros

Status Quando
400 Parâmetro inválido ou desconhecido, período maior que 90 dias, endDate antes de startDate
401 Token inválido, expirado ou revogado
403 Autenticação que não é token de API, ou token sem permissão para /v1/analytics/api
429 Rate limit excedido. Aguarde os segundos informados em Retry-After
503 Não foi possível verificar as permissões do token no momento. Tente novamente
Exemplo de retorno 400:

{
  "status": "error",
  "message": "The period cannot exceed 90 days (requested 120)"
}