Media

You use 4 different endpoints to manage your media:

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.

Parameters

Example

Sample request:

curl -X POST 'https://graph.facebook.com/v18.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>"
}

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.

Parameters

Example

Sample request:

curl -X GET 'https://graph.facebook.com/v18.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/v18.0/<MEDIA_ID>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

Sample response:

{
  "success": true
}

Parameters

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.

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

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.