API Reference
Dashboard Overview
Overview
Fetch a high-level summary of your tenant workspace in a single request — client details plus counts for users, conversations, and messages.
Use this endpoint to power the main dashboard home screen without calling each metrics endpoint separately. Response values are snapshots generated at generatedAt.
When to use this endpoint?
Use Dashboard Overview when:
- You need KPI cards for users, conversations, and messages on first load.
- You want a combined snapshot instead of three separate metrics calls.
- You are rendering an admin home screen for a tenant workspace.
- You need basic client identity (name, email, slug) alongside the metrics.
This endpoint requires tenant admin privileges with a valid client Access Token. End-user tokens are rejected.
Response Data
The data object includes these sections:
| Field | Description |
|---|---|
| client | Basic tenant client profile: _id, name, email, slug. |
| users | User counts: total, active, inactive, and currently online. |
| conversations | Conversation counts: total, group, and individual (direct). |
| messages | Message volume: total plus last 24 hours, 7 days, and 30 days. |
| generatedAt | ISO timestamp for when this snapshot was generated. |
{baseUrl}/api/{apiVersion}/dashboard/overviewAuthentication
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. |
Success Response (HTTP 200 OK)
On success, the API returns the combined dashboard snapshot for the tenant.
{
"success": true,
"message": "Dashboard overview fetched successfully",
"data": {
"client": {
"_id": "699fe1377846dcfb775c645c",
"name": "client pro 1",
"email": "cilentpro1@yoopmail.com",
"slug": "client-pro-1"
},
"users": {
"total": 128,
"active": 120,
"inactive": 8,
"online": 17
},
"conversations": {
"total": 342,
"group": 54,
"individual": 288
},
"messages": {
"total": 18432,
"last24Hours": 215,
"last7Days": 1893,
"last30Days": 7421
},
"generatedAt": "2026-06-18T09:30:00.000Z"
},
"error": null
}Common Errors
Overview fails when the token is missing, expired, or lacks tenant admin privileges.
HTTP 403 Forbidden — Tenant admin required
{
"success": false,
"message": "Access denied: tenant admin privileges required",
"data": null,
"error": null
}HTTP 401 Unauthorized — No token
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}| Code | Reason |
|---|---|
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 403 Forbidden | Access denied: tenant admin privileges required (for example, a non-client token was used). |
| 500 Internal Server Error | An unexpected error occurred while building the overview. |
Best Practices
- Prefer this overview for the dashboard home screen; use dedicated metrics endpoints when you only need one resource type.
- Cache the snapshot briefly on the client and refresh on focus or a timer — avoid polling on every render.
- Always send tenant headers with a client Bearer token over HTTPS.
- For a newer overview contract, see Dashboard → Overview v2.
Overview ready
Bind the returned counts to your KPI cards, then drill into Users Metrics, Conversations Metrics, or Messages Metrics for more detail.