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 Request

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

Response

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/v21.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/v21.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

Audio

Audio TypeExtensionMIME TypeMax Size

AAC

.aac

audio/aac

16 MB

AMR

.amr

audio/amr

16 MB

MP3

.mp3

audio/mpeg

16 MB

MP4 Audio

.m4a

audio/mp4

16 MB

OGG Audio

.ogg

audio/ogg (OPUS codecs only; base audio/ogg not supported.)

16 MB

Document

Document TypeExtensionMIME TypeMax Size

Text

.txt

text/plain

100 MB

Microsoft Excel

.xls

application/vnd.ms-excel

100 MB

Microsoft Excel

.xlsx

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

100 MB

Microsoft Word

.doc

application/msword

100 MB

Microsoft Word

.docx

application/vnd.openxmlformats-officedocument.wordprocessingml.document

100 MB

Microsoft PowerPoint

.ppt

application/vnd.ms-powerpoint

100 MB

Microsoft PowerPoint

.pptx

application/vnd.openxmlformats-officedocument.presentationml.presentation

100 MB

PDF

.pdf

application/pdf

100 MB

Image

Images must be 8-bit, RGB or RGBA.

Image TypeExtensionMIME TypeMax Size

JPEG

.jpeg

image/jpeg

5 MB

PNG

.png

image/png

5 MB

Sticker

WebP images can only be sent in sticker messages.

Sticker TypeExtensionMIME TypeMax Size

Animated sticker

.webp

image/webp

500 KB

Static sticker

.webp

image/webp

100 KB

Video

Only H.264 video codec and AAC audio codec supported. Single audio stream or no audio stream only.

Video TypeExtensionMIME TypeMax Size

3GPP

.3gp

video/3gp

16 MB

MP4 Video

.mp4

video/mp4

16 MB

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.