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.

GET{baseUrl}/api/{apiVersion}/dashboard/overview

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.

Success Response (HTTP 200 OK)

On success, the API returns the combined dashboard snapshot for the tenant.

json

1{2  "success": true,3  "message": "Dashboard overview fetched successfully",4  "data": {5    "client": {6      "_id": "699fe1377846dcfb775c645c",7      "name": "client pro 1",8      "email": "cilentpro1@yoopmail.com",9      "slug": "client-pro-1"10    },11    "users": {12      "total": 128,13      "active": 120,14      "inactive": 8,15      "online": 1716    },17    "conversations": {18      "total": 342,19      "group": 54,20      "individual": 28821    },22    "messages": {23      "total": 18432,24      "last24Hours": 215,25      "last7Days": 1893,26      "last30Days": 742127    },28    "generatedAt": "2026-06-18T09:30:00.000Z"29  },30  "error": null31}

Common Errors

Overview fails when the token is missing, expired, or lacks tenant admin privileges.

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

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.

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.

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.

Success Response (HTTP 200 OK)

On success, the API returns the combined dashboard snapshot for the tenant.

json

1{2  "success": true,3  "message": "Dashboard overview fetched successfully",4  "data": {5    "client": {6      "_id": "699fe1377846dcfb775c645c",7      "name": "client pro 1",8      "email": "cilentpro1@yoopmail.com",9      "slug": "client-pro-1"10    },11    "users": {12      "total": 128,13      "active": 120,14      "inactive": 8,15      "online": 1716    },17    "conversations": {18      "total": 342,19      "group": 54,20      "individual": 28821    },22    "messages": {23      "total": 18432,24      "last24Hours": 215,25      "last7Days": 1893,26      "last30Days": 742127    },28    "generatedAt": "2026-06-18T09:30:00.000Z"29  },30  "error": null31}

Common Errors

Overview fails when the token is missing, expired, or lacks tenant admin privileges.

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

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.