Upload, retrieve or delete media

To send media such as images, documents, audio, or video, it is recommended to use media IDs. So you must first upload the Media and then send it.

Media Endpoints

You use 4 different endpoints to manage your media:

Endpoint
Uses

POST https://waba-v2.360dialog.io/media

Upload media.

GET https://waba-v2.360dialog.io/{media-id}

Retrieve the Meta URL for a specific media.

POST https://waba-v2.360dialog.io/whatsapp_business/attachments/?mid={MESSAGE_ID}&ext={EXPIRY_TIMESTAMP}&hash={HASH_VALUE}

Download media from a media URL.

DELETE https://waba-v2.360dialog.io/{media-id}

Delete media

Constraints

  • ⚠️There is a rate limit on failed requests to the /media endpoint. If a phone number exceeds five (5) failed requests within one hour, access to the GET /{MEDIA_ID} endpoint will be temporarily blocked for that number for one hour to ensure service quality

  • 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

Upload Media

POST https://waba-v2.360dialog.io/media

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

Request example

curl --location "https://waba-v2.360dialog.io/media" \
  --header "D360-API-KEY: {{api_key}}" \
  --form "messaging_product=whatsapp" \
  --form "file=@/local/path/file.jpg;type=image/jpeg"

Headers

Key
Value

D360-API-KEY

{{api_key}}

{
    "id": "1094408688491179"
}
Example in postman

Get Media URL

GET https://waba-v2.360dialog.io/{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)

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

media-id

Headers

Key
Value

D360-API-KEY

{{api_key}}

{
    "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=1892054061371916&ext=1757082791&hash=ARm1DwW7XRmb2SOs7rlpEL5cceMurv8SN7XXIJpt6rpTbA",
    "mime_type": "image/jpeg",
    "sha256": "417c9a0755aa29d0292178af25ce2dff586cc21c4ef098b3650f1f051fd39f00",
    "file_size": 5848,
    "id": "media_id",
    "messaging_product": "whatsapp"
}

Download Media

POST https://waba-v2.360dialog.io/whatsapp_business/attachments/?mid={MESSAGE_ID}&ext={EXPIRY_TIMESTAMP}&hash={HASH_VALUE}

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&ext=1664537344507&hash=ATtBt0Cdio

  • Please note that the query string parameters in this link are confidential and must be treated as sensitive information. The link is time-bound and will remain valid for 5 minutes only.

Request Example

curl -X GET \
'https://waba-v2.360dialog.io/whatsapp_business/attachments/?mid=130345565692730173924&ext=1664537344507&hash=ATtBt0Cdio' \
-H 'D360-API-KEY: YOUR_API_KEY' \

Headers

Name
Value

D360-API-KEY

application/json

{{api_key}}

Response

Media file

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}

Path Parameters

Name
Type
Description

media-id

string

media-id

Headers

Name
Description

D360-API-KEY

360dialog API Key

Supported Media Types

Media
Supported Types
Size Limit

audio

audio/aac .acc, audio/amr .amr, audio/mpeg .mp3, audio/mp4 .m4a, audio/ogg (only opus codecs, base audio/ogg is not supported)

16MB

document

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

100MB

image

image/jpeg, image/png

Images must be 8-bit, RGB or RGBA

5MB

video

video/mp4, video/3gp

Notes:

  • Only H.264 video codec and AAC audio codec is supported.

  • We support videos with a single audio stream or no audio stream.

16MB

sticker

image/webp

Static stickers: 100KB

Animated stickers: 500KB

Recommendations

  • 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

Last updated

Was this helpful?