Skip to main content
When receiving inbound messages with media via Meta Cloud API webhooks, the payload includes a mediaId. This endpoint downloads the actual media file as base64. You can also obtain the mediaId from the media.id field of inbound messages returned by GET /v1/messages/unread, GET /v1/messages/group, and GET /v1/messages/history — on Meta numbers media.id is the value to pass here.
On unofficial (Pilot Status web) numbers there is no mediaId; those messages carry media.url (a direct download URL) instead, which you fetch directly.

​
Endpoint

GET https://pilotstatus.com.br/v1/media/{mediaId}?phoneNumberId={phoneNumberId}

​
Auth

  • x-api-key: <key> (or x-api-key-id: <api_key_id>)

​
Query parameters

​
string
required
The Meta Phone Number ID that received the message. Same value as phoneNumberId in the webhook payload.

​
Example

​
Response fields

​
string
required
Complete data URI (data:<mimeType>;base64,<data>) ready for embedding (<img src="...">) or decoding.
​
string
required
Media MIME type (e.g. image/jpeg, video/mp4, audio/ogg, application/pdf).
​
string | null
Original filename when available (documents), otherwise null.
​
string
required
The requested media ID.

​
Errors

  • 400 — missing phoneNumberId or number has no metaAccessToken
  • 401 — invalid or missing API key
  • 403 — operation not allowed for this key (e.g., a tenant-scoped key on a number-scoped endpoint)
  • 404 — media not found on Meta or number not accessible
  • 500 — download failed

​
Notes

  1. The WhatsApp number referenced by phoneNumberId must have a valid metaAccessToken configured in Pilot Status.
  2. Media downloads must happen before the Meta-signed URL expires (typically a few minutes after the webhook is received).
  3. The base64 field is a complete data URI ready for direct use.
  4. For stickers, the MIME type is typically image/webp.
  5. For audio, Meta may return audio/ogg (voice messages) or audio/mp4.

​
Webhook payload fields (Meta Cloud API)

Inbound webhooks from Meta Cloud API (message.received, message.reply) include these media-related fields when applicable:
  • content — text body or media caption
  • mediaType — "image" | "video" | "audio" | "document" | "sticker" | "location" | "contacts" | "interactive" | "button" | "reaction"
  • mediaId — Meta media object ID
  • mediaMimeType — MIME type
  • mediaCaption — caption when available
  • mediaFilename — original filename (documents)
  • mediaDownloadHint — instructions for downloading via this endpoint