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 — or reference the file from a journey — using the returned media ID.

When you upload a file, Turn.io stores the binary in its own permanent storage and uploads a copy to WhatsApp's media cache. The returned id is a durable reference: you can keep using it indefinitely, including in journeys (e.g. document(id, filename: "...")). WhatsApp's own media cache only retains files for ~30 days, but Turn.io re-uploads from permanent storage transparently when the cache expires, so you don't have to manage that yourself.

This means uploading a PDF via this endpoint is equivalent to dragging the same PDF into a Document card in the journey canvas — both produce a permanently referenceable media ID backed by the same storage.

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.

Using media in journeys

The id returned from a media upload can be used directly in journey DSL functions, in place of a public URL:

card SendTerms do
    document("f043afd0-f0ae-4b9c-ab3d-696fb4c8cd68", filename: "Terms.pdf")
    text("Please review the attached terms.")
end

The same applies to image(id), video(id), and audio(id).

This is useful when migrating journeys from another platform: upload your PDFs, images, and other media via this endpoint, then reference them by ID in the DSL rather than self-hosting them at a public URL. The media will be delivered from Turn.io's permanent storage for the lifetime of the journey.

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.io 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

Uploading Media​

Using media in journeys​

Supported File Types​

Post-Processing Media Size​

Stickers​

Retrieving Media​

Deleting Media​