# API de Relatórios de Interações

O endpoint de Relatórios de Interações fornece dados de interações com métricas de tempo calculadas para fins de relatório. Por padrão retorna interações finalizadas (onde isActive: false e analytics.finishedAt existe), mas também suporta filtrar por interações ativas em andamento através do parâmetro state.

# Headers Obrigatórios

Header Tipo Obrigatório Descrição
authorization Authorization Bearer Token ✔️ A chave da sua API
accept application/json ✔️

# Cache

Este endpoint está em cache por 5 minutos. As respostas são cacheadas para melhorar o desempenho. O header X-Cache indica se a resposta veio do cache (HIT) ou não (MISS).

# Métodos Disponíveis

Este endpoint suporta apenas o método GET.

# GET - Buscar Relatórios de Interações

  GET https://hermes.smarttalks.ai/v2/interactions/reports

Recupera dados de interações finalizadas com métricas de tempo calculadas para relatórios via requisição GET. Os parâmetros de query devem ser passados como parâmetros de URL.

# Parâmetros de Query

Parâmetro Tipo Obrigatório Padrão Descrição
startDate String Data de início do filtro (ex: 2024-01-01, 01/01/2024)
endDate String Data de término do filtro (ex: 2024-12-31, 31/12/2024)
state String finished Filtro por estado: active (em andamento) ou finished (finalizadas)
type String Filtro por tipo: live (humano) ou bot (automatizado)
channel String Filtro por canal: messenger, instagram, widget, whatsapp, soulmachines, email, nvoip
originType String Filtro por origem: LIVE ACTIVE, RECEIVED, CAMPAIGN, API, FREE ENTRY POINT, APPOINTMENT_CREATE
attendantId String Filtro por ObjectId do atendente (24 caracteres hex)
campaignId String Filtro por ObjectId da campanha (24 caracteres hex)
limit Integer 10 Número de itens a retornar. Min: 1, Max: 100
cursor String Cursor base64 para próxima página (use nextCursor da resposta anterior)
sortOrder String desc Direção da ordenação. Opções: asc, desc

# Formatos de Data Suportados

O endpoint aceita datas em múltiplos formatos com suporte a timezone (padrão UTC):

  • YYYY-MM-DD (ex: 2024-01-15)
  • YYYY/MM/DD (ex: 2024/01/15)
  • DD/MM/YYYY (ex: 15/01/2024)
  • DD-MM-YYYY (ex: 15-01-2024)
  • DD/MM/YY (ex: 15/01/24)
  • DD-MM-YY (ex: 15-01-24)
  • MM/DD/YY (ex: 01/15/24)

# Paginação Baseada em Cursor

Este endpoint utiliza paginação baseada em cursor para melhor performance em grandes conjuntos de dados.

Como usar:

  1. Primeira requisição: Omitir o parâmetro cursor
  2. Requisições seguintes: Usar o valor nextCursor da resposta anterior
  3. Última página: Quando hasMore for false, não há mais páginas

Benefícios:

  • Performance consistente independente da profundidade da página
  • Sem deslocamento de dados entre páginas
  • Utiliza queries indexadas

Nota: Os resultados são sempre ordenados por createdAt. Use sortOrder para controlar a direção (asc ou desc).

curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno:

{
  "count": 150,
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJfaWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwMTEifQ==",
  "items": [
    {
      "id": 12345,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clientName": "John Doe",
      "channelType": "whatsapp",
      "contactIdentifier": "5511999999999",
      "originType": "RECEIVED",
      "totalServiceTime": 300,
      "totalInteractionTime": 450,
      "totalWaitTime": 60,
      "responseTime": 15,
      "sentMessagesCount": 5,
      "receivedMessagesCount": 8,
      "csat": 5,
      "attendantId": "507f1f77bcf86cd799439011",
      "finishedAt": "2024-01-15T10:35:00.000Z",
      "liveAt": "2024-01-15T10:28:00.000Z",
      "takeAt": "2024-01-15T10:29:00.000Z",
      "expiredBy": null,
      "campaignId": null,
      "lastMessageAt": "2024-01-15T10:25:00.000Z",
      "isIn24hWindow": false
    }
  ]
}

# Exemplo com Intervalo de Datas

curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?startDate=2024-01-01&endDate=2024-12-31' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (com intervalo de datas):

{
  "count": 500,
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE0VDE0OjIwOjAwLjAwMFoiLCJfaWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwMTIifQ==",
  "items": [
    {
      "id": 12345,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clientName": "Maria Silva",
      "channelType": "whatsapp",
      "contactIdentifier": "5511999999999",
      "originType": "RECEIVED",
      "totalServiceTime": 300,
      "totalInteractionTime": 450,
      "totalWaitTime": 60,
      "responseTime": 15,
      "sentMessagesCount": 5,
      "receivedMessagesCount": 8,
      "csat": 5,
      "attendantId": "507f1f77bcf86cd799439011",
      "finishedAt": "2024-01-15T10:35:00.000Z",
      "liveAt": "2024-01-15T10:28:00.000Z",
      "takeAt": "2024-01-15T10:29:00.000Z",
      "expiredBy": null,
      "campaignId": null,
      "lastMessageAt": "2024-01-15T10:25:00.000Z",
      "isIn24hWindow": false
    },
    {
      "id": 12346,
      "createdAt": "2024-01-14T14:20:00.000Z",
      "clientName": "João Santos",
      "channelType": "widget",
      "contactIdentifier": "session_abc123",
      "originType": "CAMPAIGN",
      "totalServiceTime": 180,
      "totalInteractionTime": 240,
      "totalWaitTime": 30,
      "responseTime": 5,
      "sentMessagesCount": 4,
      "receivedMessagesCount": 3,
      "csat": 4,
      "attendantId": "507f1f77bcf86cd799439055",
      "finishedAt": "2024-01-14T14:24:00.000Z",
      "liveAt": "2024-01-14T14:20:30.000Z",
      "takeAt": "2024-01-14T14:21:00.000Z",
      "expiredBy": null,
      "campaignId": "507f1f77bcf86cd799439088",
      "lastMessageAt": "2024-01-14T14:15:00.000Z",
      "isIn24hWindow": false
    }
  ]
}

# Exemplo com Paginação (Cursor)

# Primeira requisição (sem cursor)
curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?startDate=2024-01-01&endDate=2024-12-31&limit=20' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

# Requisições seguintes (com cursor da resposta anterior)
curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?startDate=2024-01-01&endDate=2024-12-31&limit=20&cursor=eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTEwVDA4OjE1OjAwLjAwMFoiLCJfaWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwOTkifQ==' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (com paginação cursor):

{
  "count": 500,
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTEwVDA4OjE1OjAwLjAwMFoiLCJfaWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwOTkifQ==",
  "items": [
    {
      "id": 12385,
      "createdAt": "2024-01-10T08:15:00.000Z",
      "clientName": "Ana Costa",
      "channelType": "messenger",
      "contactIdentifier": "fb_user_1234567890",
      "originType": "API",
      "totalServiceTime": 240,
      "totalInteractionTime": 480,
      "totalWaitTime": 180,
      "responseTime": 10,
      "sentMessagesCount": 20,
      "receivedMessagesCount": 18,
      "csat": 5,
      "attendantId": "507f1f77bcf86cd799439099",
      "finishedAt": "2024-01-10T08:23:00.000Z",
      "liveAt": "2024-01-10T08:15:00.000Z",
      "takeAt": "2024-01-10T08:18:00.000Z",
      "expiredBy": null,
      "campaignId": null,
      "lastMessageAt": "2024-01-10T08:20:00.000Z",
      "isIn24hWindow": false
    }
  ]
}

# Exemplo com Ordenação Ascendente

curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?sortOrder=asc&limit=50' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (ordenado por createdAt ascendente):

{
  "count": 150,
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTAxVDAwOjAyOjAwLjAwMFoiLCJfaWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwMDEifQ==",
  "items": [
    {
      "id": 1,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "clientName": "Primeiro Cliente",
      "channelType": "email",
      "contactIdentifier": "cliente@exemplo.com",
      "originType": "LIVE ACTIVE",
      "totalServiceTime": null,
      "totalInteractionTime": 120,
      "totalWaitTime": null,
      "responseTime": null,
      "sentMessagesCount": 3,
      "receivedMessagesCount": 2,
      "csat": null,
      "attendantId": null,
      "finishedAt": "2024-01-01T00:02:00.000Z",
      "liveAt": null,
      "takeAt": null,
      "expiredBy": "bot_timeout",
      "campaignId": null,
      "lastMessageAt": "2023-12-31T20:00:00.000Z",
      "isIn24hWindow": null
    }
  ]
}

# Exemplo com Filtro por Estado (Interações Ativas)

curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?state=active&limit=20' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (interações ativas/em andamento):

{
  "count": 10,
  "hasMore": false,
  "nextCursor": null,
  "items": [
    {
      "id": 12400,
      "createdAt": "2024-01-15T14:00:00.000Z",
      "clientName": "Carlos Mendes",
      "channelType": "whatsapp",
      "contactIdentifier": "5511988887777",
      "originType": "RECEIVED",
      "totalServiceTime": null,
      "totalInteractionTime": null,
      "totalWaitTime": 120,
      "responseTime": 10,
      "sentMessagesCount": 3,
      "receivedMessagesCount": 5,
      "csat": null,
      "attendantId": "507f1f77bcf86cd799439099",
      "finishedAt": null,
      "liveAt": "2024-01-15T14:00:00.000Z",
      "takeAt": "2024-01-15T14:02:00.000Z",
      "expiredBy": null,
      "campaignId": null,
      "lastMessageAt": "2024-01-15T14:05:00.000Z",
      "isIn24hWindow": true
    }
  ]
}

# Exemplo com Filtro por Tipo (Apenas Bot)

curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?type=bot&startDate=2024-01-01&endDate=2024-01-31' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (apenas interações de bot):

{
  "count": 50,
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1VDExOjAwOjAwLjAwMFoiLCJfaWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwNTAifQ==",
  "items": [
    {
      "id": 12350,
      "createdAt": "2024-01-15T11:00:00.000Z",
      "clientName": "Jane Smith",
      "channelType": "widget",
      "contactIdentifier": "session_abc123",
      "originType": "RECEIVED",
      "totalServiceTime": null,
      "totalInteractionTime": 120,
      "totalWaitTime": null,
      "responseTime": null,
      "sentMessagesCount": 3,
      "receivedMessagesCount": 4,
      "csat": null,
      "attendantId": null,
      "finishedAt": "2024-01-15T11:02:00.000Z",
      "liveAt": null,
      "takeAt": null,
      "expiredBy": "bot_timeout",
      "campaignId": null,
      "lastMessageAt": "2024-01-14T08:00:00.000Z",
      "isIn24hWindow": null
    }
  ]
}

# Exemplo com Filtro por Canal

curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?channel=whatsapp&type=live&limit=10' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (WhatsApp com atendimento humano):

{
  "count": 200,
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJfaWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwNDUifQ==",
  "items": [
    {
      "id": 12345,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clientName": "Pedro Oliveira",
      "channelType": "whatsapp",
      "contactIdentifier": "5511999998888",
      "originType": "RECEIVED",
      "totalServiceTime": 300,
      "totalInteractionTime": 450,
      "totalWaitTime": 60,
      "responseTime": 15,
      "sentMessagesCount": 5,
      "receivedMessagesCount": 8,
      "csat": 5,
      "attendantId": "507f1f77bcf86cd799439011",
      "finishedAt": "2024-01-15T10:35:00.000Z",
      "liveAt": "2024-01-15T10:28:00.000Z",
      "takeAt": "2024-01-15T10:29:00.000Z",
      "expiredBy": null,
      "campaignId": null,
      "lastMessageAt": "2024-01-15T10:25:00.000Z",
      "isIn24hWindow": false
    }
  ]
}

# Campos da Resposta

Campo Tipo Descrição
count Integer Total de interações correspondentes aos filtros
hasMore Boolean Indica se existem mais resultados após a página atual
nextCursor String/null Cursor para próxima página (passar como cursor na próxima requisição). null na última página
items Array Array de objetos de relatório de interação
items[].id Integer ID numérico da interação
items[].createdAt String (ISO 8601) Timestamp de criação da interação
items[].clientName String/null Nome de exibição do cliente/contato (proveniente de display.label)
items[].channelType String/null Tipo do canal: whatsapp, widget, messenger, instagram, email, soulmachines, nvoip
items[].contactIdentifier String/null Identificador do contato: telefone, email, etc. (proveniente de activeChannelId)
items[].originType String/null Tipo de origem: RECEIVED, CAMPAIGN, API, LIVE ACTIVE, FREE ENTRY POINT
items[].totalServiceTime Integer/null Tempo do atendente assumir até finalizar em segundos. null se takeAt não estiver definido
items[].totalInteractionTime Integer/null Duração total da interação em segundos (de createdAt até finishedAt)
items[].totalWaitTime Integer/null Tempo de espera antes do atendente assumir em segundos (de liveAt até takeAt). null se qualquer timestamp não estiver definido
items[].responseTime Integer/null Tempo até primeira resposta do atendente em segundos (de takeAt até answeredAt). null se qualquer timestamp não estiver definido
items[].sentMessagesCount Integer Contagem de mensagens enviadas por atendentes (mensagens com userId)
items[].receivedMessagesCount Integer Contagem de mensagens recebidas do cliente (mensagens com clientId)
items[].csat Integer/null Pontuação de satisfação do cliente (1-5, se coletada)
items[].attendantId String/null ObjectId do primeiro atendente que assumiu a interação (24 caracteres hex)
items[].finishedAt String/null Timestamp ISO 8601 de quando a interação foi finalizada
items[].liveAt String/null Timestamp ISO 8601 de quando entrou na fila de atendimento humano
items[].takeAt String/null Timestamp ISO 8601 de quando o atendente assumiu a interação
items[].expiredBy String/null O que causou a expiração (ex: bot_timeout, queue_timeout, inactivity)
items[].campaignId String/null ObjectId da campanha associada (24 caracteres hex)
items[].lastMessageAt String/null Timestamp ISO 8601 da última mensagem recebida do cliente
items[].isIn24hWindow Boolean/null Se a conversa está dentro da janela de 24h para envio de mensagens sem template (Meta)

# Cálculo das Métricas de Tempo

Métrica Fórmula Descrição
totalServiceTime analytics.finishedAt - analytics.takeAt Quanto tempo o atendente gastou atendendo a interação
totalInteractionTime analytics.finishedAt - analytics.createdAt Duração total desde a criação até a conclusão
totalWaitTime analytics.takeAt - analytics.liveAt Quanto tempo o cliente esperou antes de um atendente assumir
responseTime analytics.answeredAt - analytics.takeAt Quanto tempo até a primeira resposta do atendente

Nota: Todos os tempos são retornados em segundos.

# Canais Disponíveis

Os seguintes canais podem aparecer no campo channelType:

  • whatsapp - WhatsApp
  • widget - Chat Widget
  • messenger - Facebook Messenger
  • instagram - Instagram Direct
  • email - Email
  • soulmachines - Soul Machines
  • nvoip - NVoIP

# Tipos de Origem

Os seguintes tipos podem aparecer no campo originType:

  • RECEIVED - Interação recebida do cliente
  • CAMPAIGN - Interação originada de campanha
  • API - Interação criada via API
  • LIVE ACTIVE - Interação ativa ao vivo
  • FREE ENTRY POINT - Ponto de entrada livre

# Códigos de Status

Status Descrição
200 Sucesso ao obter os relatórios
400 Requisição inválida - parâmetros inválidos
401 Não autorizado - token inválido ou ausente
403 Proibido - permissões insuficientes
408 Timeout - consulta demorou muito para executar
500 Erro interno do servidor

# Erros Comuns (400)

Erro Descrição
limit: Number must be less than or equal to 100 Limite maior que o máximo permitido (100)
limit: Number must be greater than or equal to 1 Limite menor que o mínimo permitido (1)
state: Invalid enum value. Expected 'active' \| 'finished' Valor inválido para state
type: Invalid enum value. Expected 'live' \| 'bot' Valor inválido para type
channel: Invalid enum value Valor inválido para channel
Cast to ObjectId failed for value "..." at path "attendantId" ObjectId com formato inválido

# Headers de Resposta

Header Valores Descrição
X-Cache HIT / MISS Indica se a resposta foi servida do cache

# Filtros Automáticos

O endpoint aplica automaticamente os seguintes filtros nas interações:

  1. Comportamento padrão (state=finished): isActive: false E analytics.finishedAt existente
  2. Interações ativas (state=active): isActive: true (interações em andamento)
  3. Registros ativos: status: true
  4. Contexto de autenticação: Corresponde ao groupId e accountId do usuário
  5. Restrições de unidade: Se o usuário tem restrições de unidade, apenas interações correspondentes são retornadas

# GET - Resumo de KPIs (Summary)

  GET https://hermes.smarttalks.ai/v2/interactions/reports/summary

Retorna métricas agregadas (KPIs) para interações finalizadas, incluindo taxa de deflexão, taxa de handoff e latência média do bot.

# Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição
startDate String Data de início do filtro (ex: 2024-01-01, 01/01/2024)
endDate String Data de término do filtro (ex: 2024-12-31, 31/12/2024)
channel String Filtro por canal: messenger, instagram, widget, whatsapp, soulmachines, email, nvoip

# Métricas Retornadas

Métrica Fórmula Descrição
deflectionRate (Interações só bot) / Total finalizadas × 100 % de interações resolvidas pelo bot sem intervenção humana
handoffRate (Interações com humano) / Total finalizadas × 100 % de interações que necessitaram de atendimento humano
avgLatencyMs Média do tempo entre msg cliente → resposta bot Tempo médio de resposta do bot em milissegundos

# Definições

Bot-only (Deflexão):

  • attendants.length === 0 (nenhum humano atribuído)
  • analytics.takeAt não existe (humano nunca assumiu)

Intervenção Humana (Handoff):

  • attendants.length >= 1 OU analytics.takeAt existe

Cálculo de Latência AI:

  • Calculado apenas para interações bot-only
  • Mede o tempo entre mensagem do cliente e resposta subsequente do bot
curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports/summary?startDate=2024-01-01&endDate=2024-01-31&channel=whatsapp' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno:

{
  "total": 1500,
  "deflectionRate": "72.50",
  "handoffRate": "27.50",
  "avgLatencyMs": 1250
}

# Exemplos de Resposta

Alta deflexão (bot eficiente):

{
  "total": 500,
  "deflectionRate": "92.00",
  "handoffRate": "8.00",
  "avgLatencyMs": 850
}

Sem dados de latência (todas interações com humano):

{
  "total": 200,
  "deflectionRate": "0.00",
  "handoffRate": "100.00",
  "avgLatencyMs": null
}

Nenhuma interação encontrada:

{
  "total": 0,
  "deflectionRate": "0.00",
  "handoffRate": "0.00",
  "avgLatencyMs": null
}

# Campos da Resposta

Campo Tipo Descrição
total Integer Total de interações finalizadas correspondentes aos filtros
deflectionRate String Taxa de deflexão em % (2 casas decimais)
handoffRate String Taxa de handoff em % (2 casas decimais)
avgLatencyMs Integer/null Latência média do bot em ms. null se não houver interações bot-only
Last Updated: 1/23/2026, 11:02:05 PM