Media

/v1/media

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

Media is handled differently by WhatsApp compared to the rest of Facebook. The file must be uploaded to the media volume. Once the upload is complete, you can send a message using the media ID.

There is no support for sending media by URL or byte streams.

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.

This document covers:

Uploading Media

To upload media to the WhatsApp Business API client, use the media node. 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. Note: The maximum file size for uploaded media is 64MB.

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.

Request

Uploading media:

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

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

Response

A successful response returns the id field, which is the information you need for retrieving messages and 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 File Types

Media Supported File Types

document

PDF, DOC(X), PPT(X), XLS(X)

image

JPG, JPEG, PNG

audio

AAC, M4A, AMR, MP3, OGG, OPUS

Retrieving Media

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.

You can enable the WhatsApp Business API client to auto-download media with the Auto-download Media Settings.

Request

GET /v1/media/media-id

For example, using the example image uploaded in the previous section:

curl -X GET \
  https://your-webapp-hostname:your-webapp-port/v1/media/4b5bf27b-8672-4d55-bc21-d096dc200d0f \
  -H 'Authorization: Bearer your-auth-token' 

To send this example media to a file, use the -o parameter, as shown below:

curl -X GET \
  https://your-webapp-hostname:your-webapp-port/v1/media/4b5bf27b-8672-4d55-bc21-d096dc200d0f \
  -H 'Authorization: Bearer your-auth-token' \
  -o path/filename

Response

If successful, you will see a response containing a 200 OK status and the binary data you uploaded.

Content-Type: image/jpeg or other appropriate media type
Content-Length: content-size

binary-media-data

If you used a tool like Postman, you will see the image that was uploaded. If you are using a command line tool, you will see the binary data that was uploaded. If you sent the data to a file, you will see the image in your file browser.

If the media is not found, a 404 Not Found response code is returned with no body.

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

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.

Request

DELETE /v1/media/media-id

Response

A successful response will show 200 OK and either null or {}. If the media is not found, the response will show 404 Not Found and contain no body.

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

Media storage needs to be handled by the business. If the media volume gets full, message sending will start to fail.