Media

To use media in messages, the media file must be uploaded to the media endpoint. Once the upload is complete, you can send a message by referring to the media ID.

When a media message is sent, the media is stored on the WhatsApp servers for 7 days. If a user makes a request to download the media after 7 days, the WhatsApp servers will request the same media file from the WhatsApp Business API client. If the media has been removed, the user will be notified that the media is unavailable. It is not safe to assume the media was downloaded simply based on the delivered and read receipts. Outgoing media is generally safe to be removed past 30 days, but you should employ a strategy that best suits your business.

note

If you are having trouble uploading your image it may be because of hidden attributes in your image file. We recommend using imagecompressor.com to clear your image of these attributes and then trying again.

Uploading Media

$ curl -X POST https://whatsapp.turn.io/v1/media \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: image/jpeg' \
    --data-binary @your-file-path

> {
    "media": [
        {
            "id": "f043afd0-f0ae-4b9c-ab3d-696fb4c8cd68"
        }
    ]
}

To upload media to the WhatsApp Business API client, use the media endpoint. The POST body must contain the binary media data and the Content-Type header must be set to the type of the media being uploaded. See the Supported File Types section for information about supported file types.

caution

WhatsApp processes the media that is uploaded. While the maximum file size for media that can be uploaded to the media node is 64MB, there are post-processing limits for the various media types outlined in the Post-Processing Media Size table below.

A successful response returns the id field, which is the information you need for retrieving messages and sending a media message to your customers.

Supported File Types

Media	Supported Types
audio	audio/aac, audio/mp4, audio/mpeg, audio/amr, audio/ogg (only opus codecs, base audio/ogg is not supported)
document	text/plain, application/pdf, application/vnd.ms-powerpoint, application/msword, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
image	image/jpeg, image/png. Images must be 8-bit, RGB or RGBA.
sticker	image/webp
video	video/mp4, video/3gp. Only H.264 video codec and AAC audio codec is supported. Videos with a single audio stream or no audio stream are supported.

caution

Please ensure that you are using only the supported content types listed above since Turn only guarantees the sending and receiving of these content types.

Post-Processing Media Size

The following are the post-processing size limits imposed by WhatsApp on the various media types. WhatsApp won't deliver messages with media files with a post-processing size larger than the limits outlined below.

Media Type	Size
audio	16 MB
document	100 MB
image	5 MB
sticker animated	500 KB
sticker static	100 KB
video	16 MB

Stickers

Stickers must have a transparent background, be exactly 512 x 512 pixels, and be less than 100 KB in size. As indicated in the Supported File Types table, only webp format files are accepted. Other file types can be transformed into webp online by using a file conversion site such as cloudconvert.

Retrieving Media

$ curl -X GET https://whatsapp.turn.io/v1/media/the-media-id

After you have successfully completed Uploading Media, you will receive a response containing a media ID. You will use that ID in the request to retrieve the media stored in the WhatsApp Business API client.

Retrieving media is particularly useful when a user has uploaded an image that is sent to your Webhook. When a message with media is received, the WhatsApp Business API client will download the media. Once the media is downloaded, you will receive a notification through your webhook. Use the media ID found in that notification to retrieve the media.

Deleting Media

To delete media in the WhatsApp Business API client, you will send a DELETE request to the media node along with the ID of the media that you want to delete. You will use the ID from the response to the Uploading Media or Media Message from a Webhook request.

$ curl -X DELETE https://whatsapp.turn.io/v1/media/the-media-id