Upload, retrieve or delete media
To send media such as images, documents, audio or video you must first Upload the Media and then Send it.
The media hosting is managed by Meta for numbers in the Cloud API. All media files sent through this endpoint are encrypted and persist for 30 days, unless they are deleted earlier.
Constraints
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.
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
Note: If a request to the GET/media
endpoint returns a status code of 400 or higher, ensure that it is not retried multiple times to prevent performance degradation and potential server overload. It's recommended to investigate the cause of the error and address it before attempting to make the request again.
There is a rate limit on failed requests of the /media
endpoint. If a phone number exceeds five (5) failed requests within an hour, access to GET/{MEDIA_ID}
endpoint will be blocked for that number for 1 hour to maintain service quality. In case you have any issues, reach out to our Support Team.
Endpoints
Upload Media
POST
https://waba-v2.360dialog.io/media
Make a POST request to /media to upload your media.
Request example
Headers
Name | Type | Description |
---|---|---|
D360-API-KEY | string | 360dialog API Key |
To retrieve a media you need to use an endpoint to retrieve the URL and submit get again with the URL received.
Get Media
GET
https://waba-v2.360dialog.io/{media-id}
You can then retrieve the media from the local volume by referencing the media_id
.
Request example
curl -X GET
'https://waba-v2.360dialog.io/MEDIA_ID'
-H 'D360-API-KEY: YOUR_API_KEY''
Path Parameters
Name | Type | Description |
---|---|---|
media-id | string |
|
Headers
Name | Type | Description |
---|---|---|
D360-API-KEY | string | 360dialog API Key |
Retrieve Media URL
You can use the returned URL to download the media file obtained from previous endpoint.
So for the response you obtain, delete the root hostname https://lookaside.fbsbx.com
and a attach the rest /whatsapp_business/attachments/?mid=130345565692730173924&ext=1664537344507&hash=ATtBt0Cdio
to our root url https://waba-v2.360dialog.io.
Payload Example to Download media:
curl -X GET 'https://waba-v2.360dialog.io/
whatsapp_business/attachments/?mid=130345565692730173924&ext=1664537344507&hash=ATtBt0Cdio
'
-H 'D360-API-KEY: YOUR_API_KEY' > media_file
Please treat the postfix of this message as secret. Important: This link will be valid for 5 minutes.
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 to follow redirects.
Delete Media
DELETE
https://waba-v2.360dialog.io/{media-id}
To delete media, make a call to the ID of the media you want to delete.
Path Parameters
Name | Type | Description |
---|---|---|
media-id | string |
|
Headers
Name | Type | Description |
---|---|---|
D360-API-KEY | string | 360dialog API Key |
Supported Media Types
Media | Supported Types | Size Limit |
---|---|---|
audio |
| 16MB |
document |
| 100MB |
image |
Images must be 8-bit, RGB or RGBA | 5MB |
video |
Notes:
| 16MB |
sticker |
| Static stickers: 100KB
Animated stickers: 500KB |
Recommendations
When sending messages with media such as images, videos, or audio files, it is important to ensure that they are not heavy, as processing heavy media files at once can cause delays in transmission and lead to issues with message delivery.
For this, we suggest uploading media beforehand using the /media
endpoint and then utilizing the media_id
obtained from the response when sending messages.
By following this approach, you can ensure that the media file is processed accurately without causing any delays or latencies during send-outs.
Rate limit on failed requests: If a request to the GET/media
endpoint returns a status code of 400 or higher, ensure that it is not retried multiple times to prevent performance degradation and potential server overload. It's recommended to investigate the cause of the error and address it before attempting to make the request again.
There is a rate limit on failed requests of the /media
endpoint. If a phone number exceeds five (5) failed requests within an hour, access to GET/{MEDIA_ID}
endpoint will be blocked for that number for 1 hour to maintain service quality. In case you have any issues, reach out to our Support Team.
[will be deprecated] If the WABA is registered in On-premise API
As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.
Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to start changing the hosting type of numbers to Cloud as soon as possible. Learn here how to integrate with Cloud API.
When a media message is sent, the media is stored on the WhatsApp servers for 14 days. We also store media on our servers for 14 days. If a user makes a request to download the media after 14 days, they will be notified that the media is unavailable.
It is a good practice for partners and clients to store any media in their own servers and delete them from our servers immediately after.
Constraints
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 application processes the media that is uploaded before it's sent to the server. While the maximum file size for media that can be uploaded to the
media
node is 64MB, there are post-processing limits for the various media types outlined in the Post-Processing Media Size table.Media storage is handled by 360dialog. If the media volume gets full, message sending will start to fail.
There is no support for:
Sending media by byte streams.
Sending messages with animated stickers.
Note: If a request to the GET/media
endpoint returns a status code of 400 or higher, ensure that it is not retried multiple times to prevent performance degradation and potential server overload. It's recommended to investigate the cause of the error and address it before attempting to make the request again.
There is a rate limit on failed requests of the /media
endpoint. If a phone number exceeds five (5) failed requests within an hour, access to GET/{MEDIA_ID}
endpoint will be blocked for that number for 1 hour to maintain service quality. In case you have any issues, reach out to our Support Team.
Endpoints
Upload Media
POST
https://waba.360dialog.io/v1/media
Make a POST request to /v1/media to upload your media. The body of the API request must contain the binary media data and the Content-Type header must be set to the type of the media being uploaded.
Request example
Headers
Name | Type | Description |
---|---|---|
D360-API-KEY | string | 360dialog API KEY |
Content-Type: image/jpeg or other appropriate media type your-binary-media-data
Get Media
GET
https://waba.360dialog.io/v1/media/{media_id}
You can then retrieve the media from the local volume by referencing the media_id
.
Path Parameters
Name | Type | Description |
---|---|---|
media_id | string |
|
Headers
Name | Type | Description |
---|---|---|
D360-API-KEY | string | 360dialog API KEY |
Delete media
DELETE
https://waba.360dialog.io/v1/media/{media-id}
API endpoint that will delete the media file from the storage volume.
Path Parameters
Name | Type | Description |
---|---|---|
media-id* | String | Use this edge to retrieve and delete media. |
Supported Media Types
Media | Supported Content-Types |
---|---|
audio | audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus Note: The base audio/ogg type is not supported. |
document | Any valid MIME-type. |
image | image/jpeg, image/png |
sticker | image/webp |
video | video/mp4, video/3gpp Notes: Only H.264 video codec and AAC audio codec is supported. Only videos with a single audio stream are supported. |
Post-Processing Media Size
This is the maximum allowed size of the media file after compression and encryption.
Media Type | Size |
---|---|
| 16 MB |
| 100 MB |
| 5 MB |
| 100 KB |
| 16 MB |
Last updated