How to Send Images, PDFs, and Voice Notes via WhatsApp API Without Your Code Breaking

Imagine you run a logistics company in Lahore or an e-commerce brand in Mumbai. Every day, your team manually sends hundreds of order confirmations, PDF invoices, and delivery photos. A customer pings your WhatsApp number asking for a receipt. Your support agent has to find the file on their desktop, drag it into WhatsApp Web, and send it.

When you are handling ten orders a day, this is manageable. When you scale to a hundred or a thousand, your operations will stall. You need to automate this process.

Sending text via the WhatsApp API is relatively straightforward. Sending media—images, PDFs, and audio files—is where things get complicated. Files fail to load, formats are rejected, and numbers get flagged for spam if you set things up incorrectly. This guide walks you through how the media API actually works, the options available to you, and how to write payloads that do not break in production.

The Two Ways to Connect to the WhatsApp API

Before you write a single line of code, you must choose how you want to connect to the WhatsApp network. There are two primary routes, and each has distinct trade-offs regarding cost, speed, and rules.

Option 1: Meta’s Official Cloud API

This is the official engine hosted directly on Meta’s servers. You register your business, verify your Meta Business Manager, and hook your backend up to their endpoints.

• The Cost: Meta does not charge for the API itself, but they charge per 24-hour conversation window. These rates vary by country and category (Utility, Marketing, or Service). For instance, a utility conversation (like sending an invoice) to an Indian number costs around 0.11 INR, while in Pakistan it is about 0.016 USD. You can check the exact, up-to-date rates directly on Meta's developer portal pricing sheet.
• The Catch: You cannot just send any media file whenever you want. If you initiate the conversation, you must use an approved media template. Meta must review and approve this template beforehand. If the customer initiates the conversation, you have a 24-hour window to send any media file you want without template approval.

Option 2: Unofficial or QR-Code Based APIs

These APIs run by automating a physical WhatsApp instance. You scan a QR code using a spare Android or iOS device, and the API sends messages by mimicking WhatsApp Web actions.

• The Cost: Usually a flat monthly subscription fee to the provider, with no per-message or per-conversation charges.
• The Catch: Since you are bypassing Meta's official infrastructure, you run a high risk of getting your number banned if you send high volumes of unsolicited media. If you choose this route for internal alerts or low-volume customer service, read our guide on how to connect your WhatsApp number to an API using a QR code.

If you decide to use a QR-based setup, we at WA Link offer a stable gateway that lets you connect your existing number in minutes. However, we are honest about its limits: it is not built for sending cold marketing blasts to thousands of people. If you try that, WhatsApp will block your SIM card within hours. To understand how to avoid this, read our advice on how to run a WhatsApp API without losing your number.

How Meta Handles Media: Link vs. ID

When using Meta’s Official Cloud API, you have two ways to send a file: by passing a public URL (Media by Link) or by uploading the file directly to Meta's servers first (Media by ID).

Method A: Sending Media via a Public URL (Recommended)

This is the easiest method for most developers. You host the image or PDF on your own secure server (like AWS S3, DigitalOcean Spaces, or your own web host) and send the direct link in your API request. Meta's servers will download the file, cache it, and deliver it to the user.

The major downside is caching. If you update an invoice at https://yourdomain.com/invoice-102.pdf but keep the exact same URL, Meta might send the old cached version of the file to the user. To prevent this, always append a unique query parameter or use unique file names, like invoice-102.pdf?v=1712001.

Method B: Sending Media via Media ID

If your files contain highly sensitive data that cannot sit on a public URL, you must upload them to Meta's servers first. You send a POST request to Meta’s /media endpoint containing the binary file. Meta returns a media_id. You then use this ID in your message payload. These uploaded files expire after 30 days, so you cannot store them there permanently.

The Code: Exact API Payloads for Media

Let us look at the actual JSON payloads you need to send to Meta's Cloud API endpoint. For these examples, we assume you are sending messages within an active 24-hour customer service window, meaning you do not need an approved template.

The endpoint you will post to is:

POST https://graph.facebook.com/v18.0/YOUR_PHONE_NUMBER_ID/messages

Your request must include an Authorization header with your Bearer Token, and a Content-Type header set to application/json.

1. How to Send an Image (JPEG/PNG)

Keep your images under 5MB. WhatsApp will reject anything larger. Stick to standard formats like JPG or PNG. Do not use WebP for standard images; WhatsApp reserves WebP for stickers, and sending it as a standard image can cause rendering errors on older Android devices.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+923001234567",
  "type": "image",
  "image": {
    "link": "https://yourdomain.com/assets/order-receipt.png",
    "caption": "Your payment receipt for Order #8902."
  }
}

2. How to Send a Document (PDF/Docs)

While Meta supports file formats like Excel (.xlsx) and Word (.docx), we do not recommend using them. In our experience working with retail and logistics clients, sending spreadsheets or Word files leads to immediate support complaints. Budget Android devices often do not have apps installed that can preview these files. The user is forced to download them and find a viewer. Always convert your invoices, receipts, and reports to PDF before sending.

Documents can be up to 100MB, but you should keep them as small as possible to save your user's mobile data.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919876543210",
  "type": "document",
  "document": {
    "link": "https://yourdomain.com/docs/invoice-102.pdf",
    "caption": "Monthly Statement - October",
    "filename": "October_Statement.pdf"
  }
}

The filename parameter is important. If you omit it, WhatsApp will display a generic, auto-generated string as the file name, which looks unprofessional and suspicious to the recipient.

3. How to Send Audio (Voice Notes vs. Audio Files)

This is where most developers get stuck. There is a major difference between sending an audio file and sending a voice note.

If you send an MP3 file using the standard audio payload, it will appear in the user's chat as a generic file with a download button. It will not have the inline play button, the waveform, or the blue microphone icon.

If you want it to look and behave like a native voice note recorded on a phone, you must fulfill two strict conditions:

• The audio container must be OGG.
• The audio codec must be OPUS.

If you try to send an MP3 or a standard WAV file as a voice note, WhatsApp will either reject the API call or display it as a broken file. You can use tools like FFmpeg on your server to convert your audio assets before sending them.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+923001234567",
  "type": "audio",
  "audio": {
    "link": "https://yourdomain.com/audio/welcome-note.ogg"
  }
}

Why Your Media Messages Will Fail (And How to Fix It)

When you build a system that sends media, things will go wrong. Images will fail to load, files will show up as empty blocks, and your code will throw errors. Here are the most common points of failure we see in production environments.

1. The SSL Certificate and Hosting Issue

If you use the "Media by Link" method, Meta’s servers must fetch the file from your server. If your server has a self-signed SSL certificate, or if your SSL chain is broken, Meta will refuse to connect and the message will fail.

Similarly, if you use security tools like Cloudflare and have "Under Attack Mode" or strict firewall rules turned on, Cloudflare will challenge Meta's fetch request with a JS challenge or a Captcha. Meta's automated crawler cannot solve these, so the request times out. You must whitelist Meta's IP ranges or use a dedicated, unprotected bucket for public media assets.

2. The "Media Download Failed" Error (Error Code 131015)

This is the bane of WhatsApp API developers. You send the API request, Meta returns a 200 OK with a message ID, but the customer never receives the message. When you check your webhooks, you see error code 131015.

This error means Meta accepted your API call but failed to download the asset from your URL. This usually happens because:

• Your file URL returned a 404 Not Found.
• Your server was too slow to respond (Meta expects the file download to start within a few seconds).
• The MIME type returned by your server's HTTP headers does not match the file extension. For example, if you serve a PDF but your server sends a header of Content-Type: text/html, Meta will reject it.

To debug this properly, you must set up webhooks to capture these asynchronous errors. To learn how to parse these events, read our detailed guide on tracking WhatsApp API message statuses, webhooks, and error codes.

3. File Size Limits

Do not guess your file sizes. If your system allows users to upload files that you automatically forward to WhatsApp, you must implement strict client-side or server-side validation. The limits are hard:

Frequently Asked Questions

Can I send password-protected PDFs via the WhatsApp API?

Yes. WhatsApp does not open or inspect the contents of your document files; it simply acts as a delivery pipe. If you generate a password-protected PDF (such as a bank statement or salary slip) and send it, the user will receive it normally. They will be prompted to enter the password when they tap to open the file inside WhatsApp.

Why does my audio file show up as a document instead of a playable voice note?

This happens because of the file format and codec. If you send an MP3 or standard WAV file, WhatsApp treats it as a generic document. To make it appear as a native voice note with a play button, you must convert the file to an OGG container encoded with the OPUS codec, and you must use the audio parameter in your JSON payload, not the document parameter.

Does Meta charge extra for sending media instead of text?

No. Meta charges per conversation window, not per message. Once a conversation window is open (whether initiated by a template or a customer reply), you can send as many text and media messages as you want within that 24-hour window at no extra cost. However, keep in mind that hosting the media files on your own servers will incur standard bandwidth and storage costs from your hosting provider.

How long do media files remain accessible on WhatsApp?

If you send media via a link, WhatsApp downloads and caches the file on its servers. Once delivered to the user's phone, the media remains there until the user deletes it or clears their chat history. If you upload media using Meta's /media upload endpoint to get a media_id, that specific ID is only valid for 30 days. You must use it to send a message within that timeframe, or the ID will expire and you will have to upload the file again.