> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gateway.connexease.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Messages

> Retrieve aggregated message metrics and a time-series breakdown for your organization or specific apps.

## 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

```text theme={null}
GET /public/api/v1/wa/analytics/messages
```

There are no path or body parameters.

### Headers

<ParamField header="Authorization" type="string" required>
  Secret key in `Bearer sk_...` format. See [Secret Key authentication](/essentials/authentication#secret-key).
</ParamField>

### Query parameters

All query parameters are optional.

<ParamField query="appId" default="all apps" type="string">
  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`.
</ParamField>

<ParamField query="startDate" default="today 00:00:00 (UTC)" type="string">
  ISO-8601 datetime. Start of the range.
</ParamField>

<ParamField query="endDate" default="today 23:59:59 (UTC)" type="string">
  ISO-8601 datetime. End of the range. Must be greater than `startDate`.
</ParamField>

<ParamField query="granularity" default="daily" type="string">
  Determines how the `series` is bucketed. See [Granularity](/public-api-reference/analytics/reference/enums#granularity) for the full list of values.
</ParamField>

***

## 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`.

<ResponseField name="isSuccess" type="boolean">
  `true` when the request completed successfully.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="summary" type="object">
      Totals across the selected range.

      <Expandable title="summary">
        <ResponseField name="totalMessages" type="integer">
          `sentMessages` + `receivedMessages`.
        </ResponseField>

        <ResponseField name="sentMessages" type="integer">
          Outbound messages.
        </ResponseField>

        <ResponseField name="receivedMessages" type="integer">
          Inbound messages.
        </ResponseField>

        <ResponseField name="templateMessages" type="integer">
          Outbound messages that used a template.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="series" type="object[]">
      Time points bucketed by `granularity`.

      <Expandable title="series item">
        <ResponseField name="timestamp" type="string">
          Bucket start time in ISO format (resolution reflects `granularity`).
        </ResponseField>

        <ResponseField name="totalMessages" type="integer">
          `sentMessages` + `receivedMessages` in this bucket.
        </ResponseField>

        <ResponseField name="sentMessages" type="integer">
          Outbound messages in this bucket.
        </ResponseField>

        <ResponseField name="receivedMessages" type="integer">
          Inbound messages in this bucket.
        </ResponseField>

        <ResponseField name="templateMessages" type="integer">
          Template messages in this bucket.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  **Invariants:** `Σ series[].sentMessages == summary.sentMessages` (the same holds for `templateMessages` and `receivedMessages`), and `templateMessages ≤ sentMessages`.
</Note>

***

## Examples

<AccordionGroup>
  <Accordion title="Demo 1 — all apps (defaults: today, daily)">
    ```text theme={null}
    GET /public/api/v1/wa/analytics/messages
    Authorization: Bearer sk_...
    ```

    ```json theme={null}
    {
      "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
    }
    ```
  </Accordion>

  <Accordion title="Demo 2 — single app + date range + daily">
    ```text theme={null}
    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_...
    ```

    ```json theme={null}
    {
      "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
    }
    ```
  </Accordion>

  <Accordion title="Demo 3 — multiple apps (repeatable appId)">
    ```text theme={null}
    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_...
    ```

    ```json theme={null}
    {
      "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
    }
    ```
  </Accordion>

  <Accordion title="Demo 4 — hourly (single day, single app)">
    ```text theme={null}
    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_...
    ```

    ```json theme={null}
    {
      "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
    }
    ```
  </Accordion>

  <Accordion title="Demo 5 — no data (empty range)">
    ```text theme={null}
    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_...
    ```

    ```json theme={null}
    {
      "data": {
        "summary": { "totalMessages": 0, "sentMessages": 0, "receivedMessages": 0, "templateMessages": 0 },
        "series": []
      },
      "isSuccess": true
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Errors

<ResponseField name="errors" type="object">
  Error details with `code`, `group`, and `description`; `isSuccess` is `false`.
</ResponseField>

| 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:

```json theme={null}
{ "errors": { "code": "ORGANIZATION_SECRET_011", "group": "NOT_FOUND", "description": "Invalid secret key." }, "isSuccess": false }
```

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

```json theme={null}
{ "errors": { "code": "VAL_019", "group": "VALIDATION", "description": "Invalid date range." }, "isSuccess": false }
```