We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.

Media

/v1/media

Use the media node to upload, retrieve, or delete media.

Edges

The following edges are connected to this node:

EdgeDescription

/{media-id}

Use this edge to retrieve and delete media.

Before You Start

When a media message is sent, the media is stored on the WhatsApp servers for 14 days. If a user makes a request to download the media after 14 days, the WhatsApp servers will request the same media file from the WhatsApp Business on-premises 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.

Constraints

  • If you use the media upload process rather than linking to a media URL, the file must be uploaded to the media volume. Once the upload is complete, you can send a message using the media ID.
  • The application processes the media that is uploaded before it's sent to the server. While the maximum file size for media that can be uploaded to the media node is 100MB, there are post-processing limits for the various media types outlined in the Post-Processing Media Size table below.
  • Media storage needs to be handled by the business. If the media volume gets full, message sending will start to fail.
  • There is no support for:
    • Sending media by byte streams.
    • Sending messages with animated stickers.

Uploading

Make a POST request to /v1/media to upload your media. The body of the on-premises request 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 Content-Types section for supported options.

Sending binary data in a POST HTTP request is a standard way of uploading binary data. If you want to upload an image, for example, you issue a POST request with the actual image bytes in the payload. Alternatively, you can use --data-binary if you want cURL to read and use the given file in binary exactly as given.

Example

Uploading media:

POST /v1/media
Content-Type: image/jpeg or other appropriate media type

your-binary-media-data

Uploading media with cURL:

curl -X POST \
https://your-webapp-hostname:your-webapp-port/v1/media \
-H 'Authorization: Bearer your-auth-token' \ 
-H 'Content-Type: image/jpeg'  \ # or other appropriate media type
--data-binary @your-file-path

In both cases, a successful response returns the id field, which you need for retrieving media or sending a media message to your customers.

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

If you receive an error message, see Error and Status Messages for more information.

Supported Content-Types

Media Supported Content-Types

audio

audio/aac, audio/mp4, audio/amr, audio/mpeg,
audio/ogg; codecs=opus


Note: For ogg/opus, only single channel audio files are supported by WA clients.

document

Any valid MIME-type.

image

image/jpeg, image/png


Currently, we don't support images with transparent backgrounds.

sticker

image/webp

video

video/mp4, video/3gpp


Notes:

  • Only H.264 video codec and AAC audio codec is supported.
  • We support videos with single audio stream or no audio stream.

Post-Processing Media Size

This is the maximum allowed size of the media file after compression and encryption.

Media Type Size

audio

16 MB

document

100 MB

image

5 MB

sticker

100 KB

video

16 MB

FAQ

For images, the caption will be added as description. The caption text appears in full length for images on both Android and iPhone.

For documents, the caption replaces the filename. It is not meant to be displayed on the user's device as description text but instead to show the name of the file. iPhones show the full text while Androids truncate the filename; this is technical limitation of the current implementation of WhatsApp on both devices.

It is up to you when to delete media.

After uploading media, you will receive a media ID, which you can use to send a message that includes the uploaded media element. Upon sending the media message, the WhatsApp Business API will encrypt and upload the media to WhatsApp servers where it will remain for a period of 14 days. After that, you can decide to delete the media by providing the media ID or to keep it for later use. While we recommend keeping the media for 30 days, it is up to you to decide the retention policy based on your business's policy or use-case.

There is no cleanup mechanism for either outgoing nor incoming media files. You may delete your media files manually by locating them on your file system.

To find the mountpoint of your media volume, you can run a docker command.

Request

docker volume inspect whatsappMedia

Response

[
    {
        "Driver": "local",
        "Labels": {},
        "Mountpoint": "/var/lib/docker/volumes/whatsappMedia/_data",
        "Name": "whatsappMedia",
        "Options": {},
        "Scope": "local"
    }
]

Then, to see all your incoming media files you can run the ls command with the received Mountpoint file path:

ls /var/lib/docker/volumes/whatsappMedia/_data/

For AWS setup, the media volume is mounted to /mnt/wa/media path on the host.

When sending image as an album from the WhatsApp Business API, you will need to send at least 4 images in succession. If the user's conversation view is currently active when the images are received, then the album view is unavailable until the next visit.

An album will not be created if any of the following criteria are met:

  1. Images with captions
  2. Unread divider - user sees some images, but not the rest
  3. Date header - new day between deliveries

No, currently we have to use AWS EFS to share the media volume between the Coreapp and Webapp.

The maximum file upload size is 64 MB, which means this limit also applies to any image, document, or video you send with a message.