Mídia

Upload (mídia de saída)

POST /v1/connections/:connectionId/media com o arquivo cru no corpo, Content-Type = MIME do arquivo, Content-Length obrigatório e X-Filename opcional (só exibição). O hub confere tipo, tamanho e o conteúdo real do arquivo e sobe para a Meta; o arquivo não fica guardado no hub.

Família	MIME aceitos	Teto
imagem	image/jpeg, image/png	5 MB
sticker	image/webp	500 KB
áudio	audio/aac, audio/amr, audio/mpeg, audio/mp4, audio/ogg	16 MB
vídeo	video/mp4, video/3gpp	16 MB
documento	text/plain, application/pdf, Word, Excel e PowerPoint (.doc, .docx, .xls, .xlsx, .ppt, .pptx)	100 MB

Resposta 201:

{ "media": { "id": "...", "mimeType": "image/png", "size": 48213, "sha256": "...", "expiresAt": "2026-11-21T15:00:00.000Z" } }

Use o id como mediaId no envio até expiresAt (29 dias).

Status	code	Quando
411	CONTENT_LENGTH_REQUIRED	sem Content-Length (envio chunked não é aceito)
415	MEDIA_TYPE_NOT_ALLOWED	MIME fora da tabela
413	MEDIA_TOO_LARGE	acima do teto da família, ou corpo vazio
400	MEDIA_SIGNATURE_MISMATCH	o conteúdo não é do tipo declarado
404 / 409	CONNECTION_NOT_FOUND / CONNECTION_NOT_ACTIVE	conexão
429	MEDIA_UPLOAD_BUSY	uploads simultâneos demais; Retry-After: 5
422	META_MEDIA_REJECTED	a Meta recusou o arquivo, com metaErrorCode
502	META_UNAVAILABLE	resposta incerta da Meta; pode repetir

Mídia recebida

Mensagem com mídia chega no whatsapp.message.received com message.media.id (id do hub) e message.media.status (em geral pending). O hub baixa o arquivo da Meta em segundo plano e emite whatsapp.media.updated quando termina. Esse evento pode chegar antes do whatsapp.message.received da mesma mensagem: correlacione pelo id da mídia ou pelo wamid.

GET /v1/media/:mediaId:

Status	code	Quando
200		{ media: { id, direction, mimeType, size, sha256, filename, createdAt, url, urlExpiresAt } }. url é assinada e vale 5 minutos: baixe na hora e guarde no seu storage. Mídia de saída (direction: "outbound") vem com url: null
404	MEDIA_NOT_FOUND	inexistente ou de outro app
409	MEDIA_NOT_READY	ainda baixando; tente depois ou espere o whatsapp.media.updated
410	MEDIA_UNAVAILABLE	o download falhou ou a mídia venceu na Meta (7 dias), com errorCode

O download é sempre attachment, com o MIME validado pelo hub: tipo fora da lista da Meta, ou conteúdo que não bate com o tipo declarado, vem como application/octet-stream. filename vem do remetente: use só para exibição, nunca como caminho. A mídia recebida fica no hub por 30 dias.