API Reference
Engagement
Overview
Fetch snapshot engagement KPIs for your tenant — daily, weekly, and monthly active users, stickiness, average messages per active user, and a breakdown by message type.
This endpoint returns a current snapshot (no days filter). Use it for KPI cards and composition charts on an analytics dashboard.
When to use this endpoint?
Use Engagement when:
- You need DAU / WAU / MAU cards or a stickiness ratio on the analytics home screen.
- You want average messages per active user as a depth-of-use KPI.
- You need a message-type composition chart (text, image, file, and so on).
- You prefer a lighter payload than Analytics Overview.
This endpoint requires tenant admin privileges with a valid client Access Token. End-user tokens are rejected. There is no days query parameter — values are snapshot metrics.
Response Data
The data object includes:
| Field | Description |
|---|---|
| dau | Daily active users — distinct users active in the last 24 hours. |
| wau | Weekly active users — distinct users active in the last 7 days. |
| mau | Monthly active users — distinct users active in the last 30 days. |
| stickiness | Typically dau / mau (0–1). Higher values mean more habitual daily use relative to the monthly base. |
| avgMessagesPerActiveUser | Average messages sent per active user in the engagement window. |
| messageTypes | Array of { type, count } entries for message composition (for example text, image, file). |
{baseUrl}/api/{apiVersion}/analytics/engagementAuthentication
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 current engagement snapshot for the tenant.
{
"success": true,
"message": "Engagement analytics fetched successfully",
"data": {
"dau": 27,
"wau": 86,
"mau": 120,
"stickiness": 0.23,
"avgMessagesPerActiveUser": 61.8,
"messageTypes": [
{
"type": "text",
"count": 6890
},
{
"type": "image",
"count": 412
},
{
"type": "file",
"count": 119
}
]
},
"error": null
}Common Errors
Engagement 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 engagement metrics. |
Best Practices
- Display stickiness as a percentage (
stickiness × 100) when showing it to non-technical users. - Pair engagement KPIs with Activity Series when you need trends over time — this endpoint is a snapshot only.
- Cache briefly and refresh on focus — avoid refetching on every render.
- Always send tenant headers with a client Bearer token over HTTPS.
Engagement ready
Bind DAU, WAU, MAU, and stickiness to your KPI cards, then use messageTypes for composition charts alongside Activity Series or Top Users.