# 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 (state=active) ou por todas as interações do período independente do estado (state=all) através do parâmetro state.

Quer o conjunto completo de interações do período (ativas + finalizadas + abandonadas), igual ao relatório da plataforma? Use state=all. O comportamento padrão (sem state) continua retornando apenas finalizadas.

authorization: Pode ser obtido através da plataforma no link: App SmartTalks.ai

# 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). O total (count) é cacheado à parte por 10 minutos e compartilhado entre todas as páginas de um mesmo filtro.

# 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 com métricas de tempo calculadas para relatórios via requisição GET. Por padrão retorna apenas finalizadas; use state=all para todas ou state=active para as em andamento. Os parâmetros de query devem ser passados como parâmetros de URL.

# Parâmetros de Query

Parâmetro	Tipo	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: `all` (todas), `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`. Aceita múltiplos valores (ver abaixo)
`originType`	`String`		Filtro por origem: `LIVE ACTIVE`, `RECEIVED`, `CAMPAIGN`, `INTERNAL`, `API`, `FREE ENTRY POINT` (ou o alias `ADS`). Aceita múltiplos valores (ver abaixo)
`attendantId`	`String`		Filtro por ObjectId do atendente (24 caracteres hex)
`campaignId`	`String`		Filtro por ObjectId da campanha (24 caracteres hex)
`unitId`	`String`		Filtro por ObjectId de uma unidade específica (24 caracteres hex). Respeita o escopo de unidades do usuário
`limit`	`Integer`	`10`	Número de itens a retornar. Min: 1, Max: 250
`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`

# Filtros com Múltiplos Valores (`channel` e `originType`)

Os parâmetros channel e originType aceitam um ou mais valores, em dois formatos:

Separado por vírgula: ?channel=whatsapp,instagram
Repetido: ?channel=whatsapp&channel=instagram

Ambos podem ser combinados e os valores são validados individualmente (um valor inválido retorna 400). Filtrar por um canal whatsapp inclui automaticamente todos os provedores (dialog360, gupshup, whatsappweb, whatsappevo).

Alias ADS: na origem, o valor armazenado FREE ENTRY POINT é retornado como ADS. Por consistência, o filtro originType aceita tanto ADS quanto FREE ENTRY POINT (ambos casam com as mesmas interações).

# 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:

Primeira requisição: Omitir o parâmetro cursor
Requisições seguintes: Usar o valor nextCursor da resposta anterior
Ú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",
      "flowId": "689f263428e1d3880b13761e",
      "flowName": "Orquestrador",
      "totalServiceTime": 300,
      "totalInteractionTime": 450,
      "totalWaitTime": 60,
      "responseTime": 15,
      "sentMessagesCount": 5,
      "receivedMessagesCount": 8,
      "csat": 5,
      "attendantId": "507f1f77bcf86cd799439011",
      "attendantName": "Maria Silva",
      "attendants": [{ "id": "507f1f77bcf86cd799439011", "name": "Maria Silva" }],
      "units": [{ "id": "688cc60b359c2af61a688c38", "name": "Vendas online" }],
      "evidences": [
        {
          "addonId": "68ab16767bdaa63b199bd34b",
          "addonLabel": "Motivo do Contato",
          "message": "Dúvida sobre pagamento"
        }
      ],
      "tags": [
        {
          "tagId": "69ea7552f669d645e4119c21",
          "name": "Hospedagem",
          "assignedBy": "689e525f0fcdd32a03f4c03f",
          "assignedAt": "2024-01-15T10:31:00.000Z",
          "type": "interaction"
        }
      ],
      "finishedAt": "2024-01-15T10:35:00.000Z",
      "finishedBy": [
        {
          "id": "507f1f77bcf86cd799439011",
          "name": "Maria Silva",
          "finishedAt": "2024-01-15T10:35:00.000Z"
        }
      ],
      "answeredAt": "2024-01-15T10:30:30.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 Filtro por Múltiplos Canais e Unidade

# channel e originType aceitam múltiplos valores (CSV ou repetido); unitId filtra uma unidade
curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?channel=whatsapp,instagram&originType=RECEIVED,ADS&unitId=688cc60b359c2af61a688c38' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{apiToken}}'

Exemplo de retorno (WhatsApp + Instagram, origem RECEIVED ou ADS, unidade específica):

{
  "count": 87,
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1VDA5OjAwOjAwLjAwMFoiLCJfaWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwMjEifQ==",
  "items": [
    {
      "id": 12390,
      "createdAt": "2024-01-15T09:30:00.000Z",
      "clientName": "Lucas Pereira",
      "channelType": "instagram",
      "contactIdentifier": "ig_user_998877",
      "originType": "ADS",
      "flowId": "6914f9e3fbfa022ab2c159f2",
      "flowName": "Venda de Hospedagem",
      "totalServiceTime": 210,
      "totalInteractionTime": 330,
      "totalWaitTime": 45,
      "responseTime": 12,
      "sentMessagesCount": 6,
      "receivedMessagesCount": 9,
      "csat": 5,
      "attendantId": "692069c488e6abbeeac8b7ea",
      "attendantName": "Jéssica",
      "attendants": [{ "id": "692069c488e6abbeeac8b7ea", "name": "Jéssica" }],
      "units": [{ "id": "688cc60b359c2af61a688c38", "name": "Vendas online" }],
      "evidences": [],
      "tags": [],
      "finishedAt": "2024-01-15T09:33:30.000Z",
      "liveAt": "2024-01-15T09:30:30.000Z",
      "takeAt": "2024-01-15T09:31:00.000Z",
      "expiredBy": null,
      "campaignId": null,
      "lastMessageAt": "2024-01-15T09:32:00.000Z",
      "isIn24hWindow": true
    }
  ]
}

# 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 (Todas as Interações)

Use state=all para obter todas as interações do período (ativas + finalizadas + abandonadas), reproduzindo o total exibido no relatório da plataforma. É o filtro recomendado para reconciliar dados com a interface.

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

Exemplo de retorno (todos os estados do período):

{
  "count": 19513,
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTMxVDIzOjUwOjAwLjAwMFoiLCJfaWQiOiI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkxMDAifQ==",
  "items": [
    {
      "id": 12500,
      "createdAt": "2024-01-31T23:50:00.000Z",
      "clientName": "Regina Souza",
      "channelType": "whatsapp",
      "contactIdentifier": "5585999990000",
      "originType": "RECEIVED",
      "flowId": "689f263428e1d3880b13761e",
      "flowName": "SDR Vacation Club",
      "attendantId": "68d6b4e06d9816914c2c71de",
      "attendantName": "Isaque Dantas",
      "attendants": [{ "id": "68d6b4e06d9816914c2c71de", "name": "Isaque Dantas" }],
      "units": [{ "id": "688cc5fd359c2af61a688a4f", "name": "Vacation online" }],
      "tags": [
        { "tagId": "69275156f669d645e4119c10", "name": "Hospedagem", "type": "contact" }
      ],
      "finishedAt": "2024-01-31T23:58:00.000Z",
      "finishedBy": [
        { "id": "68d6b4e06d9816914c2c71de", "name": "Isaque Dantas", "finishedAt": "2024-01-31T23:58:00.000Z" }
      ],
      "answeredAt": "2024-01-31T23:51:00.000Z",
      "liveAt": "2024-01-31T23:50:30.000Z",
      "takeAt": "2024-01-31T23:50:45.000Z",
      "expiredBy": null,
      "campaignId": null,
      "lastMessageAt": "2024-01-31T23:57:00.000Z",
      "isIn24hWindow": true
    }
  ]
}

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

state=active retorna todas as interações atualmente em andamento (isActive: true), sem qualquer restrição de janela temporal.

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`, `INTERNAL`, `LIVE ACTIVE`, `ADS` (alias de `FREE ENTRY POINT` na saída)
`items[].flowId`	`String/null`	ObjectId do fluxo/agente que atendeu a interação (24 caracteres hex)
`items[].flowName`	`String/null`	Nome do fluxo/agente. `null` se não encontrado
`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[].attendantName`	`String/null`	Nome do primeiro atendente. `null` se não encontrado
`items[].attendants`	`Array`	Lista de atendentes da interação, cada um como `{ id, name }`
`items[].attendants[].id`	`String`	ObjectId do atendente
`items[].attendants[].name`	`String/null`	Nome do atendente. `null` se não encontrado
`items[].units`	`Array`	Lista de unidades da interação, cada uma como `{ id, name }`
`items[].units[].id`	`String`	ObjectId da unidade
`items[].units[].name`	`String/null`	Nome da unidade. `null` se não encontrado
`items[].evidences`	`Array`	Evidências capturadas na interação, cada uma como `{ addonId, addonLabel, message }`
`items[].evidences[].addonId`	`String`	ObjectId do addon (campo) da evidência
`items[].evidences[].addonLabel`	`String/null`	Rótulo do addon. `null` se não encontrado
`items[].evidences[].message`	`Mixed`	Valor capturado da evidência
`items[].tags`	`Array`	Tags da interação. Tags sem identificador são omitidas
`items[].tags[].tagId`	`String`	ObjectId da tag (para tags de contato, usa o `_id` da tag de contato)
`items[].tags[].name`	`String/null`	Nome da tag (resolvido). `null` se a tag não for encontrada
`items[].tags[].assignedBy`	`String/null`	ObjectId de quem atribuiu a tag (ausente em tags de contato)
`items[].tags[].assignedAt`	`String/null`	Timestamp ISO 8601 de atribuição (ausente em tags de contato)
`items[].tags[].type`	`String`	Tipo da tag: `interaction` ou `contact`
`items[].finishedAt`	`String/null`	Timestamp ISO 8601 de quando a interação foi finalizada
`items[].finishedBy`	`Array`	Responsáveis pelo encerramento (a interação pode ser encerrada por mais de um), cada um como `{ id, name, finishedAt }`. Vazio quando não há registro. Obs.: este dado passou a ser registrado recentemente, então interações antigas podem não tê-lo
`items[].finishedBy[].id`	`String`	ObjectId do usuário que encerrou
`items[].finishedBy[].name`	`String/null`	Nome do usuário que encerrou. `null` se não encontrado
`items[].finishedBy[].finishedAt`	`String/null`	Timestamp ISO 8601 do encerramento por esse usuário
`items[].answeredAt`	`String/null`	Timestamp ISO 8601 da primeira resposta do atendente (atendimento iniciado)
`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
INTERNAL - Interação interna
LIVE ACTIVE - Interação ativa ao vivo
ADS - Ponto de entrada livre / anúncio (valor armazenado FREE ENTRY POINT, retornado como ADS)

No filtro originType, tanto ADS quanto FREE ENTRY POINT são aceitos e casam com as mesmas interações.

# 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 250`	Limite maior que o máximo permitido (250)
`limit: Number must be greater than or equal to 1`	Limite menor que o mínimo permitido (1)
`state: Invalid enum value. Expected 'all' \\| '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
`originType: Invalid enum value`	Valor inválido para originType
`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:

Comportamento padrão (state=finished): isActive: false E analytics.finishedAt existente
Interações ativas (state=active): isActive: true (interações em andamento, sem restrição de janela temporal)
Todas as interações (state=all): nenhum filtro de estado aplicado — retorna ativas, finalizadas e abandonadas (paridade com o relatório da plataforma)
Registros ativos: status: true
Contexto de autenticação: Corresponde ao groupId e accountId do usuário
Restrições de unidade: Se o usuário tem restrições de unidade, apenas interações correspondentes são retornadas
Filtro unitId: Quando informado, filtra por aquela unidade respeitando o escopo do usuário. Uma unidade fora do escopo retorna lista vazia (não expõe dados)

# 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	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

# API de Relatórios de Interações

# Headers Obrigatórios

# Cache

# Métodos Disponíveis

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

# Parâmetros de Query

# Filtros com Múltiplos Valores (channel e originType)

# Formatos de Data Suportados

# Paginação Baseada em Cursor

# Exemplo com Filtro por Múltiplos Canais e Unidade

# Exemplo com Intervalo de Datas

# Exemplo com Paginação (Cursor)

# Exemplo com Ordenação Ascendente

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

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

# Exemplo com Filtro por Tipo (Apenas Bot)

# Exemplo com Filtro por Canal

# Campos da Resposta

# Cálculo das Métricas de Tempo

# Canais Disponíveis

# Tipos de Origem

# Códigos de Status

# Erros Comuns (400)

# Headers de Resposta

# Filtros Automáticos

# GET - Resumo de KPIs (Summary)

# Parâmetros de Query

# Métricas Retornadas

# Definições

# Exemplos de Resposta

# Campos da Resposta

# Filtros com Múltiplos Valores (`channel` e `originType`)