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#

Reference images#

Frequently asked#

Gotchas & common mistakes#