Mídia
Faça o upload da mídia uma única vez para distribuir uma mesma imagem / áudio / documento para muitos destinatários sem reenviar toda vez.
{ "source_url": "https://cdn.example.com/promo.jpg", "mime_type": "image/jpeg" }Retorna { media_id, media_url, mime_type, size }. Encaixe o media_url no campo media_url do body de qualquer envio de mensagem subsequente. O limite de 25 MB corresponde ao limite por mensagem que o WhatsApp aplica para áudio / documento.
Mídia recebida
Mídia recebida flui por um proxy assinado em GET /v1/media/:token — o token é a autorização, então seu front-end pode fazer hot-link sem expor chaves de API.
Retenção
Guardamos a mídia recebida por uma janela limitada e depois apagamos os bytes. O expiresAt do token é o mesmo prazo da retenção do arquivo que ele aponta, então um token que ainda parece válido sempre resolve para bytes que ainda temos.
Passada a janela, a mídia se perde de vez — planeje persistir os bytes do seu lado. Você vai ver:
| Status | Código | Significado |
|---|---|---|
| 401 | media_token_expired | O token passou do expiresAt. |
| 410 | media_gone | Não guardamos mais essa mídia. |
Buscar de novo pelo message id
Se a sua ingestão falhou e o media_url do webhook já venceu, busque os mesmos bytes com a API key do canal — sem token assinado. O :messageId é o message_id do payload do webhook.
Responde com os bytes crus e o Content-Type original. Retorna 404 message_not_found quando a mensagem não é daquele canal, e 410 media_gone quando a retenção já descartou o arquivo.