Analytics

Overview

The Analytics API provides access to organization dashboards, agent performance tracking, and direct Meta WhatsApp platform metrics.

---

Dashboard Stats

Retrieve general high-level dashboard metrics for the organization.

GET /api/analytics/dashboard

Query Parameters

Parameter	Type	Required	Description
from	string	No	Start date (YYYY-MM-DD). Defaults to start of current month.
to	string	No	End date (YYYY-MM-DD). Defaults to current date.

Response

{
  "status": "success",
  "data": {
    "stats": {
      "total_messages": 12450,
      "messages_change": 14.5,
      "total_contacts": 450,
      "contacts_change": 8.2,
      "chatbot_sessions": 890,
      "chatbot_change": -3.1,
      "campaigns_sent": 12,
      "campaigns_change": 20.0
    },
    "recent_messages": [
      {
        "id": "e9b728cd-7eb1-4d32-9cb7-7f8a7e02e1c0",
        "contact_name": "John Doe",
        "content": "Hello! I need help with my order.",
        "direction": "incoming",
        "created_at": "2024-01-01T12:00:00Z",
        "status": "read"
      }
    ]
  }
}

---

Agent Analytics

Track performance metrics, response times, and break records for support agents.

Note

Regular agents only see their own statistics (my_stats). Administrators and Managers see metrics for all agents.

List Agent Analytics

GET /api/analytics/agents

Query Parameters

Parameter	Type	Required	Description
from	string	No	Start date (YYYY-MM-DD). Defaults to start of current month.
to	string	No	End date (YYYY-MM-DD). Defaults to current date.
group_by	string	No	Trend grouping: day or week (default: day)
agent_id	string	No	Filter by specific agent UUID (requires administrative permission)

Response

{
  "status": "success",
  "data": {
    "summary": {
      "total_transfers_handled": 142,
      "active_transfers": 3,
      "avg_queue_time_mins": 1.5,
      "avg_first_response_mins": 2.4,
      "avg_resolution_mins": 15.8,
      "transfers_by_source": {
        "ivr": 98,
        "manual": 44
      },
      "total_break_time_mins": 120.5,
      "break_count": 4
    },
    "agent_stats": [
      {
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "agent_name": "Jane Smith",
        "avg_first_response_mins": 1.8,
        "avg_resolution_mins": 12.5,
        "transfers_handled": 45,
        "active_transfers": 1,
        "messages_sent": 320,
        "total_break_time_mins": 45.0,
        "break_count": 2,
        "is_available": true
      }
    ],
    "trend_data": [
      {
        "date": "2024-01-01",
        "transfers_handled": 24,
        "avg_response_mins": 2.1
      }
    ],
    "my_stats": {
      "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "agent_name": "Jane Smith",
      "avg_first_response_mins": 1.8,
      "avg_resolution_mins": 12.5,
      "transfers_handled": 45,
      "active_transfers": 1,
      "messages_sent": 320,
      "total_break_time_mins": 45.0,
      "break_count": 2,
      "is_available": true
    }
  }
}

Get Agent Details

Retrieve details and trend analytics for a specific agent.

GET /api/analytics/agents/{id}

Query Parameters

Parameter	Type	Required	Description
from	string	No	Start date (YYYY-MM-DD)
to	string	No	End date (YYYY-MM-DD)
group_by	string	No	Trend grouping: day or week

Response

{
  "status": "success",
  "data": {
    "agent": {
      "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "agent_name": "Jane Smith",
      "avg_first_response_mins": 1.8,
      "avg_resolution_mins": 12.5,
      "transfers_handled": 45,
      "active_transfers": 1,
      "messages_sent": 320,
      "total_break_time_mins": 45.0,
      "break_count": 2,
      "is_available": false,
      "current_break_start": "2024-01-01T14:30:00Z"
    },
    "trend_data": [
      {
        "date": "2024-01-01",
        "transfers_handled": 5,
        "avg_response_mins": 1.8
      }
    ]
  }
}

Compare Agents

Retrieve performance comparison metrics for all agents.

GET /api/analytics/agents/comparison

Query Parameters

Supports the from and to date filters.

Response

{
  "status": "success",
  "data": {
    "agents": [
      {
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "agent_name": "Jane Smith",
        "avg_first_response_mins": 1.8,
        "avg_resolution_mins": 12.5,
        "transfers_handled": 45,
        "active_transfers": 1,
        "messages_sent": 320,
        "total_break_time_mins": 45.0,
        "break_count": 2,
        "is_available": true
      }
    ]
  }
}

---

Meta WhatsApp Analytics

Directly queries Meta’s Graph API for phone-level performance metrics, templates click rates, cost, and pricing tier information. Results are cached to avoid API rate limits.

Get Meta Analytics

GET /api/analytics/meta

Query Parameters

Parameter	Type	Required	Description
analytics_type	string	Yes	Metrics type: analytics, pricing_analytics, template_analytics, call_analytics
start	string	Yes	Start date (YYYY-MM-DD)
end	string	Yes	End date (YYYY-MM-DD)
account_id	string	No	Filter by specific WhatsApp Account UUID (queries all WABAs if empty)
granularity	string	No	Granularity: HALF_HOUR, DAY, MONTH (default: DAY). Auto-adjusted per API rules.
template_ids	string	No	Filter by template IDs (JSON array of strings, e.g. ["123","456"])

Response (Messaging Analytics example)

{
  "status": "success",
  "data": {
    "accounts": [
      {
        "account_id": "893c5d88-b4b6-4b2a-bf3b-9a8bb698a3e7",
        "account_name": "Primary Line",
        "data": {
          "id": "1234567890123",
          "analytics": {
            "granularity": "DAY",
            "data_points": [
              {
                "start": 1704067200,
                "end": 1704153599,
                "sent": 150,
                "delivered": 148
              }
            ]
          }
        }
      }
    ],
    "cached": false
  }
}

Response (Template Analytics example)

{
  "status": "success",
  "data": {
    "accounts": [
      {
        "account_id": "893c5d88-b4b6-4b2a-bf3b-9a8bb698a3e7",
        "account_name": "Primary Line",
        "data": {
          "id": "1234567890123",
          "template_analytics": {
            "granularity": "DAILY",
            "data_points": [
              {
                "template_id": "87654321",
                "start": 1704067200,
                "end": 1704153599,
                "sent": 100,
                "delivered": 99,
                "read": 80,
                "replied": 15,
                "clicked": [
                  {
                    "type": "quick_reply_button",
                    "button_content": "Opt-in",
                    "count": 12
                  }
                ],
                "cost": [
                  {
                    "type": "amount_spent",
                    "value": 1.45
                  }
                ]
              }
            ]
          }
        },
        "template_names": {
          "87654321": "Welcome Message Campaign"
        }
      }
    ],
    "cached": false
  }
}

List Meta Accounts for Analytics

List active WhatsApp phone numbers/accounts configured for queries.

GET /api/analytics/meta/accounts

Response

{
  "status": "success",
  "data": {
    "accounts": [
      {
        "id": "893c5d88-b4b6-4b2a-bf3b-9a8bb698a3e7",
        "name": "Primary Line",
        "phone_id": "123456789"
      }
    ]
  }
}

Refresh Meta Cache

Clear the Redis cache for all cached Meta analytics configurations belonging to the organization.

POST /api/analytics/meta/refresh

Response

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

---

Planned Endpoints

The following endpoints are currently stubbed and will return a 501 Not Implemented response:

• GET /api/analytics/messages - Messaging analytics details.
• GET /api/analytics/chatbot - Chatbot performance metrics.