API Reference
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=7Authentication
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
{
"success": true,
"message": "Message metrics fetched successfully",
"data": {
"total": 18432,
"last24Hours": 215,
"last7Days": 1893,
"last30Days": 7421,
"activity": [
{
"date": "2026-06-12",
"count": 240
},
{
"date": "2026-06-13",
"count": 310
},
{
"date": "2026-06-14",
"count": 0
},
{
"date": "2026-06-15",
"count": 188
},
{
"date": "2026-06-16",
"count": 402
},
{
"date": "2026-06-17",
"count": 338
},
{
"date": "2026-06-18",
"count": 215
}
]
},
"error": null
}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
daysexplicitly (7 / 30 / 90) so chart ranges stay consistent across screens. - Use
activityfor 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.