Analytics

Analysis and Business Intelligence endpoints. Provide aggregated data on calls, agents, and trends. Requires manager role or above.

Endpoints

Method	Endpoint	Description	Minimum Role
GET	/api/v1/analytics/overview	Overview (KPIs)	manager
GET	/api/v1/analytics/hourly	Hourly distribution	manager
GET	/api/v1/analytics/agents	Agent performance	manager
GET	/api/v1/analytics/trends	Time-based trends	manager
POST	/api/v1/analytics/refresh-views	Refresh materialized views	manager

---

Overview

Returns Key Performance Indicators (KPIs) for the period.

GET /api/v1/analytics/overview

Query Parameters

Parameter	Type	Default	Description
date_from	string	30 days ago	Start date (ISO 8601)
date_to	string	today	End date (ISO 8601)
department_id	uuid	-	Filter by department

Request Example

curl -X GET "https://voki.avanter.com.br/api/v1/analytics/overview?date_from=2026-02-01&date_to=2026-02-18" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": {
    "total_calls": 342,
    "completed_calls": 298,
    "missed_calls": 28,
    "cancelled_calls": 16,
    "avg_duration": 285,
    "avg_wait_time": 18,
    "avg_rating": 4.6,
    "total_customers": 215,
    "new_customers": 48,
    "completion_rate": 87.1,
    "satisfaction_rate": 92.0
  }
}

---

Hourly Distribution

Returns the distribution of calls by hour of the day.

GET /api/v1/analytics/hourly

Query Parameters

Parameter	Type	Default	Description
date_from	string	7 days ago	Start date
date_to	string	today	End date
department_id	uuid	-	Filter by department

Request Example

curl -X GET "https://voki.avanter.com.br/api/v1/analytics/hourly?date_from=2026-02-11&date_to=2026-02-18" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": [
    { "hour": 8, "total": 12, "completed": 10, "missed": 2 },
    { "hour": 9, "total": 25, "completed": 23, "missed": 2 },
    { "hour": 10, "total": 38, "completed": 35, "missed": 3 },
    { "hour": 11, "total": 42, "completed": 40, "missed": 2 },
    { "hour": 12, "total": 15, "completed": 13, "missed": 2 },
    { "hour": 13, "total": 20, "completed": 18, "missed": 2 },
    { "hour": 14, "total": 45, "completed": 42, "missed": 3 },
    { "hour": 15, "total": 40, "completed": 37, "missed": 3 },
    { "hour": 16, "total": 35, "completed": 33, "missed": 2 },
    { "hour": 17, "total": 22, "completed": 20, "missed": 2 }
  ]
}

---

Agent Performance

Returns performance metrics per agent.

GET /api/v1/analytics/agents

Query Parameters

Parameter	Type	Default	Description
date_from	string	30 days ago	Start date
date_to	string	today	End date
department_id	uuid	-	Filter by department
sort_by	string	total_calls	Sort: total_calls, avg_duration, avg_rating
sort_order	string	desc	Direction

Request Example

curl -X GET "https://voki.avanter.com.br/api/v1/analytics/agents?date_from=2026-02-01" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": [
    {
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_name": "João Silva",
      "total_calls": 85,
      "completed_calls": 78,
      "missed_calls": 5,
      "avg_duration": 312,
      "avg_wait_time": 15,
      "avg_rating": 4.8,
      "total_duration": 24336,
      "satisfaction_rate": 95.0
    },
    {
      "user_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "user_name": "Maria Santos",
      "total_calls": 72,
      "completed_calls": 68,
      "missed_calls": 3,
      "avg_duration": 278,
      "avg_wait_time": 12,
      "avg_rating": 4.7,
      "total_duration": 18904,
      "satisfaction_rate": 93.0
    }
  ]
}

---

Trends

Returns aggregated data over time for trend visualization.

GET /api/v1/analytics/trends

Query Parameters

Parameter	Type	Default	Description
date_from	string	30 days ago	Start date
date_to	string	today	End date
granularity	string	day	Granularity: day, week, month
department_id	uuid	-	Filter by department

Request Example

curl -X GET "https://voki.avanter.com.br/api/v1/analytics/trends?date_from=2026-02-01&granularity=day" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": [
    {
      "date": "2026-02-01",
      "total_calls": 18,
      "completed_calls": 16,
      "avg_duration": 290,
      "avg_rating": 4.5,
      "new_customers": 3
    },
    {
      "date": "2026-02-02",
      "total_calls": 22,
      "completed_calls": 20,
      "avg_duration": 310,
      "avg_rating": 4.7,
      "new_customers": 5
    }
  ]
}

---

Refresh Materialized Views

Forces a refresh of the analytics materialized views. Useful when recent data does not appear in queries.

POST /api/v1/analytics/refresh-views

Request Example

curl -X POST https://voki.avanter.com.br/api/v1/analytics/refresh-views \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": {
    "message": "Materialized views refreshed successfully",
    "refreshed_at": "2026-02-18T17:30:00Z"
  }
}