Get started
Documentation topics
Developer docs

Download received media

GET https://api.unpoll.cc/v1/agents/{id}/media/{media_id}

A received image, audio, video, document, or sticker carries its WhatsApp media ID in data.<type>.id, never the file itself. Download it with the agent's API key; Unpoll uses the stored WhatsApp token for you. Your bot does not need the provider token or a provider media URL.

curl "https://api.unpoll.cc/v1/agents/$AGENT_ID/media/$MEDIA_ID" \
  -H "Authorization: Bearer $UNPOLL_API_KEY" \
  -o photo.jpg

Check the response status before treating the output as a file: non-200 responses use the JSON error format.

Successful downloads

  • 200 returns the file's bytes, not JSON metadata or a redirect.
  • Content-Type is WhatsApp's MIME type, reduced to a lowercase type/subtype, or application/octet-stream. The response has Content-Disposition: attachment.
  • Unpoll checks the file's size and SHA-256 before returning it, so a 200 is always the complete file.
  • The original filename, caption, and voice-note flag remain in the webhook event, not in a reconstructed message.
  • Unpoll stores no media files. Each download fetches the file from WhatsApp again. Download each file once and keep your own copy if you need it later.

Availability and limits

WhatsApp keeps received media for 30 days. After that, or for an ID belonging to another agent, the call returns 404 media_not_found. This provider media lifetime is separate from Unpoll's 7-day event history.

Files are at most 16 MB (the download cap is 16 MiB). Each call counts against 12 media lookups per minute per agent, separately from sends and read calls. Downloads work for active and paused agents.

Each Unpoll API instance downloads at most 4 files at once. A download waits up to 10 seconds for a slot, then returns 503 unavailable if none becomes available.

Media errors

Statuserror.codeMeaning
400invalid_requestThe media ID is empty, over 256 bytes, or not visible ASCII.
404media_not_foundWhatsApp does not know the ID: it expired, belongs to another agent, or never existed.
429rate_limitedOver 12 downloads per minute for this agent, here or at WhatsApp. Retry after Retry-After.
502media_too_largeWhatsApp reports a file over 16 MiB.
502media_unavailableWhatsApp failed, timed out, or returned a file that does not match its size or SHA-256. Retry after Retry-After.
503unavailableUnpoll is busy or unavailable. Retry after Retry-After.

401 invalid_api_key, 404 not_found, 409 agent_disconnected, and 409 provider_credentials_rejected have the same meanings as on the send route.

Received media can be downloaded, not sent. Unpoll exposes no media-upload or media-send API.