List Message Logs

GET https://pilotstatus.com.br/v1/messages

Lists the message logs — sent and received — of the WhatsApp number tied to your API key, newest first, with pagination and filters. For the full detail of a single message, use GET /v1/messages/{messageId}.

The dashboard Logs & Analytics page is the visual counterpart of this endpoint — the same rows, filters, and statuses you see there are what this endpoint returns as JSON.

Headers

x-api-key: ps_... (or x-api-key-id: <api_key_id>) — a number-scoped key. Tenant-scoped keys receive 403.

Query parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based).
`pageSize`	integer	`20`	Rows per page (max `100`).
`status`	string (CSV)	—	Filter by delivery status: `QUEUED`, `SENT`, `DELIVERED`, `READ`, `PLAYED`, `FAILED`, `CANCELED`. Accepts a comma-separated list (e.g. `status=FAILED,CANCELED`). Delivery statuses only exist for outbound messages, so this filter implies outbound-only results.
`direction`	string	—	`in` (received) or `out` (sent). `out` leaves out the outbound rows that had no send request — see the Warning in Outbound rows with no send request.
`startDate`	string	—	ISO 8601 lower bound on `createdAt` (e.g. `2026-02-01T00:00:00.000Z`).
`endDate`	string	—	ISO 8601 upper bound on `createdAt`. Must not be before `startDate`.
`search`	string	—	A phone number in any format (`+5511999999999`, `5511999999999`, `11 99999-9999`, …) or a template name.
`templateId`	string	—	Template id or name — returns only messages sent with that template.
`window`	string	—	`open` or `closed` — the 24h service-window state recorded at send time (see the Note below).

24h service window: WhatsApp opens a 24-hour customer-service window every time a contact messages you. serviceWindowOpenAtSend records the state of that window at the moment each outbound message was accepted: true means it was a reply inside an open window and was sent immediately; false means it was a “cold” send outside the window — paced by the anti-block engine on Pilot Status web numbers, and requiring an approved template on Meta Cloud API numbers; null means the window was not computed (inbound rows, group/channel destinations). Filter with window=open / window=closed.

Examples

curl "https://pilotstatus.com.br/v1/messages?page=1&pageSize=20" \
  -H "x-api-key: ps_your_key_here"

curl "https://pilotstatus.com.br/v1/messages?page=1&pageSize=20" \
  -H "x-api-key-id: ck_xxx"

curl "https://pilotstatus.com.br/v1/messages?status=FAILED&direction=out&startDate=2026-02-01T00:00:00.000Z&endDate=2026-02-28T23:59:59.999Z" \
  -H "x-api-key: ps_your_key_here"

Response (200)

{
  "data": [
    {
      "id": "msg_abc",
      "correlationId": "corr_123",
      "direction": "OUT",
      "from": "+5511888888888",
      "to": "+5511999999999",
      "content": "Hi John, your order 123 is on its way!",
      "template": "order_shipped",
      "status": "READ",
      "errorCode": null,
      "errorMessage": null,
      "origin": "API",
      "serviceWindowOpenAtSend": true,
      "createdAt": "2026-02-24T15:00:00.000Z",
      "sentAt": "2026-02-24T15:00:05.000Z",
      "deliveredAt": "2026-02-24T15:00:07.000Z",
      "readAt": "2026-02-24T15:02:11.000Z",
      "externalMessageId": "wamid.HBgLNTUxMTk5OTk5OTk5"
    },
    {
      "id": "msg_def",
      "correlationId": null,
      "direction": "IN",
      "from": "+5511999999999",
      "to": "+5511888888888",
      "content": "Thanks! See you tomorrow.",
      "template": null,
      "status": null,
      "errorCode": null,
      "errorMessage": null,
      "origin": null,
      "serviceWindowOpenAtSend": null,
      "createdAt": "2026-02-24T15:03:40.000Z",
      "sentAt": null,
      "deliveredAt": null,
      "readAt": null,
      "externalMessageId": "wamid.HBgLNTUxMTg4ODg4ODg4"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 2,
  "totalPages": 1
}

Response fields

Field	Description
`id`	Internal message id — use it with `GET /v1/messages/{messageId}` for single-message detail.
`correlationId`	Correlation identifier from the send request. `null` on received rows, and on outbound rows that had no send request (see Outbound rows with no send request).
`direction`	`IN` (received) or `OUT` (sent).
`from` / `to`	Sender and recipient phone numbers.
`content`	Message text. `null` when redacted by the number’s PII retention mode.
`template`	Template name for template sends, otherwise `null`.
`status`	Delivery status of outbound messages (`QUEUED`, `SENT`, `DELIVERED`, `READ`, `PLAYED`, `FAILED`, `CANCELED`) — see Message Status. `null` on inbound rows.
`errorCode` / `errorMessage`	Populated on `FAILED` sends — see Log Error Codes. `GET /v1/messages/{messageId}` returns the same `errorCode` for the same message.
`origin`	Where the send originated. Full value set below.
`serviceWindowOpenAtSend`	`true`, `false`, or `null` — the 24h service-window state recorded at send time (see the Note above).
`createdAt` / `sentAt` / `deliveredAt` / `readAt`	Lifecycle timestamps (ISO 8601).
`externalMessageId`	Provider WhatsApp message ID (wamid).

Retention: rows respect the number’s PII retention mode. On RELAY_ONLY numbers the rows are returned redacted (content: null).

`origin` — which rail the message left by

Value	Rail
`API`	`POST /v1/messages/send` — the public API
`MCP`	The Pilot Status MCP server tool
`CHATWOOT`	An agent reply from a Chatwoot inbox. From an API mirror inbox, Pilot Status sends it and the row is a regular send. From a native WhatsApp Cloud inbox, Chatwoot sends it itself through the Meta layer — see below
`CHAT`	The chat on the Pilot Status dashboard
`DASHBOARD`	A template preview sent from the dashboard
`SYSTEM`	Platform-issued (onboarding welcome and other internal sends)
`APP`	Outbound, but not through us — the business sent it from the WhatsApp Business app on the phone, or from another tool on the same WABA. On a Meta number these rows come from the `message_echoes` / `smb_message_echoes` webhooks
`LAYER`	Sent through the Pilot Status Meta layer by a client other than a native Chatwoot inbox — for example your own code calling the Graph API with your `ps_` key
`null`	An inbound message — or an outbound one whose send source is not one of the above

origin: null does not mean “inbound”. Read direction for that. A null on an OUT row means the send carried a source we do not map to a public tag; treat it as “unclassified outbound”, not as received traffic, or a billing report will silently under-count your own sends.

The set grows. Treat a value you do not recognise as “unclassified outbound”, not as an error.

Outbound rows with no send request

Three kinds of OUT row were not sent by Pilot Status, so there is no send request behind them: APP, LAYER, and CHATWOOT from a native WhatsApp Cloud inbox. On these rows:

correlationId, template, serviceWindowOpenAtSend, errorCode and errorMessage are null;
GET /v1/messages/{messageId} answers 404 — the list row is all there is;
status follows the statuses Meta reports: SENT, DELIVERED, READ or FAILED;
the message does not count toward your plan’s message usage;
on a number whose PII retention mode redacts the row, to and content are null and redacted: true is added, as on any other row.

A CHATWOOT row from an API mirror inbox is a regular send: it has a correlationId and full detail. On LAYER rows and native-inbox CHATWOOT rows, content is what the Graph API request carried: the text body, a media caption, or the body text of an interactive message. Three types get a short generated text instead:

a template reads Template: <name> — the rendered body is not stored, and template stays null;
a location reads Location: <latitude>, <longitude>, followed by its name and address when the request had them;
contacts read Contacts: <names>.

Audio and stickers have content: null. A native-inbox CHATWOOT row:

{
  "id": "cm_01J9...",
  "correlationId": null,
  "direction": "OUT",
  "from": "+5511911111111",
  "to": "5511988887777",
  "content": "agent reply",
  "template": null,
  "status": "SENT",
  "errorCode": null,
  "errorMessage": null,
  "origin": "CHATWOOT",
  "serviceWindowOpenAtSend": null,
  "createdAt": "2026-10-06T18:00:00.000Z",
  "sentAt": "2026-10-06T18:00:00.000Z",
  "deliveredAt": null,
  "readAt": null,
  "externalMessageId": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjA="
}

The status, direction=out, templateId and window filters leave these rows out. They return only messages that had a send request, so APP, LAYER and native-inbox CHATWOOT rows never match them, even though they are OUT. To get these rows, list without those filters (startDate, endDate and a phone-number search keep them) and read direction and origin.

LAYER rows, and CHATWOOT rows from a native inbox, are recorded only from the moment Pilot Status started recording layer sends for the number. Earlier sends are not backfilled. What is and is not recorded: Meta layer → Sends are recorded in Logs.

Common errors

Status	Meaning
`400`	`INVALID_DATE_RANGE` — malformed `startDate`/`endDate`, or `endDate` before `startDate`
`401`	Missing/invalid API key header (`x-api-key` / `x-api-key-id`)
`403`	A tenant-scoped key used on a number-scoped endpoint

Overview

Messaging

Templates

Numbers

Phone Lines

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

GET /v1/messages — List Message Logs

List Message Logs

Headers

Query parameters

Examples

Response (200)

Response fields

`origin` — which rail the message left by

Outbound rows with no send request

Common errors

​List Message Logs

​Headers

​Query parameters

​Examples

​Response (200)

​Response fields

​origin — which rail the message left by

​Outbound rows with no send request

​Common errors

List Message Logs

Headers

Query parameters

Examples

Response (200)

Response fields

`origin` — which rail the message left by

Outbound rows with no send request

Common errors