Skip to main content
Retrieve the full stored message history (direct and group conversations) for the connected number.

​
Endpoint

GET https://pilotstatus.com.br/v1/messages/history
Requires a number-scoped API key (ps_*) in the x-api-key header. Tenant-scoped keys return 403. You may also identify the key with x-api-key-id: <api_key_id>.All providers supported: this endpoint works for both unofficial (Pilot Status web) numbers and official Meta Cloud API numbers.
This endpoint is how you read old messages. Your webhook does not replay them: when a number connects, the device’s history is imported into the chat but not delivered as message.received events. See PATCH /v1/numbers/{id} if you want that delivery turned on for a number.

​
Query parameters

​
string
ISO 8601 datetime. Filter messages with providerTimestamp on or after this date.
​
string
ISO 8601 datetime. Filter messages with providerTimestamp on or before this date.
​
integer
default:"1"
Page number (≥ 1).
​
integer
default:"30"
Results per page (1–100).
Both startDate and endDate are optional individually. When supplied, each must be a valid ISO 8601 string and startDate must not be later than endDate; otherwise 400 INVALID_DATE_RANGE is returned. Results are ordered by providerTimestamp descending (newest first). The endpoint returns up to roughly one month of stored history, counted from the number’s connection date.

​
PII mode effect

The response depends on the PII mode configured for the number (set in the dashboard, on the API Keys page’s Privacy & retention panel or in the number’s settings). The query bounds come solely from your startDate/endDate — the PII window is not applied to the query. Instead, rows that fall outside the retention window are still returned, but redacted: the row is present (keyed on its providerTimestamp) with redacted: true and its text, media, participantName, and participantPhone nulled.

​
Example

​
Message object fields

​
string
required
Pilot Status internal message ID.
​
string
required
ID of the parent conversation (direct or group).
​
string
required
"INBOUND" (received) or "OUTBOUND" (sent).
​
string
required
Provider that handled the message (PILOT_STATUS, META, …).
​
string | null
Provider message id (e.g. Meta wamid) when available.
​
string
required
Message status (QUEUED, SENT, DELIVERED, READ, FAILED, …).
​
string
required
text, image, audio, video, document, location, contacts, sticker, or reaction.
​
string | null
Origin of an outbound message (e.g. APP, API) when available.
​
string | null
Message text or caption when available.
​
string | null
WhatsApp display name of the counterpart/sender when available.
​
string | null
Counterpart/sender in E.164 format when available.
​
string | null
externalMessageId of the message this one replies to, when available.
​
object | null
Media descriptor { provider, id, url, mimeType, fileName } when the message carries media; null otherwise.
  • media.provider — the delivering provider — "META" for Meta Cloud API numbers, or an internal provider tag for unofficial numbers.
  • media.id — Meta media id. Set on META numbers — pass it to GET /v1/media/{mediaId} to download the bytes; null for unofficial numbers.
  • media.url — Direct download URL when available. META inbound media is mirrored to S3 (so META messages usually carry both id and url); the unofficial provider provides its own link. Best-effort — may be null.
  • media.mimeType — Media MIME type when known (may be null).
  • media.fileName — Media file name when known (may be null).
​
boolean
true when the row falls outside the number’s PII retention window (or the number is RELAY_ONLY). Redacted rows keep their id, providerTimestamp, and delivery metadata, but text, media, participantName, and participantPhone are null.
​
string | null
ISO 8601 — when the message was sent.
​
string | null
ISO 8601 — when the message was delivered.
​
string | null
ISO 8601 — when the message was read (only when read receipts are enabled).
​
string
required
ISO 8601 — provider’s timestamp for the message (sort key).
​
string
required
ISO 8601 — when the record was created in Pilot Status.

​
Common errors

  • 400 INVALID_DATE_RANGE — startDate or endDate is not a valid ISO 8601 string, or startDate > endDate.
  • 400 NUMBER_NOT_FOUND — the API key is not bound to a WhatsApp number.
  • 401 — missing or invalid x-api-key header.
  • 403 — tenant-scoped key used (number-scoped key required).