139 lines
No EOL
4 KiB
Markdown
139 lines
No EOL
4 KiB
Markdown
# Analytics API
|
|
|
|
The Analytics API provides endpoints for tracking, analyzing, and reporting on bot usage and performance metrics.
|
|
|
|
## Status: Roadmap
|
|
|
|
This API is on the development roadmap. The endpoints documented below represent the planned interface design.
|
|
|
|
## Base URL
|
|
|
|
```
|
|
http://localhost:8080/api/v1/analytics
|
|
```
|
|
|
|
## Authentication
|
|
|
|
Uses the standard botserver authentication mechanism with appropriate role-based permissions.
|
|
|
|
## Endpoints
|
|
|
|
### Usage Statistics
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/analytics/usage` | Get overall usage statistics |
|
|
| GET | `/api/v1/analytics/usage/daily` | Get daily usage breakdown |
|
|
| GET | `/api/v1/analytics/usage/monthly` | Get monthly usage summary |
|
|
|
|
### Conversation Metrics
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/analytics/conversations` | Get conversation metrics |
|
|
| GET | `/api/v1/analytics/conversations/volume` | Get conversation volume over time |
|
|
| GET | `/api/v1/analytics/conversations/duration` | Get average conversation duration |
|
|
| GET | `/api/v1/analytics/conversations/resolution` | Get resolution rate metrics |
|
|
|
|
### User Engagement
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/analytics/engagement` | Get user engagement metrics |
|
|
| GET | `/api/v1/analytics/engagement/retention` | Get user retention data |
|
|
| GET | `/api/v1/analytics/engagement/satisfaction` | Get satisfaction scores |
|
|
|
|
### Reports
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/v1/analytics/reports` | Generate a custom report |
|
|
| GET | `/api/v1/analytics/reports/{report_id}` | Get report by ID |
|
|
| GET | `/api/v1/analytics/reports` | List all reports |
|
|
|
|
### Real-time Metrics
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/analytics/realtime` | Get real-time metrics |
|
|
| GET | `/api/v1/analytics/realtime/active` | Get active sessions count |
|
|
|
|
## Request Examples
|
|
|
|
### Get Usage Statistics
|
|
|
|
```bas
|
|
stats = GET "/api/v1/analytics/usage"
|
|
TALK "Total conversations: " + stats.total_conversations
|
|
TALK "Active users: " + stats.active_users
|
|
```
|
|
|
|
### Get Daily Usage
|
|
|
|
```bas
|
|
daily = GET "/api/v1/analytics/usage/daily?days=7"
|
|
FOR EACH day IN daily.data
|
|
TALK day.date + ": " + day.conversations + " conversations"
|
|
NEXT
|
|
```
|
|
|
|
### Generate Custom Report
|
|
|
|
```bas
|
|
report_config = NEW OBJECT
|
|
report_config.type = "engagement"
|
|
report_config.start_date = "2025-01-01"
|
|
report_config.end_date = "2025-01-31"
|
|
report_config.format = "pdf"
|
|
|
|
report = POST "/api/v1/analytics/reports", report_config
|
|
TALK "Report ID: " + report.id
|
|
```
|
|
|
|
### Get Real-time Metrics
|
|
|
|
```bas
|
|
realtime = GET "/api/v1/analytics/realtime"
|
|
TALK "Active sessions: " + realtime.active_sessions
|
|
TALK "Messages per minute: " + realtime.messages_per_minute
|
|
```
|
|
|
|
## Response Codes
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 200 | Success |
|
|
| 400 | Bad Request (invalid parameters) |
|
|
| 401 | Unauthorized |
|
|
| 403 | Forbidden (insufficient permissions) |
|
|
| 404 | Not Found |
|
|
| 500 | Internal Server Error |
|
|
|
|
## Query Parameters
|
|
|
|
### Time Range Filters
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `start_date` | String | Start date (ISO 8601 format) |
|
|
| `end_date` | String | End date (ISO 8601 format) |
|
|
| `days` | Integer | Number of days to include |
|
|
| `period` | String | Predefined period (today, week, month, year) |
|
|
|
|
### Grouping Options
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `group_by` | String | Group results by (hour, day, week, month) |
|
|
| `bot_id` | UUID | Filter by specific bot |
|
|
| `user_id` | UUID | Filter by specific user |
|
|
|
|
## Required Permissions
|
|
|
|
| Endpoint Category | Required Role |
|
|
|-------------------|---------------|
|
|
| Usage Statistics | `analytics_viewer` or `admin` |
|
|
| Conversation Metrics | `analytics_viewer` or `admin` |
|
|
| User Engagement | `analytics_viewer` or `admin` |
|
|
| Reports | `analytics_admin` or `admin` |
|
|
| Real-time Metrics | `analytics_viewer` or `admin` | |