> ## 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} — Baixar Mídia de Entrada

> Baixe mídia de entrada recebida via Meta Cloud API como base64.

When receiving inbound messages with media via Meta Cloud API webhooks, the payload includes a `mediaId`. Este endpoint baixa o arquivo de mídia real como base64.

Você também pode obter o `mediaId` a partir do campo `media.id` das mensagens de entrada retornadas por `GET /v1/messages/unread`, `GET /v1/messages/group` e `GET /v1/messages/history` — em números **Meta**, `media.id` é o valor a ser passado aqui.

<Note>
  Em números **não oficiais (Pilot Status web)** não há `mediaId`; essas mensagens carregam `media.url` (uma URL de download direto), que você busca diretamente.
</Note>

## Endpoint

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

## Autenticação

* `x-api-key: <key>` (ou `x-api-key-id: <api_key_id>`)

## Parâmetros de query

<ParamField query="phoneNumberId" type="string" required>
  O Meta Phone Number ID que recebeu a mensagem. Mesmo valor que `phoneNumberId` no payload do webhook.
</ParamField>

## Exemplo

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

## Campos de resposta

<ResponseField name="base64" type="string" required>
  Data URI completo (`data:<mimeType>;base64,<data>`) pronto para incorporação (`<img src="...">`) ou decodificação.
</ResponseField>

<ResponseField name="mimeType" type="string" required>
  Tipo MIME da mídia (ex.: `image/jpeg`, `video/mp4`, `audio/ogg`, `application/pdf`).
</ResponseField>

<ResponseField name="fileName" type="string | null">
  Nome do arquivo original quando disponível (documentos), caso contrário `null`.
</ResponseField>

<ResponseField name="mediaId" type="string" required>
  O ID da mídia solicitada.
</ResponseField>

## Erros

* `400` — `phoneNumberId` ausente ou número sem `metaAccessToken`
* `401` — chave de API inválida ou ausente
* `403` — operação não permitida para esta chave (ex.: uma chave com escopo de tenant em um endpoint com escopo de número)
* `404` — mídia não encontrada na Meta ou número não acessível
* `500` — falha no download

## Notas

1. O número de WhatsApp referenciado por `phoneNumberId` deve ter um `metaAccessToken` válido configurado no Pilot Status.
2. Os downloads de mídia devem ocorrer antes que a URL assinada pela Meta expire (normalmente alguns minutos após o webhook ser recebido).
3. O campo `base64` é um data URI completo pronto para uso direto.
4. Para figurinhas, o tipo MIME é normalmente `image/webp`.
5. Para áudio, a Meta pode retornar `audio/ogg` (mensagens de voz) ou `audio/mp4`.

## Campos do payload do webhook (Meta Cloud API)

Webhooks de entrada da Meta Cloud API (`message.received`, `message.reply`) incluem estes campos relacionados a mídia quando aplicável:

* `content` — corpo do texto ou legenda da mídia
* `mediaType` — `"image"` | `"video"` | `"audio"` | `"document"` | `"sticker"` | `"location"` | `"contacts"` | `"interactive"` | `"button"` | `"reaction"`
* `mediaId` — ID do objeto de mídia da Meta
* `mediaMimeType` — tipo MIME
* `mediaCaption` — legenda quando disponível
* `mediaFilename` — nome do arquivo original (documentos)
* `mediaDownloadHint` — instruções para download via este endpoint