# Upload, retrieve or delete media

### Media Endpoints <a href="#media-endpoints" id="media-endpoints"></a>

You use 4 different endpoints to manage your media:

<table data-header-hidden><thead><tr><th width="391.9874267578125">Endpoints</th></tr></thead><tbody><tr><td><a href="https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/media-uploads#post-media">Upload media</a>.</td></tr><tr><td><a href="https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/media#get-media_id">Retrieve the Meta URL for a specific media</a>.</td></tr><tr><td><a href="https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/media#get-whatsapp_business-attachments">Download media from a media URL.</a></td></tr><tr><td><a href="https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/media#delete-media_id">Delete media</a></td></tr></tbody></table>

## Constraints

* **Media Uploads** (`POST /media`): A limit of 25 requests per second (RPS) per phone number.
* **Media Retrieval** (`GET /<media_id>`): While there is no fixed RPS for successful retrievals, an error-based throttle is in place:
  * **Error Threshold:** 20 error responses within a 60-minute window.
  * **Penalty:** If this threshold is exceeded, requests to this endpoint will be blocked for 30 minutes.

{% hint style="info" %}
**Note:** Error-based throttling applies only to `GET` requests and does not affect the `POST /media` endpoint.
{% endhint %}

* If you use the media upload process rather than linking to a media URL, the file **must** be uploaded to the media volume. Once the upload is complete, you can send a message using the media ID.
* 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 an error.&#x20;
* There are various size limits for media types outlined in the Supported Media Types table.
* Meta's image processor utilizes Exchangeable Image File Format (EXIF) tags (for example: `Orientation`, which rotates images), if present in media files. Please ensure that your EXIF tag values are correctly configured. <https://exiftool.org/TagNames/EXIF.html>

{% hint style="warning" %}
**All images** sent via the WhatsApp platform (Cloud API) are *automatically re-encoded and optimized* for network efficiency. This process results in the conversion of PNGs to JPEG and a significant reduction in file size (approx. 70-80%), which may lead to visible compression artifacts.

For more details on how to prepare your assets and minimize quality loss, see our [Image Processing and Optimization Guide](https://docs.360dialog.com/partner/messaging/media-messages/image-processing-and-optimization).
{% endhint %}

### Upload Media <a href="#upload-media" id="upload-media"></a>

Please use this [endpoint](https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/media-uploads#post-media).&#x20;

All media files sent through this endpoint are encrypted and stored for 30 days after last use, unless deleted earlier.

## Get Media URL

Please use this [endpoint](https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/media#get-media_id).

The API will return a **URL** pointing to where the media is stored. The URL will begin with `https://lookaside.fbsbx.com` (Facebook’s CDN host)

## Download Media

Please use this [endpoint](https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/media#get-whatsapp_business-attachments).

You can use the returned URL from the previous step to download the media file.

* Replace the root hostname `https://lookaside.fbsbx.com`  (Facebook’s CDN host) with `https://waba-v2.360dialog.io`
* Append the endpoint and query string parameters `\/whatsapp_business\/attachments\/?mid=130345565692730173924&source=getMedia&ext=1664537344507&hash=ATtBt0Cdio`&#x20;
* Remove 3 backslashes `\` from the URL

Please note that this link is confidential and must be treated as sensitive information. The link will only remain valid **for 5 minutes**.

{% hint style="info" %}
Depending on your `cURL` version you may receive a `BINARY` response instead of the expected `JSON`. In this case please add the `--compressed` flag to your cURL query.

* In case you receive *`308 Permanent Redirect`* errors using cURL, please use the\
  `--location` [option](https://curl.se/docs/manpage.html#-L) to follow redirects.
  {% endhint %}

## Direct Media download

Incoming media message webhooks (such as image or video messages) now include the media download URL. Having this URL allows the direct download of the media file, skipping the Get Media URL step. This significantly improves and eases media handling.To download the media, retrieve the URL from the webhook and call the following [endpoint](https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/media#get-whatsapp_business-attachments).

It is important to highlight that media retrieved directly from the webhook are available for **7 days**, instead of the standard 30 days associated with uploaded media.

## Delete Media&#x20;

Please use this [endpoint](https://app.gitbook.com/s/-M4sMxKjL6eJRvZn6jeG-887967055/messaging-api/api-reference/media#delete-media_id).

## Supported Media Types <a href="#supported-media-types" id="supported-media-types"></a>

<table><thead><tr><th width="164">Media</th><th width="479">Supported Types</th><th>Size Limit</th></tr></thead><tbody><tr><td>audio</td><td><code>audio/aac .acc</code>,  <code>audio/amr .amr</code>,  <code>audio/mpeg .mp3</code>, <code>audio/mp4 .m4a</code>, <code>audio/ogg</code> (only <code>opus codecs</code>, base <code>audio/ogg</code> is not supported)</td><td>16MB</td></tr><tr><td>document</td><td><code>text/plain</code>, <code>application/pdf</code>, <code>application/vnd.ms-powerpoint</code>, <code>application/msword</code>, <code>application/vnd.ms-excel</code>, <code>application/vnd.openxmlformats-officedocument.wordprocessingml.document</code>, <code>application/vnd.openxmlformats-officedocument.presentationml.presentation</code>, <code>application/vnd.openxmlformats-officedocument.spreadsheetml.sheet</code></td><td>100MB</td></tr><tr><td>image</td><td><p><code>image/jpeg</code>, <code>image/png</code></p><p><br></p><p>Images must be 8-bit, RGB or RGBA</p></td><td>5MB</td></tr><tr><td>video</td><td><p><code>video/mp4</code>, <code>video/3gp</code></p><p><br></p><p>Notes:</p><ul><li>Only H.264 video codec and AAC audio codec is supported.</li><li>We support videos with a single audio stream or no audio stream.</li></ul></td><td>16MB</td></tr><tr><td>sticker</td><td><code>image/webp</code></td><td><p>Static stickers: 100KB</p><p><br></p><p>Animated stickers: 500KB</p></td></tr></tbody></table>

## Recommendations&#x20;

* When sending media messages (images, videos, or audio), avoid using large files. Processing heavy media can cause transmission delays and impact message delivery.
* To optimize performance, upload media in advance via the `/media` endpoint and use the `media_id` from the response when sending messages. This ensures accurate processing and prevents delays during message send-outs.
* If a request to the `GET /media` endpoint returns a status code of 400, do not retry it repeatedly. Instead, investigate and resolve the error before making another request. Excessive retries can degrade performance and risk server overload.
* A rate limit is enforced on failed requests. If a phone number exceeds five (5) failed requests to the `/media` endpoint within one hour, access to the `GET /{MEDIA_ID}` endpoint will be temporarily blocked for that number for one hour to maintain service quality.
* If you encounter any media issues, please reach out to our Support Team