WhatsApp Media Download: Retrieve Files by Media ID

01What is media retrieval?

Media retrieval is how an integration gets the actual bytes of a file from the WhatsApp Cloud API. Webhooks never carry the file itself: an inbound Media Message — an image, voice note, video, sticker or document — arrives as a Media ID inside the message object. Getting the file takes two calls. First, GET https://graph.facebook.com/v26.0/{MEDIA_ID} returns JSON with url, mime_type, sha256, file_size and id. Second, a GET on that url with the same Authorization: Bearer header returns the binary file, with its MIME type in Content-Type.

Two clocks govern it. The URL is valid for five minutes after it is issued; if it lapses, you call GET /{MEDIA_ID} again for a new one. The media ID itself lasts 7 days for files received through webhooks (30 days for files you uploaded), and once it expires the file can no longer be retrieved at all. The download URL is not on graph.facebook.com, but it still requires your access token — requests without it fail.

Media retrieval is the inbound direction; Media Upload is the outbound one, where you push a file to /{PHONE_NUMBER_ID}/media to get an ID for sending. The same retrieval steps also work on IDs you uploaded, which is handy for checking what a stored ID points to, and the optional phone_number_id query parameter on the lookup checks that the media is associated with that business number.

Key takeaways

Media retrieval is a two-step download: GET /{MEDIA_ID} returns a URL, then you fetch that URL with your bearer token.
The download URL expires five minutes after it is issued; request a fresh one instead of storing it.
Inbound media IDs expire after 7 days, so download customer files as soon as the webhook arrives.
A failed download returns 404: request a new URL and retry, and if that fails too, renew the access token.
Check the bytes against sha256 and the expected mime_type before storing or showing the file.

02 · How it works, step by step

How does media retrieval work?

Step 1
Receive the media ID
The Messages Webhook delivers image.id, audio.id, video.id, document.id or sticker.id with mime_type and sha256. Return 200 to the webhook first, then queue a download job.
Step 2
Exchange the ID for a URL
GET /{MEDIA_ID} with your bearer token returns url, mime_type, sha256 and file_size. Issuing the URL starts its five-minute clock.
Step 3
Download with the token
GET the url with Authorization: Bearer {ACCESS_TOKEN}. The body is the binary file and Content-Type gives its MIME type.
Step 4
Verify and store
Hash the bytes and compare with sha256, check size and type, then save the file to your own storage under your own reference.
Step 5
Recover from failures
On a 404 or an expired URL, call GET /{MEDIA_ID} again and retry. If that fails, renew the access token; if the ID itself has expired, ask the customer to resend.

03Media retrieval in code

1# 1. Media ID -> download URL (valid for 5 minutes)
2curl "https://graph.facebook.com/v26.0/{MEDIA_ID}" \
3  -H "Authorization: Bearer {ACCESS_TOKEN}"
4# {"messaging_product":"whatsapp","url":"{MEDIA_URL}","mime_type":"image/jpeg",
5#  "sha256":"{FILE_HASH}","file_size":"303833","id":"{MEDIA_ID}"}
6 
7# 2. URL -> file (the token is required on this request too)
8curl "{MEDIA_URL}" \
9  -H "Authorization: Bearer {ACCESS_TOKEN}" \
10  --output receipt.jpg

04 · Common mistakes, and the fix

Common mistakes with media retrieval

Fetching the URL without the token
The download URL is not public. Requests without Authorization: Bearer fail, so never hand it to a browser or an image tag — serve the file from your own storage instead.
Storing the URL
It is dead five minutes after it was issued. Store the downloaded file (or, briefly, the media ID) and generate your own signed links for agents.
Downloading inside the webhook request
Fetching a 16 MB video before returning 200 slows the webhook and triggers Meta's retries. Acknowledge first, then download from a queue worker.
Letting the queue fall behind
Inbound media IDs expire after 7 days. A backlog or outage longer than that loses files permanently, so alert on the age of the oldest download job.
Trusting the file blindly
Check sha256, size and MIME type, and scan documents before staff open them; customers can send any document type WhatsApp accepts.

05Media retrieval: key facts and limits

Step 1: GET /{MEDIA_ID} → url, mime_type, sha256, file_size, id
Step 2: GET {url} with Authorization: Bearer
URL lifetime: 5 minutes after it is issued
Inbound media ID lifetime: 7 days
Uploaded media ID lifetime: 30 days
Failed download: 404 → request a new URL, then check the token
Media Meta could not fetch: Arrives as webhook error 131052 (media download error)

06Example: Damage claims at a Kolkata courier

A Kolkata courier asks customers to send a photo when a parcel arrives damaged. Each photo reaches the webhook as an image.id; the handler returns 200 and queues a job. Within two seconds a worker exchanges the ID for a URL, downloads the JPEG with the access token, checks the hash, saves it to the company's object storage under the claim number and posts a signed link to the claims inbox. When an agent opens the claim three days later the photo is there, with no dependence on a URL that died after five minutes or an ID with four days left to live.

07Why does media retrieval matter?

Customer files are often the most valuable part of a conversation: a photo of a damaged parcel, a prescription, a signed form, an identity document, a voice note describing a fault. If the webhook pipeline does not retrieve them promptly and reliably, agents see a broken attachment, claims stall and the file is gone for good after seven days. A correct retrieval pipeline — acknowledge, queue, fetch, verify, store — is what makes inbound media usable in a support inbox, a chatbot or a back-office workflow.

08 · Tips from the bench

Best practices for media retrieval

Download inbound media within seconds of the webhook, not when an agent opens the chat.
Keep the mime_type and, for documents, the original filename with the stored file.
Serve files to your inbox from your own object storage with signed URLs.
Log the media ID with every failed download so you can retry while it is still valid.
Size workers and storage for the Media File Limits: documents can be up to 100 MB. A user file Meta itself could not download arrives as error 131052, so ask the customer to resend.

09Media Retrieval FAQs

How do I download media from the WhatsApp Cloud API?+

Call `GET /{MEDIA_ID}` to get a download URL, then GET that URL with your `Authorization: Bearer` token. The response body is the file, and the URL works for five minutes.

Why does my WhatsApp media URL return 404?+

Usually the five-minute URL has expired, or the request was sent without the access token. Request a new URL from `GET /{MEDIA_ID}` and retry with the header; if it still fails, renew the token.

How long can I download a customer's WhatsApp media?+

For 7 days after it arrives, the lifetime of an inbound media ID. After that the file cannot be retrieved, so download and store it as soon as the webhook comes in.

Can I show the WhatsApp media URL directly to agents?+

No. It requires your access token and expires in five minutes. Download the file once, store it, and give agents a link from your own storage instead.

See InfiQ pricing

Media Retrieval

Beat the five-minute download clock

01What is media retrieval?

How does media retrieval work?

Receive the media ID

Exchange the ID for a URL

Download with the token

Verify and store

Recover from failures

03Media retrieval in code

Common mistakes with media retrieval

Fetching the URL without the token

Storing the URL

Downloading inside the webhook request

Letting the queue fall behind

Trusting the file blindly