Skip to content

Media ID

Also called: WhatsApp media ID · Media object ID · media_id

Definition
The ID the WhatsApp Cloud API returns for an uploaded file, or sends in an inbound media message, used to send or download that file.

Exhibit A

Follow a media ID from birth to expiry

3 / 3
  • Uploaded to Referenced in a send: send by ID
  • Uploaded to URL issued: GET /{MEDIA_ID}
  • Received to URL issued: GET /{MEDIA_ID}
  • URL issued to Downloaded: fetch url with token
  • Referenced in a send to Deleted: DELETE /{MEDIA_ID}
  • Referenced in a send to Expired: after 30 days
  • Received to Expired: after 7 days
  1. Uploaded
  2. Referenced in a send
  3. Expired

Step 3 of 3 · end of walk

Expired

30 days after upload or 7 days after receipt. Sends and lookups with this ID now fail.

Arrived from Referenced in a send via after 30 days.

Can move to

Nothing — this is a final state.

A media ID is born by upload or by an inbound message, is used to send or to fetch a 5-minute URL, and ends by deletion or expiry. Switch paths to compare an uploaded file with a customer's photo.

Happy path, step 3 of 3: Expired (via after 30 days). 30 days after upload or 7 days after receipt. Sends and lookups with this ID now fail.

What is a media ID?

A media ID is the identifier the WhatsApp Cloud API gives a file stored on WhatsApp's servers. You get one in two ways: through Media Upload — POST /{PHONE_NUMBER_ID}/media — which returns {"id": "..."}, or by receiving one — when a customer sends a photo, voice note or PDF, the Messages Webhook carries the file's ID inside the message object (image.id, audio.id, document.id and so on) together with its mime_type and sha256.

The ID is a handle, not the file. To send, you reference it in the media object of a Media Message, such as "image": {"id": "{MEDIA_ID}"}, on the messages endpoint — or as a template header parameter. To download it — Media Retrieval — you call GET /{MEDIA_ID}, which returns a short-lived url plus mime_type, sha256 and file_size, then fetch that URL with your access token. To remove a file you uploaded before it lapses, call DELETE /{MEDIA_ID}.

Validity is where teams slip. IDs returned by an upload are kept for 30 days unless you delete them sooner; IDs received in webhooks expire after 7 days, and with them the ability to download that customer's file. The media URL you get from an ID is shorter-lived still, at five minutes. That is the difference between the two: the media ID is a reusable reference that lives for days, while the media URL is a download link that lives for minutes. Nor is it the file handle the Resumable Upload API returns for template sample media: that handle goes into a template definition and cannot be used to send.

Key takeaways

  • A media ID identifies a file stored on WhatsApp's servers: you send by referencing it and download by exchanging it for a URL.
  • Media IDs from your own uploads stay valid for 30 days; IDs received in inbound webhooks expire after 7 days.
  • A media ID is not a link: GET /{MEDIA_ID} returns a download URL that itself expires after 5 minutes.
  • One uploaded media ID can be reused across many sends while valid, instead of uploading the same file per recipient.
  • Download inbound files promptly — once the ID expires, the customer's file can no longer be fetched.

How does a media ID work?

  1. Upload or receive

    Uploading a file to /{PHONE_NUMBER_ID}/media returns an ID that lasts 30 days. An inbound media message delivers an ID in the webhook that lasts 7 days.

  2. Send by reference

    Put the ID in the media object of a send, e.g. "document": {"id": "{MEDIA_ID}", "filename": "invoice.pdf"}. The same ID can be used in many sends while it is valid.

  3. Resolve it to a URL to download

    GET /{MEDIA_ID} returns url, mime_type, sha256 and file_size. The URL expires in 5 minutes; ask for a new one if it lapses.

  4. Fetch with your token and keep the file

    Download the URL with Authorization: Bearer {ACCESS_TOKEN} — without it the request fails — check the bytes against sha256, and store the file in your own storage.

  5. Delete it or let it expire

    DELETE /{MEDIA_ID} removes an uploaded file early and returns {"success": true}. Otherwise the ID simply stops working when its validity ends.

Example: One upload, a week of fee reminders

A Bhopal school uploads its term fee schedule PDF once at 9 am on Monday and stores the returned media ID with an expiry date 30 days out. Its utility template with a document header uses that same ID for all 3,400 parents over the week. When a parent replies with a photo of the payment receipt, the webhook carries a new media ID; the school's worker downloads the file within seconds, checks its hash, attaches it to the student's record and never needs that 7-day ID again.

A media ID in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "919812345678",
    "type": "document",
    "document": {
      "id": "{MEDIA_ID}",
      "filename": "fee-schedule.pdf",
      "caption": "Term 2 fee schedule"
    }
  }'

Common mistakes with a media ID

  • Storing the ID instead of the file

    Inbound IDs expire after 7 days. If your inbox keeps only the ID, customer photos and documents become unrecoverable. Download inbound media on arrival and keep it in your own storage.

  • Confusing the ID with the URL

    Saving the url from GET /{MEDIA_ID} and using it later fails, because it lasts 5 minutes. Keep the ID (while valid) or the downloaded file, never the URL.

  • Re-uploading for every send

    Uploading the same brochure once per recipient wastes time and requests. Upload once, cache the ID with its 30-day expiry and reuse it across the campaign.

  • Using a stale upload ID in a scheduled campaign

    A campaign scheduled 35 days after the upload fails on every message. Record the upload date with the ID and re-upload before the 30 days run out.

Why does a media ID matter?

Media IDs make outbound files efficient and inbound files retrievable. A business sending the same brochure to 20,000 customers uploads it once and reuses the ID, instead of uploading 20,000 times or making WhatsApp fetch a public link for every send. On the inbound side, the ID is the only way to get a customer's photo or document at all, and the 7-day expiry means a support system that does not download promptly loses evidence such as damaged-product photos, prescriptions or signed forms.

Best practices for a media ID

  • Save the upload timestamp with each media ID and refresh it at around 25 days.
  • Verify downloaded bytes against the sha256 from the webhook or the media lookup.
  • Pass phone_number_id on lookups and deletes to confirm the file belongs to your number.
  • Keep a map of file hash to media ID so identical files share one upload.

Media ID FAQs

How long is a WhatsApp media ID valid?+
30 days for media you upload and 7 days for media IDs received in inbound webhooks. After that the ID stops working, so cache upload IDs with their date and download inbound files promptly.
What is the difference between a media ID and a media URL?+
The ID is a reusable reference valid for days. The URL is a download link returned by `GET /{MEDIA_ID}` that expires after 5 minutes and needs your access token to fetch.
Can I send the same media ID to many recipients?+
Yes. While it is valid, one uploaded media ID can be referenced in any number of sends, which is faster than uploading the file for each recipient or passing a public link every time.
Should I send media by ID or by link?+
Use an ID for files you send repeatedly or that should not be public; use `link` for files already on a public HTTPS URL that you send occasionally. The customer receives the same media message either way.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms