Skip to main content
Retrieve the inbound messages that count as unread for the connected number. Unread is not derived from a per-message readAt flag (per-message readAt is not maintained for inbound messages). Instead, it is derived from each conversation’s unreadCount — the same counter shown in the dashboard — and the response total is the sum of unreadCount across the unread conversations. Each item includes that conversation-level unread count.

​
Endpoint

GET https://pilotstatus.com.br/v1/messages/unread
Requires a number-scoped API key (ps_*) in the x-api-key header. Tenant-scoped keys return 403.

​
Query parameters

​
integer
default:"1"
Page number (≥ 1).
​
integer
default:"30"
Results per page (1–100).
There is no date-range filter on this endpoint; it returns all currently unread inbound messages.

​
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). This endpoint uses redact-and-show: it does not apply a hard retention date filter — message envelopes are still returned, but content, from, media, and fromName/sender are nulled and redacted: true is set for rows the PII policy covers.

​
Example

​
Message object fields

​
string
required
Pilot Status internal message ID.
​
string
required
ID of the parent conversation.
​
integer
required
Total unread message count for that conversation.
​
string
required
Always "INBOUND" for this endpoint.
​
string
required
text, image, audio, video, document, location, contacts, sticker, or reaction.
​
string | null
Message text or caption when available.
​
string
required
Sender in E.164 format.
​
string | null
Sender display name (resolved from the conversation) when available.
​
object | null
Media descriptor { provider, id, url, mimeType, fileName } when the message carries media; null for text.
  • 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 content, media, and the sender fields were nulled by the number’s PII policy (see PII mode effect); false (or absent) when the row is returned in full.
​
null
required
Always null — per-message readAt is not maintained for inbound messages; unread state is tracked at the conversation level via conversationUnreadCount.
​
string
required
ISO 8601 — when the message was received.

​
Common errors

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