Pular para o conteúdo principal
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.
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.

​
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

​
phoneNumberId
string
obrigatório
O Meta Phone Number ID que recebeu a mensagem. Mesmo valor que phoneNumberId no payload do webhook.

​
Exemplo

curl "https://pilotstatus.com.br/v1/media/abc123?phoneNumberId=123456789012345" \
  -H "x-api-key: ps_your_key_here"

​
Campos de resposta

​
base64
string
obrigatório
Data URI completo (data:<mimeType>;base64,<data>) pronto para incorporação (<img src="...">) ou decodificação.
​
mimeType
string
obrigatório
Tipo MIME da mídia (ex.: image/jpeg, video/mp4, audio/ogg, application/pdf).
​
fileName
string | null
Nome do arquivo original quando disponível (documentos), caso contrário null.
​
mediaId
string
obrigatório
O ID da mídia solicitada.

​
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