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).

GET{baseUrl}/api/{apiVersion}/analytics/engagement

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 current engagement snapshot for the tenant.

json

1{2  "success": true,3  "message": "Engagement analytics fetched successfully",4  "data": {5    "dau": 27,6    "wau": 86,7    "mau": 120,8    "stickiness": 0.23,9    "avgMessagesPerActiveUser": 61.8,10    "messageTypes": [11      {12        "type": "text",13        "count": 689014      },15      {16        "type": "image",17        "count": 41218      },19      {20        "type": "file",21        "count": 11922      }23    ]24  },25  "error": null26}

Common Errors

Engagement 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 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.

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).

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 current engagement snapshot for the tenant.

json

1{2  "success": true,3  "message": "Engagement analytics fetched successfully",4  "data": {5    "dau": 27,6    "wau": 86,7    "mau": 120,8    "stickiness": 0.23,9    "avgMessagesPerActiveUser": 61.8,10    "messageTypes": [11      {12        "type": "text",13        "count": 689014      },15      {16        "type": "image",17        "count": 41218      },19      {20        "type": "file",21        "count": 11922      }23    ]24  },25  "error": null26}

Common Errors

Engagement 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 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.