# Analytics

> Access dashboard and messaging analytics

Source: https://docs.soosh.io/reference/api/analytics/

## Overview

The Analytics API provides access to messaging statistics, chatbot performance, and dashboard metrics.

## Dashboard Stats

Get an overview of key metrics for the dashboard.

`GET /api/analytics/dashboard`

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `from` | string | Start date, `YYYY-MM-DD`. Must be sent together with `to`. |
| `to` | string | End date, `YYYY-MM-DD` (inclusive of the whole day). |

If `from`/`to` are omitted, the range defaults to the **current calendar month to now**. A
malformed date returns `400 Invalid start date format. Use YYYY-MM-DD`.

### Response

Each `*_change` value is the percentage change against the immediately preceding window of the
same length (`100.0` when the previous window was zero and the current one is not).

```json
{
  "status": "success",
  "data": {
    "stats": {
      "total_messages": 50000,
      "messages_change": 12.5,
      "total_contacts": 5000,
      "contacts_change": 4.2,
      "chatbot_sessions": 320,
      "chatbot_change": -3.1,
      "campaigns_sent": 20,
      "campaigns_change": 0.0
    },
    "recent_messages": [
      {
        "id": "uuid",
        "contact_name": "John Doe",
        "content": "Hello!",
        "direction": "incoming",
        "status": "received",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ]
  }
}
```

## Message Analytics

`GET /api/analytics/messages`

> **Careful:** **Not implemented.** This route is registered but currently returns
> `501 Not implemented yet`. Use [Dashboard Stats](#dashboard-stats) and the
> [Meta Analytics](#meta-analytics) endpoints for messaging metrics.

## Chatbot Analytics

`GET /api/analytics/chatbot`

> **Careful:** **Not implemented.** This route is registered but currently returns
> `501 Not implemented yet`. Chatbot counters are available from
> `GET /api/chatbot/settings`, which returns a `stats` object alongside the settings.

## Agent Analytics

Performance metrics for human agents handling transfers. Users **without** the
`analytics.agents:read` / `analytics:read` permission see only their own stats
(`my_stats`); users with the permission see every agent.

`GET /api/analytics/agents`

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `from` | string | Start date (`YYYY-MM-DD`). Defaults to the start of the current month |
| `to` | string | End date (`YYYY-MM-DD`). Defaults to now |
| `group_by` | string | Trend granularity: `day` (default) or `week` |
| `agent_id` | string | Restrict to a single agent (requires analytics permission) |

### Response

```json
{
  "status": "success",
  "data": {
    "summary": {
      "total_transfers_handled": 120,
      "active_transfers": 5,
      "avg_queue_time_mins": 3.2,
      "avg_first_response_mins": 1.8,
      "avg_resolution_mins": 12.5,
      "transfers_by_source": { "chatbot": 80, "manual": 40 },
      "total_break_time_mins": 45.0,
      "break_count": 3
    },
    "agent_stats": [
      {
        "agent_id": "uuid",
        "agent_name": "Jane Agent",
        "avg_first_response_mins": 1.5,
        "avg_resolution_mins": 10.2,
        "transfers_handled": 40,
        "active_transfers": 2,
        "messages_sent": 320,
        "total_break_time_mins": 15.0,
        "break_count": 1,
        "is_available": true,
        "current_break_start": null
      }
    ],
    "trend_data": [
      { "date": "2024-01-01", "transfers_handled": 12, "avg_response_mins": 0 }
    ],
    "my_stats": {
      "agent_id": "uuid",
      "agent_name": "Jane Agent",
      "transfers_handled": 40
    }
  }
}
```

## Agent Details

Detailed analytics for a single agent (requires analytics permission).

`GET /api/analytics/agents/{id}`

Accepts the same `from`, `to`, and `group_by` query parameters as Agent Analytics.

### Response

```json
{
  "status": "success",
  "data": {
    "agent": {
      "agent_id": "uuid",
      "agent_name": "Jane Agent",
      "transfers_handled": 40,
      "avg_resolution_mins": 10.2,
      "messages_sent": 320,
      "is_available": true
    },
    "trend_data": [
      { "date": "2024-01-01", "transfers_handled": 12, "avg_response_mins": 0 }
    ]
  }
}
```

## Agent Comparison

Side-by-side stats for all agents in the organization (requires analytics
permission). Accepts `from` and `to` query parameters.

`GET /api/analytics/agents/comparison`

### Response

```json
{
  "status": "success",
  "data": {
    "agents": [
      {
        "agent_id": "uuid",
        "agent_name": "Jane Agent",
        "transfers_handled": 40,
        "avg_resolution_mins": 10.2,
        "messages_sent": 320
      }
    ]
  }
}
```

## Meta Analytics

Fetch native WhatsApp Business analytics straight from Meta's Graph API, cached
in Redis. See the [Meta Insights feature guide](https://docs.soosh.io/features/meta-insights) for the
dashboards these power.

`GET /api/analytics/meta`

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `analytics_type` | string | Yes | One of `analytics` (messaging), `pricing_analytics`, `template_analytics`, `call_analytics` |
| `start` | string | Yes | Start date (`YYYY-MM-DD`) |
| `end` | string | Yes | End date (`YYYY-MM-DD`) |
| `granularity` | string | No | `HALF_HOUR`, `DAY` (default), or `MONTH`. Auto-adjusted to fit the range |
| `account_id` | string | No | Limit to one WhatsApp account; omit for all accounts in the org |
| `template_ids` | string | No | JSON array of Meta template IDs (template analytics only; auto-detected if omitted) |

> **Note:** Granularity is auto-adjusted to avoid Meta API errors: `MONTH` falls back to
> `DAY` for ranges under 30 days, and `HALF_HOUR` falls back to `DAY` for ranges
> over 7 days. Template analytics have a 90-day lookback limit.

### Response

Results are grouped per account. `cached` indicates whether the response came
from the Redis cache.

```json
{
  "status": "success",
  "data": {
    "accounts": [
      {
        "account_id": "uuid",
        "account_name": "main",
        "data": { },
        "template_names": { "meta-template-id": "order_confirmation" }
      }
    ],
    "cached": false
  }
}
```

## Meta Analytics Accounts

List the WhatsApp accounts available for Meta analytics.

`GET /api/analytics/meta/accounts`

### Response

```json
{
  "status": "success",
  "data": {
    "accounts": [
      { "id": "uuid", "name": "main", "phone_id": "123456789" }
    ]
  }
}
```

## Refresh Meta Analytics Cache

Clear the cached Meta analytics for the organization so the next request fetches
fresh data from Meta. Requires the `analytics:write` permission.

`POST /api/analytics/meta/refresh`

### Response

```json
{
  "status": "success",
  "data": { "message": "Analytics cache cleared successfully" }
}
```

## Metrics Explained

### Message Metrics

| Metric | Description |
|--------|-------------|
| `delivery_rate` | Percentage of sent messages that were delivered |
| `read_rate` | Percentage of delivered messages that were read |

### Chatbot Metrics

| Metric | Description |
|--------|-------------|
| `resolution_rate` | Percentage of conversations resolved without agent |
| `avg_resolution_time` | Average time to resolve a conversation |
| `completion_rate` | Percentage of started flows that were completed |

> **Tip:** Use analytics to identify popular topics and optimize your chatbot flows for better automation.

## Data Retention

Analytics data is retained for:
- Detailed (hourly): 30 days
- Daily: 1 year
- Monthly: Indefinitely

> **Note:** Historical data older than retention periods is aggregated and individual message-level details are not available.