O endpoint de Relatórios de Interações fornece dados de interações finalizadas com métricas de tempo calculadas para fins de relatório. Retorna apenas interações concluídas (onde isActive: false e analytics.finishedAt existe) com tempos de serviço e contagens de mensagens calculados.
authorization: Pode ser obtido através da plataforma no link: App SmartTalks.ai| Header | Tipo | Obrigatório | Descrição |
|---|---|---|---|
authorization | Authorization Bearer Token | ✔️ | A chave da sua API |
accept | application/json | ✔️ |
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).
Este endpoint suporta apenas o método GET.
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â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) | ||
limit | Integer | 10 | Número de itens a retornar. Min: 1, Max: 100 | |
offset | Integer | 0 | Número de itens a pular para paginação. Min: 0 | |
sortBy | String | createdAt | Campo para ordenação. Opções: createdAt, id | |
sortOrder | String | desc | Direção da ordenação. Opções: asc, desc |
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)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,
"items": [
{
"id": 12345,
"createdAt": "2024-01-15T10:30:00.000Z",
"clientName": "John Doe",
"channelType": "whatsapp",
"channelId": "5511999999999",
"originType": "RECEIVED",
"totalServiceTime": 1800,
"totalInteractionTime": 3600,
"totalWaitTime": 120,
"sentMessagesCount": 15,
"receivedMessagesCount": 12,
"csat": 5
}
]
}
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,
"items": [
{
"id": 12345,
"createdAt": "2024-01-15T10:30:00.000Z",
"clientName": "Maria Silva",
"channelType": "whatsapp",
"channelId": "5511999999999",
"originType": "RECEIVED",
"totalServiceTime": 1800,
"totalInteractionTime": 3600,
"totalWaitTime": 120,
"sentMessagesCount": 15,
"receivedMessagesCount": 12,
"csat": 5
},
{
"id": 12346,
"createdAt": "2024-01-14T14:20:00.000Z",
"clientName": "João Santos",
"channelType": "widget",
"channelId": "widget-abc123",
"originType": "CAMPAIGN",
"totalServiceTime": 900,
"totalInteractionTime": 1200,
"totalWaitTime": 60,
"sentMessagesCount": 8,
"receivedMessagesCount": 5,
"csat": 4
}
]
}
curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?startDate=2024-01-01&endDate=2024-12-31&limit=20&offset=40' \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {{apiToken}}'
Exemplo de retorno (com paginação):
{
"count": 500,
"items": [
{
"id": 12385,
"createdAt": "2024-01-10T08:15:00.000Z",
"clientName": "Ana Costa",
"channelType": "messenger",
"channelId": "1234567890",
"originType": "API",
"totalServiceTime": 2400,
"totalInteractionTime": 4800,
"totalWaitTime": 180,
"sentMessagesCount": 20,
"receivedMessagesCount": 18,
"csat": 5
}
]
}
curl -X GET 'https://hermes.smarttalks.ai/v2/interactions/reports?sortBy=id&sortOrder=asc&limit=50' \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {{apiToken}}'
Exemplo de retorno (ordenado por id ascendente):
{
"count": 150,
"items": [
{
"id": 1,
"createdAt": "2024-01-01T00:00:00.000Z",
"clientName": "Primeiro Cliente",
"channelType": "email",
"channelId": "cliente@exemplo.com",
"originType": "INTERNAL",
"totalServiceTime": 600,
"totalInteractionTime": 900,
"totalWaitTime": null,
"sentMessagesCount": 3,
"receivedMessagesCount": 2,
"csat": null
}
]
}
| Campo | Tipo | Descrição |
|---|---|---|
count | Integer | Total de interações correspondentes (para paginação) |
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 | Nome de exibição do cliente/contato (proveniente de display.label) |
items[].channelType | String | Tipo do canal (ex: whatsapp, widget, messenger, instagram, email) |
items[].channelId | String | Identificador do canal (ex: número de telefone, email) |
items[].originType | String | Tipo de origem: RECEIVED, CAMPAIGN, API, LIVE ACTIVE, INTERNAL, 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 analytics.createdAt até analytics.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[].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 (se coletada, proveniente de analytics.csat) |
| 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 |
Nota: Todos os tempos são retornados em segundos.
Os seguintes canais podem aparecer no campo channelType:
whatsapp - WhatsAppwidget - Chat Widgetmessenger - Facebook Messengerinstagram - Instagram Directemail - EmailOs seguintes tipos podem aparecer no campo originType:
RECEIVED - Interação recebida do clienteCAMPAIGN - Interação originada de campanhaAPI - Interação criada via APILIVE ACTIVE - Interação ativa ao vivoINTERNAL - Interação internaFREE ENTRY POINT - Ponto de entrada livre| 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 |
| 408 | Timeout - consulta demorou muito para executar |
| 500 | Erro interno do servidor |
| 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) |
offset: Number must be greater than or equal to 0 | Offset negativo |
| Header | Valores | Descrição |
|---|---|---|
X-Cache | HIT / MISS | Indica se a resposta foi servida do cache |
O endpoint aplica automaticamente os seguintes filtros nas interações:
isActive: false E analytics.finishedAt existentestatus: truegroupId e accountId do usuário