Media by URL vs Media ID

Every media message (image, document, video, audio) needs you to tell WhatsApp where to get the file. There are exactly two ways: give it a public URL and let Meta fetch it, or upload the file to Meta’s servers first and use the ID Meta gives you.

Method 1 — Media by URL

Give WhatsApp a public link. Meta fetches the file and delivers it.

{
  "messaging_product": "whatsapp",
  "to": "919959623255",
  "type": "image",
  "image": {
    "link": "https://example.com/photo.jpg",
    "caption": "Here is your invoice"
  }
}

Requirements for the URL:

Must be publicly accessible — no login, no password, no auth header
Must be https:// — not http://. WhatsApp requires encrypted URLs
If your file is on localhost or a private server, use ngrok or Cloudflare Tunnel to expose it temporarily as a public https:// URL

Use when: The file is already hosted on a public server, CDN, or cloud storage (S3, Google Cloud, etc.).

Method 2 — Media by ID

Upload the file to Meta’s servers first, receive a media_id, then use that ID in your message. Step 1 — Upload the file:

POST https://graph.facebook.com/v21.0/{phone-number-id}/media
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data

messaging_product = whatsapp
file              = [the actual file bytes]
type              = image/jpeg

Meta returns:

{ "id": "1234567890" }

Step 2 — Send the message using the ID:

{
  "messaging_product": "whatsapp",
  "to": "919959623255",
  "type": "image",
  "image": {
    "id": "1234567890",
    "caption": "Here is your invoice"
  }
}

Use when: The file is on your local machine, a private server, or you send the same file to many users (upload once, reuse the ID).

Side-by-side comparison

	URL method	Media ID method
Steps to send	1	2 (upload then send)
File must be public	Yes	No
Works with localhost	No (use ngrok)	Yes
Reuse same file	No (re-fetched each time)	Yes (same ID for all sends)
ID expiry	n/a	30 days — after that the ID stops working
Best for	Files already hosted online	Local files, private files, repeated sends

Local testing: to test the URL method with a file on your computer, run ngrok http 3000 for a temporary public https:// URL, or use Cloudflare Tunnel (free, more stable for longer sessions). Both create a public tunnel to your local machine so Meta can fetch the file.

Reference images

Media by URL example — Sending a media message using a public URL.

Media upload step — Uploading a file to Meta's servers to get a media ID.

Send using media ID — Sending a media message using the media ID returned from the upload step.

Frequently asked

How do I send an image on WhatsApp API?

Two ways — provide a public https:// URL to the image in the link field, or upload the image to Meta first and use the returned ID in the id field. Both go in the image object of your request body.

Why is my image link not working even though the URL is correct?

The URL must be publicly accessible (no login required) and must use https:// not http://. If your file is on a local or private server, use ngrok or Cloudflare Tunnel to create a public URL.

How do I upload a file to WhatsApp before sending it?

Send a multipart/form-data POST to https://graph.facebook.com/v21.0/{phone-number-id}/media with your token, messaging_product=whatsapp, the file bytes, and the MIME type. Meta returns a media_id you then use in your message.

Can I reuse the same media ID for multiple users?

Yes. Upload once and use the ID in as many messages as you want. Media IDs are valid for 30 days — after that you must re-upload.

Which method should I use — URL or media ID?

URL is simpler if the file is already public online. Media ID is better for files on your own server, large files you send repeatedly, or any file that is not publicly accessible.

Gotchas & common mistakes

http:// instead of https:// — WhatsApp rejects non-HTTPS URLs. Always use https://.
Private or authenticated URLs — if the URL requires a login or token, Meta cannot fetch it and the send will fail.
Localhost URLs — http://localhost/file.jpg is not reachable by Meta’s servers. Use ngrok or Cloudflare Tunnel for local testing.
Expired media ID — media IDs expire after 30 days. Re-upload before the ID expires if you plan to reuse it.
Wrong MIME type on upload — the type field must match the actual file format (e.g. image/jpeg, application/pdf). A mismatch causes the upload or send to fail.

​Method 1 — Media by URL

​Method 2 — Media by ID

​Side-by-side comparison

​Reference images

​Frequently asked

​Gotchas & common mistakes

Method 1 — Media by URL

Method 2 — Media by ID

Side-by-side comparison

Reference images

Frequently asked

Gotchas & common mistakes