Now send Images, Videos, PDFs and other media content with the Twilio API for WhatsApp

February 19, 2019
Written by

Twilio API for WhatsApp : send Images, Videos, PDFs etc.
  • You can now send image, video, text and PDF files up to 5 mb in size over WhatsApp.
  • Sending a media message over WhatsApp is similar to sending an MMS — all you have to do is include the MediaUrl parameter in your API requests.
  • Media content is currently only supported in Session Messages. If the WhatsApp session with a user expires, you must wait for an inbound message to create a new session before you can send them a media message.

We’re thrilled to announce that you can now send and receive not just images and videos, but also PDFs, text files, and audio files using the Twilio API for WhatsApp. At Twilio, our mission is to enable developers and businesses to engage effectively with their customers on the messaging channels they prefer, and that means being able to use them for rich contextual conversations. Your customers increasingly want to communicate with you in the same way they do with their friends, family and co-workers, and the ability to exchange media such as image, audio, video and pdf files is central to that.

If you’ve used our MMS API before, sending a media message over WhatsApp will look very familiar to you. It’s very similar to sending an MMS — all you have to do is include the `MediaUrl` parameter in your API request to send a WhatsApp message, as shown below:

curl -X POST \
    --data-urlencode "To=whatsapp:+13105555555" \
    --data-urlencode "From=whatsapp:+12125551234" \
    --data-urlencode "Body=Thanks for contacting me on WhatsApp! Here is a picture of an owl." \
    --data-urlencode "MediaUrl=" \

Media support on WhatsApp can unlock a range of use cases. For example, airlines and movie theaters can now directly send boarding passes and tickets as PDFs to their customers, instead of sending a link to download the file. Customer support teams can ask customers to send a picture or short video of their problem, instead of requiring them to describe it in onerous detail. E-commerce companies can send a photo when packages are delivered to confirm delivery. You get the picture!

There are however a few differences between MMS and WhatsApp media messages. You can only send media messages to WhatsApp users if you have an active messaging ‘session’ with them. Messaging sessions are created when a user responds to a template message you send them, or starts a conversation by messaging your number on WhatsApp, and stay active for 24 hours after the last message they send you. WhatsApp media messages also do not support some file types that MMS does. You can read more about file type support in the FAQs.

We’re excited about continuing to enhance the Twilio API for WhatsApp, and can’t wait to see what you build!

Get started sending media messages with the Twilio API for WhatsApp