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

Caution

Not implemented. This route is registered but currently returns 501 Not implemented yet. Use Dashboard Stats and the Meta Analytics endpoints for messaging metrics.

Chatbot Analytics

GET/api/analytics/chatbot

Caution

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

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

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.

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

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.