Media

You use 4 different endpoints to manage your media:

EndpointUses

POST /PHONE_NUMBER_ID/media

Upload media.

GET /MEDIA_ID

Retrieve the URL for a specific media.

DELETE /MEDIA_ID

Delete a specific media.

GET /MEDIA_URL

Download media from a media URL.

See Supported Media Types for supported types and size limits.

Get Media ID

To complete some of the following API calls, you need to have a media ID. There are two ways to get this ID:

  1. From the API call: Once you have successfully uploaded media files to the API, the media ID is included in the response to your call.
  2. From Webhooks: When a business account receives a media message, it downloads the media and uploads it to the Cloud API automatically. That event triggers the Webhooks and sends you a notification that includes the media ID.

Upload Media

To upload media, make a POST call to /PHONE_NUMBER_ID/media and include the parameters listed below. All media files sent through this endpoint are encrypted and persist for 30 days, unless they are deleted earlier.

EndpointAuthentication

/PHONE_NUMBER_ID/media

Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup.


Solution Partners must authenticate themselves with an access token with the whatsapp_business_messaging permission.

Parameters

NameDescription (Click the arrow in the left column for supported options.)

file

Required.

Path to the file stored in your local directory. For example: "@/local/path/file.jpg".

type

Required.

Type of media file being uploaded. See Supported Media Types for more information.

Supported Options

Supported options for images are:

  • image/jpeg
  • image/png

Supported options for documents are:

  • 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

Supported options for audio are:

  • audio/aac
  • audio/mp4
  • audio/mpeg
  • audio/amr
  • audio/ogg
  • audio/opus

Supported options for video are:

  • video/mp4
  • video/3gp

Supported options for stickers are:

  • image/webp

messaging_product

Required.

Messaging service used for the request. In this case, use whatsapp.

Example

Sample request:

curl -X POST 'https://graph.facebook.com/v19.0/<MEDIA_ID>/media' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-F 'file=@"2jC60Vdjn/cross-trainers-summer-sale.jpg"' \
-F 'type="image/jpeg"' \
-F 'messaging_product="whatsapp"'

A successful response returns an object with the uploaded media's ID:

{
  "id":"<MEDIA_ID>"
}

All API calls require authentication with access tokens.

Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup.

Solution Partners must authenticate themselves with an access token with the whatsapp_business_messaging and whatsapp_business_management permissions. See System User Access Tokens for information.

Retrieve Media URL

To retrieve your media’s URL, send a GET request to /MEDIA_ID. Use the returned URL to download the media file. Note that clicking this URL (i.e. performing a generic GET) will not return the media; you must include an access token. See Download Media.

EndpointAuthentication

/MEDIA_ID

Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup.


Solution Partners must authenticate themselves with an access token with the whatsapp_business_messaging permission.

Parameters

NameDescription

phone_number_id

Optional.

Business phone number ID. If included, the operation will only be processed if the ID matches the ID of the business phone number that the media was uploaded on.

Example

Sample request:

curl -X GET 'https://graph.facebook.com/v19.0/<MEDIA_ID>/' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

A successful response includes an object with a media url. The URL is only valid for 5 minutes. To use this URL, see Download Media.

{
  "messaging_product": "whatsapp",
  "url": "<URL>",
  "mime_type": "<MIME_TYPE>",
  "sha256": "<HASH>",
  "file_size": "<FILE_SIZE>",
  "id": "<MEDIA_ID>"
}

Delete Media

To delete media, make a DELETE call to the ID of the media you want to delete.

Example

Sample request:

curl -X DELETE 'https://graph.facebook.com/v19.0/<MEDIA_ID>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

Sample response:

{
  "success": true
}

Parameters

NameDescription

phone_number_id

Optional.

Business phone number ID. If included, the operation will only be processed if the ID matches the ID of the business phone number that the media was uploaded on.

Download Media

To download media, make a GET call to your media’s URL. All media URLs expire after 5 minutes —you need to retrieve the media URL again if it expires. If you directly click on the URL you get from a /MEDIA_ID GET call, you get an access error.

EndpointAuthentication

/MEDIA_ID

Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup.


Solution Partners must authenticate themselves with an access token with the whatsapp_business_messaging permission.

Example

Sample request:

curl  \
 'URL' \
 -H 'Authorization: Bearer ACCESS_TOKEN' > media_file

If successful, you will receive the binary data of media saved in media_file, response headers contain a content-type header to indicate the mime type of returned data. Check supported media types for more information.

If media fails to download, you will receive a 404 Not Found response code. In that case, we recommend you try to retrieve a new media URL and download it again. If doing so doesn't resolve the issue, please try to renew the ACCESS_TOKEN then retry downloading the media.

Supported Media Types

MediaSupported TypesSize Limit

audio

audio/aac, audio/mp4, audio/mpeg, audio/amr, audio/ogg (only opus codecs, base audio/ogg is not supported)

16MB

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

100MB

image

image/jpeg, image/png


Images must be 8-bit, RGB or RGBA

5MB

video

video/mp4, video/3gp


Notes:

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

16MB

sticker

image/webp

Static stickers: 100KB


Animated stickers: 500KB

Media message download constraints

The maximum supported file size for media messages on Cloud API is 100MB. In the event the customer sends a file that is greater than 100MB, you will receive a webhook with error code 131052 and title:

"Media file size too big. Max file size we currently support: 100MB. Please communicate with your customer to send a media file that is smaller than 100MB"_.

We advise that you send customers a warning message that their media file exceeds the maximum file size when this webhook event is triggered.