Skip to main content
Retrieve messages from GROUP conversations for the connected number.

​
Endpoint

GET https://pilotstatus.com.br/v1/messages/group
Requires a number-scoped API key (ps_*) in the x-api-key header. Tenant-scoped keys return 403.
Meta numbers: this endpoint works for official Meta Cloud API numbers too, provided the number is an approved Official Business Account with groups enabled. Numbers that are not eligible return 400 META_GROUPS_NOT_ELIGIBLE.

​
Query parameters

​
startDate
string
ISO 8601 datetime. Filter messages created on or after this date.
​
endDate
string
ISO 8601 datetime. Filter messages created 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. Results are ordered by createdAt descending (newest first).

​
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 group messages returned (subject to date filters).
STORE_X_DAYSOnly messages within the last N days are returned. The effective lower bound is max(startDate, now − piiRetentionDays). Messages outside the retention window have been hard-deleted by the daily job.
RELAY_ONLYReturns an empty list (messages: [], total: 0) and includes a notice: "PII_RELAY_ONLY" field. No message data is stored for this number.

​
Example

curl "https://pilotstatus.com.br/v1/messages/group?startDate=2026-06-01T00:00:00Z&endDate=2026-06-27T23:59:59Z&page=1&pageSize=30" \
  -H "x-api-key: ps_your_key_here"

​
Message object fields

​
id
string
required
Pilot Status internal message ID.
​
conversationId
string
required
ID of the parent group conversation.
​
direction
string
required
"INBOUND" (received in the group) or "OUTBOUND" (sent to the group).
​
type
string
required
text, image, audio, video, document, location, contacts, sticker, or reaction.
​
content
string | null
Message text or caption when available.
​
from
string
required
Sender in E.164 format.
​
participantName
string | null
WhatsApp display name of the sender when available.
​
groupId
string
required
Group JID (e.g. 120363123456789012@g.us).
​
groupName
string | null
Group display name when available.
​
media
object | null
Media descriptor { provider, id, url, mimeType, fileName } when the message carries media; null for text.
  • media.provider — "META", "EVO", or "EVO_GO" — the provider that delivered the media.
  • media.id — Meta media id. Set on META numbers — pass it to GET /v1/media/{mediaId} to download the bytes; null on Evolution.
  • media.url — Direct download URL when available. META inbound media is mirrored to S3 (so META messages usually carry both id and url); Evolution 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).
​
createdAt
string
required
ISO 8601 — when the message was created.

​
Common errors

  • 400 META_GROUPS_NOT_ELIGIBLE — the API key is bound to a Meta Cloud API number that is not an approved Official Business Account (or does not have groups enabled).
  • 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).