Objective

The Twilio for WhatsApp API supports sending and receiving media messages with WhatsApp users.

The way you send media on WhatsApp depends on if the message is being sent within a customer service window or not. This article explains how to send media using WhatsApp and the limitations involved.

Product

Programmable Messaging

Procedure

Sending media outside of the customer service window

WhatsApp allows media to be sent outside of a customer service window as long as it is part of an approved template. You can create WhatsApp templates using Content Templates and media is supported in a number of different content types. See here for more information on the available content types. 

Note that the supported file types for media in a template are not as extensive as those for free-form messages. You can use the following file types in media templates:

• application/pdf
• image/jpeg
• image/jpg
• image/png
• video/mp4

WhatsApp classifies approved templates into 1 of 3 types of media headers (Image, Video, Document) based on the sample that was submitted. Once the content template has been approved another type of media header can't be sent using the template. For example, if a content template is approved with an image, a video cannot be sent using the same content template.

Sending media in a free-form WhatsApp message

To send a free-form 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. Please note that, unlike MMS, a WhatsApp media message can only contain one media attachment. Any additional attachments will be ignored.

Here’s an example cURL script:

curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json \
  --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=https://demo.twilio.com/owl.png" \
  -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

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.
  • Unless your Twilio number has been enabled for WhatsApp in production, use your WhatsApp Sandbox number for sending messages.
• Line 4 update with your desired message.
  • Note: A free-form message like this is only possible during a 24 hour customer service window.
• 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).

Supported File Types

The Twilio API for WhatsApp supports sending and receiving the following media formats:

Template messages

Free-form messages

*The image/webp MIME type is only used for WhatsApp stickers, which have additional requirements. See the section "WhatsApp Stickers" below for more details.

**WhatsApp outbound OGG is only supported when the ogg file uses the opus audio codec. These files may have the .ogg or the .opus extension.

The following size restrictions apply to WhatsApp media messages:

• Audio, Video and Document media messages up to 16 MB.
• Stickers up to 100KB.
• Images up to 5MB.

A free-form WhatsApp media message can only contain one media object. Additional MediaUrl parameters will be ignored. 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 the limit for that media type, please reduce the file size before sending it to Twilio.

Notice: MP4 video files which do not include an audio track (silent videos) may fail with error 63005, due to a bug in WhatsApp. This issue persists as of June 2020. To work around this issue, please add an audio track (with AAC codec) to any MP4 video sent via WhatsApp. The audio track can contain silence.

Please note that the Twilio API for WhatsApp does not support including a text body ("caption") in the same free-form message as a webp image, video, audio file, document, contact (vCard), or location. If you pass the Body parameter on a message with one of these media types, the body will be ignored and not delivered to the device.

If you would like to include text within a WhatsApp media message, you can utilize the following Content Template types:

• twilio/media
• twilio/carousel
• twilio/catalog
• twilio/flows
• whatsapp/card

Sending WhatsApp "Voice Notes" (audio play button appears in-app)

WhatsApp mobile users have the ability to record and send "Voice Notes" by holding a microphone button in the app. These appear as an audio message with a play button, rather than a downloadable file.

Businesses using the Twilio API for WhatsApp can send a Voice Note by using the OGG file format (with the opus audio codec – see above).

Only OGG files are natively playable in the WhatsApp app. Other audio formats supported by WhatsApp, such as MP3 files, will appear as a downloadable file in the app.

File Name Behavior on WhatsApp Media Messages

Outbound WhatsApp messages with media: Outbound media messages will generally have the media filename preserved. However, if you send a video file, WhatsApp may rename the file to "WhatsApp Video [timestamp]", which is the WhatsApp application's default behavior.

Inbound WhatsApp messages with media: The media filename as sent by the user is shown in the message body. The actual filename associated with the media object will be a random string.

WhatsApp Stickers

WhatsApp Stickers are large, colorful emojis in webp format. To send a sticker on the WhatsApp Business API with Twilio, it must fulfil the following requirements:

• Stickers must have a transparent background.
• Stickers must be exactly 512x512 pixels.
• Stickers must be less than 100 KB.
• Stickers must be static - animated stickers are not supported.

Message bodies are not supported when sending stickers. Any message body included in a request with a sticker will be ignored.

Troubleshooting

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/was not sent with an approved media template (see Rules and Limitations above).
• Twilio encountered an error when trying to get your media.
• Your message, including media, is larger than the limit for that file type.
• 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).

If you included a message body with your WhatsApp media message, and only the media was delivered to the user, please note that this is expected when sending an audio, contact, or location message. To deliver a text message as well as one of these media types, please send two separate messages.

Pricing

Adding a media attachment to a message does not affect the message price. For more information, see Twilio API for WhatsApp pricing.