Media management

Let us consider we have a template that requires an image in the header. We could provide this image by specifying a Url in the media header, or we could upload this image to Meta and provide the reference Id in the media header. Meta prefers using uploaded media as it is more reliable and less prone to external issues such as slow servers and DNS resolution problems.

This document describes how to upload, download and delete media.

Note that we do not store your media. All media is stored by Meta and we simply act as a middleman between yourself and Meta. It is also important that you keep a handle to any media that you have uploaded. We explicitly do not let you list your media as we expect you to keep track of what you have uploaded.

mediaId's

The media API endpoint manages your media using a mediaId which is returned when uploading your media or by webhooks. mediaId's returned by the API expire after 30 days. mediaId's returned by webhooks expire after 7 days.

Media from webhooks

If a handset sends a message that contains media, the media Id will be sent to you in a webhook.

Upload media

To upload media, make a POST request to whatsapp/v1/media with a multi-part body including a BusinessPhoneNumberId and the file binary data. All media files sent through this endpoint are persisted on Meta's servers for 30 days, unless they are deleted earlier.

Get media

You can query the whatsapp/v1/media/MEDIA_ID endpoint to get a media URL, which will provide you a link to download the media. You will also be provided with the status of the media (whether or not it has expired), and an expiry date.

Delete media

Make a DELETE request to whatsapp/v1/media including the BusinessPhoneNumberId and the mediaId in the body to delete your media asset.

Download media

To download media, make a GET request to whatsapp/v1/media/MEDIA_ID/download. Upon success the API will respond with the binary data of the media asset.

Document headers and filenames

filename is only applicable when the header type is a Document. It is ignored for Image and Video headers. The filename should include the correct file extension (for example .pdf, .docx, .xlsx) so WhatsApp can correctly identify and display the document.

A mismatched or missing extension can cause WhatsApp to display the document incorrectly or to reject it.

{
    "Parameters": {
        "Header": {
            "Media": {
                 "type": "document",
                 "url": "https://...",
                 "filename": "payment.docx"   
            }
        }
    }
}

Media types

Meta allows uploading various media types.

Audio

Document

Image

Images must be 8-bit, RGB or RGBA.

Sticker

WebP images can only be sent in sticker messages.

Video