Delivering visually engaging content is essential to improve conversion rates on the WhatsApp Business Platform. While text updates work for basic alerts, B2B sales networks need to send media like PDF invoices, product images, and video tutorials.

The WhatsApp Business API supports **Media Messages** in headers and session replies. This developer guide outlines file size limits, details POST requests for media uploads, and provides templates to send media objects programmatically.

Key Takeaways

  • Media messaging supports file formats including PDF, JPG, PNG, MP4, and 3GP.
  • Outbound templates can include dynamic media headers (images, documents, videos).
  • Uploading media requires a two-step process: upload to Meta's servers, then pass the file ID in messaging requests.
  • Strict size limits apply (e.g. up to 100MB for documents, 5MB for images).

Table of Contents

1. Supported Media Formats & Limits

Meta enforces file size constraints to optimize mobile delivery speed:

  • Images (PNG/JPEG): Maximum size limit of 5MB.
  • Documents (PDF): Maximum size limit of 100MB.
  • Video (MP4): Maximum size limit of 16MB.

Using compressed files is recommended. Learn more on our WhatsApp Automation page.

2. Uploading Media to Meta's Servers

To send files, first POST the file binary to Meta's media endpoint to retrieve a unique `id` variable. This `id` is passed in subsequent messaging payloads.

Manage team support inbox settings on our Shared Team Inbox page.

3. Programming Media Message Payloads

Once you have a file ID, send it in your messaging requests. Here is an example JSON payload to send a PDF document:


{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "917257073570",
  "type": "document",
  "document": {
    "id": "4b92c81a-7b39-479d-bf02-4a5f585be2ed",
    "caption": "Your Invoice for Order #1092",
    "filename": "invoice_1092.pdf"
  }
}

Review template settings on our WhatsApp Template Directory.

4. Configuring Dynamic Media Headers

You can define templates with media headers. When calling the template API, pass the dynamic image or document URL to render headers on devices. Review configurations on our WhatsApp Chatbot Builder page.

5. Best Practices for Media Storage

Cache Meta file IDs on your backend database to avoid uploading duplicate assets, reducing bandwidth. For details on virtual numbers, check our Partnership & Onboarding Portal. Learn about plans on our Pricing Details page.

Frequently Asked Questions (FAQs)

Q1: What media formats are supported by the WhatsApp API?

A: The API supports images (JPEG, PNG), documents (PDF, DOCX), audio (AAC, MP3), and video (MP4).

Q2: What is the maximum file size for PDF documents?

A: Meta allows sending PDF documents up to 100MB in size, though smaller files deliver faster.

Q3: How long do uploaded media files remain on Meta's servers?

A: Uploaded media files expire and are deleted from Meta's cache after 30 days.

Q4: Can we send dynamic images in template headers?

A: Yes. You can register templates with image headers, passing different image URLs for each recipient.

Q5: What is the cost category for media messages?

A: Sending media messages triggers standard conversation sessions, billed based on category (Marketing or Utility).

Q6: Do we need a developer to send media templates?

A: No. You can upload files and schedule media broadcasts using the Text World marketing panel code-free.

Q7: What is the benefit of sending brochures via WhatsApp?

A: Delivering catalogs directly to chats achieves higher engagement rates compared to email links.

Q8: How do we prevent media download failures?

A: Host source media files on secure, high-bandwidth HTTPS servers to ensure Meta can fetch files successfully.

Q9: Can we receive voice notes from customers?

A: Yes. Incoming voice notes trigger webhook notifications containing media IDs, which you download to listen.

Q10: What is the benefit of the green tick verification for media?

A: The green badge displays your brand name in header views, giving customers confidence to download attachments safely.

Q11: Can we test media messages in sandbox?

A: Yes. The developer sandbox allows you to upload and deliver test images and documents to whitelisted numbers.

Q12: Can we register landlines to deliver media messages?

A: Yes. Landline registered numbers have the same media messaging capabilities as standard mobile lines.

Q13: What happens to media sent to offline users?

A: Meta buffers media messages on their servers, delivering files once the user's device comes online.

Q14: Are virtual numbers allowed to send video messages?

A: Yes. All registered API numbers support the same media formats and size limits.

Q15: Can we run automated NPS surveys with media?

A: Yes. You can attach quick-reply buttons to image or video templates to collect customer ratings visually.

Next Steps

Integrating media messages like PDFs and images inside templates improves visual appeal. Adhering to Meta's size limits prevents transmission drop errors.

Ready to deploy media templates? Connect with our developer integration team to start planning your setup today.