> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/media/{mediaId} — Download Inbound Media

> Download inbound media received via Meta Cloud API as base64.

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.

<Note>
  On **Evolution** (`EVO`/`EVO_GO`) numbers there is no `mediaId`; those messages carry `media.url` (a direct download URL) instead, which you fetch directly.
</Note>

## 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

<ParamField query="phoneNumberId" type="string" required>
  The Meta Phone Number ID that received the message. Same value as `phoneNumberId` in the webhook payload.
</ParamField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://pilotstatus.com.br/v1/media/abc123?phoneNumberId=123456789012345" \
    -H "x-api-key: ps_your_key_here"
  ```

  ```json Response (200) theme={null}
  {
    "base64": "data:image/jpeg;base64,/9j/4AAQ...",
    "mimeType": "image/jpeg",
    "fileName": "photo.jpg",
    "mediaId": "abc123_media_id"
  }
  ```
</CodeGroup>

## Response fields

<ResponseField name="base64" type="string" required>
  Complete data URI (`data:<mimeType>;base64,<data>`) ready for embedding (`<img src="...">`) or decoding.
</ResponseField>

<ResponseField name="mimeType" type="string" required>
  Media MIME type (e.g. `image/jpeg`, `video/mp4`, `audio/ogg`, `application/pdf`).
</ResponseField>

<ResponseField name="fileName" type="string | null">
  Original filename when available (documents), otherwise `null`.
</ResponseField>

<ResponseField name="mediaId" type="string" required>
  The requested media ID.
</ResponseField>

## 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