You use 4 different endpoints to manage your media:
Endpoint | Uses |
---|---|
Upload media. |
|
Retrieve the URL for a specific media. |
|
Delete a specific media. |
|
Download media from a media URL. |
See Supported Media Types for supported types and size limits.
To complete some of the following API calls, you need to have a media ID. There are two ways to get this ID:
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.
Endpoint | Authentication |
---|---|
(See Get Phone Number 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 |
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
.
curl -X POST 'https://graph.facebook.com/ v20.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"'
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.
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
.
Endpoint | Authentication |
---|---|
|
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 |
Name | Description |
---|---|
|
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. |
Sample request:
curl -X GET 'https://graph.facebook.com/ v20.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>" }
To delete media, make a DELETE
call to the ID of the media you want to delete.
Sample request:
curl -X DELETE 'https://graph.facebook.com/ v20.0
/<MEDIA_ID>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
Sample response:
{ "success": true }
Name | Description |
---|---|
|
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. |
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.
Endpoint | Authentication |
---|---|
|
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 |
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.
Audio Type | Extension | MIME Type | Max 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 Type | Extension | MIME Type | Max 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 |
|
|
application/pdf |
100 MB |
Image Type | Extension | MIME Type | Max Size |
---|---|---|---|
JPEG |
.jpeg |
image/jpeg |
5 MB |
PNG |
.png |
image/png |
5 MB |
WebP images can only be sent in sticker messages .
Sticker Type | Extension | MIME Type | Max Size |
---|---|---|---|
Animated sticker |
.webp |
image/webp |
500 KB |
Static sticker |
.webp |
image/webp |
100 KB |
Video Type | Extension | MIME Type | Max Size |
---|---|---|---|
3GPP |
.3gp |
video/3gp |
16 MB |
MP4 Video |
.mp4 |
video/mp4 |
16 MB |
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.