Messages Metrics

Overview

Retrieve tenant-level message volume metrics, including totals for recent time windows and a daily activity series for charts.

Use the optional days query parameter to control how far back the activity series looks (for example 7, 30, or 90 days).

When to use this endpoint?

Use Messages Metrics when:

You need message volume KPIs (total, last 24 hours, 7 days, 30 days).
You are rendering a daily activity line or bar chart for messages.
You want to refresh messaging metrics independently from users or conversations.
Product or ops dashboards need recent engagement trends.

Requires a client Access Token with tenant admin privileges and tenant headers.

Response Data

Field	Type	Description
total	number	All-time message count for the tenant.
last24Hours	number	Messages created in the last 24 hours.
last7Days	number	Messages created in the last 7 days.
last30Days	number	Messages created in the last 30 days.
activity	array	Daily series for charts. Each item has `date` (YYYY-MM-DD) and `count`. Length follows the `days` query parameter.

GET{baseUrl}/api/{apiVersion}/dashboard/metrics/messages?days=7

Authentication: Required (Bearer token)
Tenant-scoped: Yes (tenant DB - requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Client Access Token with tenant admin privileges.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

Query Parameters

Parameter	Example	Required	Description
days	7	Optional	Look-back window in days for the `activity` series (for example 7, 30, or 90). Common default is 7 when omitted by your client.

Success Response (HTTP 200 OK)

On success, the API returns volume KPIs plus a daily activity series suitable for charts.

json

1{2  "success": true,3  "message": "Message metrics fetched successfully",4  "data": {5    "total": 18432,6    "last24Hours": 215,7    "last7Days": 1893,8    "last30Days": 7421,9    "activity": [10      {11        "date": "2026-06-12",12        "count": 24013      },14      {15        "date": "2026-06-13",16        "count": 31017      },18      {19        "date": "2026-06-14",20        "count": 021      },22      {23        "date": "2026-06-15",24        "count": 18825      },26      {27        "date": "2026-06-16",28        "count": 40229      },30      {31        "date": "2026-06-17",32        "count": 33833      },34      {35        "date": "2026-06-18",36        "count": 21537      }38    ]39  },40  "error": null41}

Common Errors

Code	Reason
400 Bad Request	Invalid `days` value or malformed query.
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Access denied: tenant admin privileges required.
500 Internal Server Error	An unexpected error occurred while computing message metrics.

Best Practices

Pass days explicitly (7 / 30 / 90) so chart ranges stay consistent across screens.
Use activity for charts and the summary counters for KPI cards.
Avoid very large look-back windows on every page load; cache and refresh on an interval or user action.
Always send tenant headers with a client Bearer token over HTTPS.

Message metrics ready

Plot activity on a daily chart and show last24Hours / last7Days as summary cards. For deeper inspection, continue with List Messages.

When to use this endpoint?

Use Messages Metrics when:

You need message volume KPIs (total, last 24 hours, 7 days, 30 days).
You are rendering a daily activity line or bar chart for messages.
You want to refresh messaging metrics independently from users or conversations.
Product or ops dashboards need recent engagement trends.

Requires a client Access Token with tenant admin privileges and tenant headers.

Response Data

Field	Type	Description
total	number	All-time message count for the tenant.
last24Hours	number	Messages created in the last 24 hours.
last7Days	number	Messages created in the last 7 days.
last30Days	number	Messages created in the last 30 days.
activity	array	Daily series for charts. Each item has `date` (YYYY-MM-DD) and `count`. Length follows the `days` query parameter.

Header

Value

Description

Authorization

Bearer <access_token>

Client Access Token with tenant admin privileges.

is-tenant

true

Targets the tenant DB ("true", needs x-client-id).

x-client-id

Tenant (client) id. Required when is-tenant=true.

Parameter

Example

Required

Description

days

Optional

Look-back window in days for the activity series (for example 7, 30, or 90). Common default is 7 when omitted by your client.

Success Response (HTTP 200 OK)

On success, the API returns volume KPIs plus a daily activity series suitable for charts.

json

1{2  "success": true,3  "message": "Message metrics fetched successfully",4  "data": {5    "total": 18432,6    "last24Hours": 215,7    "last7Days": 1893,8    "last30Days": 7421,9    "activity": [10      {11        "date": "2026-06-12",12        "count": 24013      },14      {15        "date": "2026-06-13",16        "count": 31017      },18      {19        "date": "2026-06-14",20        "count": 021      },22      {23        "date": "2026-06-15",24        "count": 18825      },26      {27        "date": "2026-06-16",28        "count": 40229      },30      {31        "date": "2026-06-17",32        "count": 33833      },34      {35        "date": "2026-06-18",36        "count": 21537      }38    ]39  },40  "error": null41}

Code

Reason

400 Bad Request

Invalid days value or malformed query.

401 Unauthorized

Access Token is missing, invalid, or expired.

403 Forbidden

Access denied: tenant admin privileges required.

500 Internal Server Error

An unexpected error occurred while computing message metrics.

Best Practices

Pass days explicitly (7 / 30 / 90) so chart ranges stay consistent across screens.
Use activity for charts and the summary counters for KPI cards.
Avoid very large look-back windows on every page load; cache and refresh on an interval or user action.
Always send tenant headers with a client Bearer token over HTTPS.