WhatsApp Document Message: Send PDFs and Files

01 · How it works, in 5 steps

How does a document message work?

1
Produce a phone-friendly file
Export a PDF that reads well on a small screen and keep it well under 100 MB. Avoid password protection unless the customer already knows the password.
2
Upload it
POST the file to /{PHONE_NUMBER_ID}/media as multipart form data with messaging_product=whatsapp and its MIME type. The response is a media id, valid for 30 days.
3
Name it for the customer
Set filename to something meaningful with the extension, such as GST-Invoice-ACS-20871.pdf, and write a caption that says what the file is and what to do with it.
4
Pick the right vehicle
Inside the window, send type: "document". Outside it, send an approved template whose header is a document, passing the media id or link as the header parameter.
5
Confirm and keep records
Track the delivered and read statuses for the wamid, and keep the original in your own storage — the media ID expires, and the customer may ask for the file again.

02Try it

Hands-on: use the controls to work through it yourself.

Send an invoice, then a copy on request

4 / 4

Nagpur AC ServiceBusiness account

Today

Nagpur AC Service: GST-Invoice-ACS-20871.pdfDocumentHi Meera, here is your invoice for today's AC service. Keep it for warranty claims.Reply here if anything looks wrong10:30Read
Customer: Thanks! Can you also send last year's invoice? I need it for the warranty.10:31
Nagpur AC Service: GST-Invoice-ACS-11402.pdfDocumentHere it is: the service visit from 12 May 2025.10:32Read
Customer: Got both, thank you!10:33

Message 4 of 4

CustomerText

Free-form text. A business can send it only within 24 hours of the customer’s last message.

First the invoice arrives as an approved template's document header; then, inside the window the customer's question opens, as a plain document message. Step through to see filename, caption and ticks.

03What is a document message?

A document message is the WhatsApp message type (type: "document") for sending a file the customer can open, save or forward: an invoice, an e-ticket, a bank statement, a policy schedule, a menu. The customer sees a file card with an icon for the file type, the filename and an optional caption underneath, and taps it to open the file in their phone's viewer.

On the Cloud API the document object takes either an id — a media ID from uploading the file with POST /{PHONE_NUMBER_ID}/media, which Meta recommends for performance — or a link to the file on a public HTTPS server, plus an optional caption and an optional filename. The filename should include the extension, because the WhatsApp client picks the icon from it. Officially supported types are PDF, Word (DOC, DOCX), Excel (XLS, XLSX), PowerPoint (PPT, PPTX) and plain text, each up to 100 MB; other types may go through but are not guaranteed to display correctly.

It is one member of the media message family, alongside images, video, audio and stickers, with its formats listed under media file limits. Like every free-form message it can be sent only inside an open customer service window. Outside the window, a document travels as the header of an approved template — typically a utility template such as an invoice or ticket confirmation — and is billed by that template's category.

Key takeaways

A document message delivers a file — usually a PDF — as a card the customer can open, save or forward, with a filename and an optional caption.
Officially supported types are PDF, DOC/DOCX, XLS/XLSX, PPT/PPTX and TXT, each up to 100 MB.
Send by uploaded media id (Meta's recommendation) or by public link, and set filename with its extension so the right icon shows.
As a free-form message it needs an open window; outside it, attach the file as the document header of an approved template.
Uploaded media IDs expire after 30 days, so upload close to sending and keep your own copy of every file.

04 · In code

A document message in code

1# 1. Upload the file (the media id is valid for 30 days)
2curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/media" \
3  -H "Authorization: Bearer {ACCESS_TOKEN}" \
4  -F "messaging_product=whatsapp" \
5  -F "type=application/pdf" \
6  -F "file=@GST-Invoice-ACS-20871.pdf;type=application/pdf"
7# → { "id": "1037543291543636" }
8 
9# 2. Send it inside an open customer service window
10curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \
11  -H "Authorization: Bearer {ACCESS_TOKEN}" \
12  -H "Content-Type: application/json" \
13  -d '{
14    "messaging_product": "whatsapp",
15    "recipient_type": "individual",
16    "to": "919812345678",
17    "type": "document",
18    "document": {
19      "id": "1037543291543636",
20      "filename": "GST-Invoice-ACS-20871.pdf",
21      "caption": "Your invoice for the AC service on 14 October. Keep it for warranty claims."
22    }
23  }'

05 · Mistakes to avoid

Common mistakes with a document message

Leaving out the filename
Without it the customer may see a generic name, and without the extension the wrong icon. Always send filename, ending in .pdf or the right extension.
Linking to private storage
A link must be publicly reachable when Meta fetches it. Signed URLs that expire in seconds or need cookies fail, so upload the file and send by id instead.
Reusing an old media ID
IDs from uploads expire after 30 days, and IDs received in webhooks after 7. Re-upload from your own archive rather than caching media IDs for months.
A free-form document after the window closed
A plain document message fails once 24 hours have passed since the customer's last message. Use a template with a document header, approved in advance.
Files phones cannot open
ZIP archives, unusual formats or 80 MB scans may not open on low-end phones. Stick to supported types and compress large PDFs.

06 · Key facts

A document message: key facts and limits

Message type: document
Supported types: PDF, DOC(X), XLS(X), PPT(X), TXT
Maximum size: 100 MB
Source: Uploaded media id (recommended) or public link
Uploaded media ID: Expires after 30 days
Filename: Optional; its extension sets the icon
Caption: Optional, with a length limit
Outside the window: Document header on an approved template

07Example: Invoices that stop getting lost in Nagpur

A Nagpur AC-servicing company used to email invoices that customers rarely opened, then spent time re-sending them for warranty claims. It moved to WhatsApp: after each visit, an approved utility template with a document header delivers GST-Invoice-ACS-20871.pdf with the line "Your invoice for today's service. Keep it for warranty claims." When a customer later asks in chat for last year's invoice, the agent — inside the window her question opened — sends it as a plain document message, fetched from the company's archive and uploaded again because the original media ID expired months ago.

08 · Why it matters

Why does a document message matter?

Many of the messages customers value most are documents: the tax invoice they need for reimbursement, the boarding pass at the gate, the lab report for their doctor. Delivering them on WhatsApp instead of email puts them where customers already look and keeps them findable in the chat's media tab. Getting the details right — a descriptive filename, the right template category, files that open on any phone — decides whether the document is used or turns into a support call.

09 · Pro tips

Best practices for a document message

Put the reference number in the filename; customers search their media tab by it.
Make the caption the instruction: "Show this at the gate" or "Keep for warranty claims".
Send invoices and tickets with a utility template's document header; that is the category transactional files belong to.
Check large files with a media size optimiser before sending them to customers on slow networks.

10Document Message FAQs

How do I send a PDF through the WhatsApp Business API?+

Upload it with POST /{PHONE_NUMBER_ID}/media to get a media ID, then send a message of type document with that id. Add a filename ending in .pdf and an optional caption; outside the window, use a template with a document header.

What is the maximum document size on the WhatsApp Business API?+

100 MB for supported document types: PDF, Word, Excel, PowerPoint and plain text. Other file types may be accepted but are not guaranteed to display correctly.

Can I send a document outside the 24-hour window?+

Only inside an approved template. A plain document message needs an open customer service window; a template with a document header can be sent at any time and is billed by its category.

Why does my document show the wrong name or icon?+

Because the filename is missing or has no extension. The WhatsApp client uses the extension to choose the icon, so set filename explicitly on every send.

Should I send a document by link or by media ID?+

By media ID where you can. Meta recommends uploading for better performance, while a link must stay publicly reachable as Meta fetches it; keep your own copy either way, because uploaded IDs expire after 30 days.

See InfiQ pricing

Document Message

How does a document message work?

Produce a phone-friendly file

Upload it

Name it for the customer

Pick the right vehicle

Confirm and keep records

02Try it

Send an invoice, then a copy on request

03What is a document message?

A document message in code

Common mistakes with a document message

Leaving out the filename

Linking to private storage

Reusing an old media ID

A free-form document after the window closed

Files phones cannot open