Sending and Receiving Media with WhatsApp Messaging on Twilio (Beta)

The Twilio for WhatsApp API supports sending and receiving media messages with WhatsApp users. The API works exactly like sending MMS messages with Twilio, however there are some rules and restrictions that are unique to WhatsApp.

Usage Example

To send a media message with WhatsApp, include the MediaUrl parameter with your HTTP POST request. This is exactly like sending an MMS message with Twilio Programmable SMS.

Here’s an example cURL script:

curl -XPOST \
  --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=" \

This example will contact the WhatsApp destination (310) 555-5555 from the sender (212) 555-1234 via the WhatsApp app, and includes the image owl.png, and the following message:

Thanks for contacting me on WhatsApp! Here is a picture of an owl.

To make this script work for you, make the following updates, and then paste it into a terminal window:

  • Line 1 update with your Account SID.
  • Line 2 update with a valid destination.
  • Line 3 update with a valid WhatsApp sender number.
  • Line 4 update with your desired message.
    • Note: A free-form message like this is only possible during a 24 hour user-initiated session. Unprompted messages have template requirements. For more information, see the Rules and Limitations section below.
  • Line 5 update with a valid media file url.
  • Line 6 update with your Account SID and Auth Token.

For full details, including sample code from our Helper Library SDKs, please see Twilio API for WhatsApp (Twilio Docs).

Rules and Limitations

You can send media messages to any WhatsApp user who has sent you a message within the past 24 hours.

If a user has not sent a message to your WhatsApp number within the past 24 hours, you cannot send them a media message through WhatsApp. This means media files are not allowed in pre-approved templates.

This is because WhatsApp only allows sending media on session messages. WhatsApp divides outgoing messages into two categories: template messages and session messages. Template messages are the initial messages you send to users, and must follow a pre-approved template cleared by WhatsApp. Once a user starts a “session” by sending you a message, you can exchange free-form messages with them for 24 hours. For more detail, please see Rules and Best Practices for WhatsApp Messaging on Twilio.

Supported File Types

The Twilio API for WhatsApp supports sending and receiving images, audio, and PDF files. The following formats are currently supported:

Audio MP3, OGG, AMR
Documents PDF
Video MP4

You can send media messages up to 5 MB in size. At this time, Twilio will not transcode media for outgoing WhatsApp messages, so if you need to send a media object that is larger than 5 MB, please reduce the file size before sending it to Twilio.


If a WhatsApp media message was not delivered, there are a few likely explanations:

  • The media message was not sent during an active session with the user (see Rules and Limitations above).
  • Twilio encountered an error when trying to get your media.
  • Your message including media is larger than 5 MB.
  • The content-type headers of your media attachment do not match the file extension (for example, content-type is image/jpg but file extension is .png).


Adding a media attachment to a message does not affect the message price. Media messages have the same pricing as a standard Session message to the same destination country. For more information, see Twilio API for WhatsApp pricing.

Related Topics

Have more questions? Submit a request
Powered by Zendesk