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).

{
  "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

Chatbot Analytics

GET /api/analytics/chatbot

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

{
  "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

{
  "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

{
  "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 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)

Response

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

{
  "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

{
  "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

{
  "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

Data Retention

Analytics data is retained for:

Detailed (hourly): 30 days
Daily: 1 year
Monthly: Indefinitely