Get Messages

What it does

Returns an organization’s WhatsApp message analytics: summary cards at the top and a time series below. The source is ClickHouse with no caching, so every request returns the most up-to-date data. It can be scoped org-wide (all apps) or to selected app(s), and is bucketed by a date range and a granularity (hourly/daily/weekly/monthly).

Endpoint

GET /public/api/v1/wa/analytics/messages

There are no path or body parameters.

Headers

Authorization

string

required

Secret key in Bearer sk_... format. See Secret Key authentication.

Query parameters

All query parameters are optional.

appId

string

default:"all apps"

Repeatable. If none is given, all of the organization’s apps are included; if one or more are given, only those apps are included. An ID that does not belong to the organization → 404. For multiple apps, repeat the parameter: ?appId=app_AAA&appId=app_BBB.

startDate

string

default:"today 00:00:00 (UTC)"

ISO-8601 datetime. Start of the range.

endDate

string

default:"today 23:59:59 (UTC)"

ISO-8601 datetime. End of the range. Must be greater than startDate.

granularity

string

default:"daily"

Determines how the series is bucketed. See Granularity for the full list of values.

Response

The envelope is { "data": {...}, "isSuccess": true }, where data contains:

summary (object) — totals for the selected range (the stat cards).
series (array) — time points bucketed by granularity.

isSuccess

boolean

true when the request completed successfully.

data

object

Show data

summary

object

Totals across the selected range.

Show summary

totalMessages

integer

sentMessages + receivedMessages.

sentMessages

integer

Outbound messages.

receivedMessages

integer

Inbound messages.

templateMessages

integer

Outbound messages that used a template.

series

object[]

Time points bucketed by granularity.

Show series item

timestamp

string

Bucket start time in ISO format (resolution reflects granularity).

totalMessages

integer

sentMessages + receivedMessages in this bucket.

sentMessages

integer

Outbound messages in this bucket.

receivedMessages

integer

Inbound messages in this bucket.

templateMessages

integer

Template messages in this bucket.

Invariants: Σ series[].sentMessages == summary.sentMessages (the same holds for templateMessages and receivedMessages), and templateMessages ≤ sentMessages.

Examples

Demo 1 — all apps (defaults: today, daily)

GET /public/api/v1/wa/analytics/messages
Authorization: Bearer sk_...

{
  "data": {
    "summary": { "totalMessages": 1280, "sentMessages": 940, "receivedMessages": 340, "templateMessages": 612 },
    "series": [
      { "timestamp": "2026-06-08T00:00:00", "totalMessages": 1280, "sentMessages": 940, "receivedMessages": 340, "templateMessages": 612 }
    ]
  },
  "isSuccess": true
}

Demo 2 — single app + date range + daily

GET /public/api/v1/wa/analytics/messages?appId=app_7poyXj8GXuv76e&startDate=2026-06-01T00:00:00&endDate=2026-06-04T00:00:00&granularity=daily
Authorization: Bearer sk_...

{
  "data": {
    "summary": { "totalMessages": 845, "sentMessages": 600, "receivedMessages": 245, "templateMessages": 410 },
    "series": [
      { "timestamp": "2026-06-01T00:00:00", "totalMessages": 300, "sentMessages": 210, "receivedMessages": 90, "templateMessages": 150 },
      { "timestamp": "2026-06-02T00:00:00", "totalMessages": 280, "sentMessages": 200, "receivedMessages": 80, "templateMessages": 140 },
      { "timestamp": "2026-06-03T00:00:00", "totalMessages": 265, "sentMessages": 190, "receivedMessages": 75, "templateMessages": 120 }
    ]
  },
  "isSuccess": true
}

Demo 3 — multiple apps (repeatable appId)

GET /public/api/v1/wa/analytics/messages?appId=app_AAA&appId=app_BBB&startDate=2026-06-01T00:00:00&endDate=2026-06-08T00:00:00&granularity=weekly
Authorization: Bearer sk_...

{
  "data": {
    "summary": { "totalMessages": 5120, "sentMessages": 3800, "receivedMessages": 1320, "templateMessages": 2450 },
    "series": [
      { "timestamp": "2026-06-01T00:00:00", "totalMessages": 5120, "sentMessages": 3800, "receivedMessages": 1320, "templateMessages": 2450 }
    ]
  },
  "isSuccess": true
}

Demo 4 — hourly (single day, single app)

GET /public/api/v1/wa/analytics/messages?appId=app_7poyXj8GXuv76e&startDate=2026-06-08T00:00:00&endDate=2026-06-08T23:59:59&granularity=hourly
Authorization: Bearer sk_...

{
  "data": {
    "summary": { "totalMessages": 120, "sentMessages": 90, "receivedMessages": 30, "templateMessages": 55 },
    "series": [
      { "timestamp": "2026-06-08T09:00:00", "totalMessages": 40, "sentMessages": 30, "receivedMessages": 10, "templateMessages": 18 },
      { "timestamp": "2026-06-08T10:00:00", "totalMessages": 80, "sentMessages": 60, "receivedMessages": 20, "templateMessages": 37 }
    ]
  },
  "isSuccess": true
}

Demo 5 — no data (empty range)

GET /public/api/v1/wa/analytics/messages?appId=app_7poyXj8GXuv76e&startDate=2026-01-01T00:00:00&endDate=2026-01-02T00:00:00
Authorization: Bearer sk_...

{
  "data": {
    "summary": { "totalMessages": 0, "sentMessages": 0, "receivedMessages": 0, "templateMessages": 0 },
    "series": []
  },
  "isSuccess": true
}

Errors

errors

object

Error details with code, group, and description; isSuccess is false.

HTTP	Code	Group	When
401	`ORGANIZATION_SECRET_010`	`NOT_FOUND`	Authorization header / secret key is missing.
401	`ORGANIZATION_SECRET_011`	`NOT_FOUND`	Secret key is invalid.
404	`APPLICATION_004`	`NOT_FOUND`	The given `appId`(s) do not belong to the organization.
422	`VAL_019`	`VALIDATION`	`endDate <= startDate` (invalid date range).
422	`VAL_*`(FastAPI validation)	`VALIDATION`	Invalid `granularity` enum, unparseable `startDate`/`endDate`, etc.
500 / 502	`SYS_001`	`SYSTEM`	ClickHouse unreachable / query error (unexpected infrastructure error).

Example error responses:

{ "errors": { "code": "ORGANIZATION_SECRET_011", "group": "NOT_FOUND", "description": "Invalid secret key." }, "isSuccess": false }

{ "errors": { "code": "APPLICATION_004", "group": "NOT_FOUND", "description": "Application(s) not found for this organization: app_FOREIGN" }, "isSuccess": false }

{ "errors": { "code": "VAL_019", "group": "VALIDATION", "description": "Invalid date range." }, "isSuccess": false }

Getting Started

Analytics

Application

Template

What it does

Endpoint

Headers

Query parameters

Response

Examples

Errors

​What it does

​Endpoint

​Headers

​Query parameters

​Response

​Examples

​Errors

What it does

Endpoint

Headers

Query parameters

Response

Examples

Errors