API Reference
Conversations Metrics
Overview
Retrieve tenant-level conversation counts broken down by type — total conversations, group chats, and individual (direct) conversations.
Use this endpoint for conversation KPI cards or when refreshing only the conversations section of your dashboard.
When to use this endpoint?
Use Conversations Metrics when:
- You need group vs individual conversation totals for charts or cards.
- You want a lightweight count without loading the full conversation list.
- You are refreshing conversation KPIs independently from users or messages.
Requires a client Access Token with tenant admin privileges and tenant headers.
Response Data
| Field | Type | Description |
|---|---|---|
| total | number | Total conversations in the tenant. |
| group | number | Count of group conversations. |
| individual | number | Count of individual (direct / 1:1) conversations. |
GET
{baseUrl}/api/{apiVersion}/dashboard/metrics/conversationsAuthentication
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 conversation totals for the tenant.
json
{
"success": true,
"message": "Conversation metrics fetched successfully",
"data": {
"total": 342,
"group": 54,
"individual": 288
},
"error": null
}Common Errors
| Code | Reason |
|---|---|
| 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 conversation metrics. |
Best Practices
- Use this for conversation-only widgets; use Dashboard Overview for a combined snapshot.
- Link KPI cards to List Conversations so admins can inspect the underlying data.
- Always send tenant headers with a client Bearer token over HTTPS.
Conversation metrics ready
Map total, group, and individual to your conversations KPI row. Continue with List Conversations for details.