Skip to main content
List conversations for the connected number, ordered by the most recent message activity.

​
Endpoint

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

​
Query parameters

​
startDate
string
ISO 8601 datetime. Filter conversations whose last message is on or after this date.
​
endDate
string
ISO 8601 datetime. Filter conversations whose last message is on or before this date.
​
page
integer
default:"1"
Page number (≥ 1).
​
pageSize
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.

​
PII mode effect

The response depends on the PII mode configured for the number (set via PATCH /api/whatsapp-numbers/[id]):
PII modeEffect
STORE_INDEFINITE (default)All conversations returned (subject to date filters).
STORE_X_DAYSOnly conversations with activity within the last N days are returned. The effective lower bound is max(startDate, now − piiRetentionDays).
RELAY_ONLYReturns an empty list (conversations: [], total: 0) and includes a notice: "PII_RELAY_ONLY" field. No conversation data is stored for this number.

​
Example

curl "https://pilotstatus.com.br/v1/conversations?startDate=2026-06-01T00:00:00Z&page=1&pageSize=20" \
  -H "x-api-key: ps_your_key_here"

​
Conversation object fields

​
id
string
required
Pilot Status conversation ID.
​
type
string
required
"DIRECT", "GROUP" or "NEWSLETTER".
​
from
string | null
Sender phone in E.164 (with +) for individuals; null for groups/newsletters and lid-only peers.
​
fromName
string | null
Contact or group display name when available (resolved from the conversation).
​
lastMessageAt
string
required
ISO 8601 — timestamp of the last message activity.
​
unreadCount
integer
required
Number of inbound messages not yet read.
​
createdAt
string
required
ISO 8601 — when the conversation was first created.

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