LogoLogo
Become a PartnerStatus Page
  • get started
    • Welcome to 360Dialog
    • Quickstarts
      • Register as a Meta Tech Provider
      • Add a WhatsApp Number
      • Set up Integrated Onboarding
      • Create a Message Template
      • Send a Message
      • (temp title) Getting started as a partner
    • Pricing & Billing
      • Payment Methods for BR: Pix & Boleto
      • Month Closing Invoice (MCI)
    • Get API Access
    • Tech Provider Program
      • Understanding the Meta Tech Provider Program
      • Becoming a Meta Tech Provider: A Step-by-Step Guide
  • MM Lite Beta Program
    • Onboarding
    • Sending Messages
    • Expected Errors & Programming Languages
    • MM Lite Sandbox Testing
      • Sending Messages using MM Lite Sandbox
      • Expected Erros & Programming Languages
  • Partner & Account Management
    • Solutions for Partners
      • Benefits for Partners
      • Partner Hub
      • WABA Management
    • Account Setup & Management
      • Prerequisites and best practices for account creation
      • Account Structure
      • Account Creation
  • Integrations & API Development
    • Webhook Events & Setup
      • Webhook Events (Partner & Messaging API)
      • Webhook Configuration & Management
    • Integration Best Practices
      • Architecture and Security
      • Best Practices for Designing Integrations
        • Design a Stable Webhook Receiving Endpoint
      • Sizing Your Environment Based on Expected Throughput
      • Design a Resilient Message Sending Service
      • Integrated Onboarding
        • Basic Integrated Onboarding
        • Custom Integrated Onboarding
        • Host Your Own Embedded Signup
      • API Key Authentication for the Partner API
  • API Reference
    • Messaging API
    • Messaging Health Status
    • Sandbox (Test API Key)
    • Differences Between Cloud API and On-Premise API for Partners
      • [will be deprecated] Messaging with On-Premise API
    • Partner API
  • WABA Management
    • Managing WABA Accounts
      • Using the Partner Hub to manage Clients and Channels
      • Using the Partner API to manage Clients and Channels
      • Partner Permission to Generate API Key
      • Checking Usage & Statistics
    • Phone Number & Hosting
      • Migrating a Phone Number
        • Migrate number from Meta or alternate BSP to 360Dialog
        • Migrate a phone number to a new WABA
        • Migrate a phone number to a new WABA to change messaging Currency
      • WhatsApp Coexistence
        • Coexistence Onboarding
        • Coexistence Webhooks
      • Hosting type Change (On-premise API to Cloud API)
    • WABA Profile & Compliance
      • Display Name Guidelines
      • WABA Profile Info
      • WABA Policy Enforcement
      • Business Account Verification
    • Partner change (between 360Dialog Partners)
    • WhatsApp Flows
    • Accelerated Onboarding
    • Business Account Verification
  • Messaging
    • Sending & Receiving Messages
      • Conversations
      • Receiving messages
      • Before sending a message
    • Message Types
      • Conversational Components
      • Checklist for Message Broadcasts and Campaigns
      • Text messages
      • Interactive messages
        • Single and Multi Product Messages
        • Location Request Messages
        • Address Messages (India and Singapore only)
      • Contacts & Location Messages
    • Template Messages
      • Template Library
      • Template Elements
      • Sending Template Messages
      • Authentication Templates
        • Zero-Tap Authentication Templates
        • One-Tap Autofill Authentication Templates
        • Copy Code Authentication Templates
      • Catalog Templates
      • Product Card Carousel Templates
      • Single-Product Message Templates
      • Coupon Code Templates
      • Limited-Time Offer Templates
      • Multi-Product Templates
    • Media Messages
      • Upload, retrieve or delete media
    • Messaging Health & Troubleshooting
      • Messaging Limits & Quality Rating
      • Errors While Messaging
      • Messages statuses
  • Commerce & Payments
    • Payments (India Only)
      • Receive WhatsApp Payments via Payments Gateway
      • Receive WhatsApp Payments via Payment Links
      • Order Details Template Message
    • Payments (Singapore Only)
      • Receive WhatsApp Payments via Stripe
    • Products and Catalogs
      • India Businesses: Compliance for Commerce
  • Support & Updates
    • Help & Troubleshooting
      • FAQ
      • Error Code Reference
      • User Support Documentation
        • Tutorials
          • Page How to Troubleshoot Login Issues in the 360dialog Hub
          • How to Report an Issue
          • How to Contact Support
        • How-To Guides
          • Raise a support request
          • Requesting a Status Update for Business Verification
        • Reference
          • Troubleshooting Embedded Signup Issues
          • Commerce Policy Checks for WhatsApp API Access
          • Support Availability & SLAs
          • Incident Issue Prioritization
          • Case Types Table
        • Explanation
          • Why Business Verification Takes Time
          • Why Some Issues Are Not Emergencies
          • Understanding the Support Process
      • Support with Meta
    • Imprint & Data Privacy
    • Product Updates & News
      • How to ensure your Template Messages will be received
      • Integrated Onboarding new look and Campaigns Best Practices
Powered by GitBook
On this page
  • Constraints
  • Endpoints
  • Upload Media
  • Get Media
  • Retrieve Media URL
  • Delete Media
  • Supported Media Types
  • Recommendations
  • [will be deprecated] If the WABA is registered in On-premise API
  • Constraints
  • Endpoints
  • Upload Media
  • Get Media
  • Delete media
  • Supported Media Types

Was this helpful?

  1. Messaging
  2. Media Messages

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.

PreviousMedia MessagesNextMessaging Health & Troubleshooting

Last updated 1 month ago

Was this helpful?

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 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.

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

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

Headers

Name
Type
Description

D360-API-KEY

string

360Dialog API Key

{
    "id": "1094408688491179"
}

curl -X POST 'https://waba-v2.360dialo.io/media' -H 'D360-API-KEY: YOUR_API_KEY' -F 'file=@/local/path/file.jpg;type=image/jpeg'

-F '"messaging_product" = "whatsapp"'

Headers

Name
Type
Description

D360-API-KEY

string

fgqBtpI9EIlO

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

media-id

Headers

Name
Type
Description

D360-API-KEY

string

360Dialog API Key

{
  "messaging_product": "whatsapp",
  "url": "URL",
  "mime_type": "image/jpeg",
  "sha256": "HASH",
  "file_size": "SIZE",
  "id": "ID"
}

Path Parameters

Name
Type
Description

media-id

string

YbnVwPlVVPGj

Headers

Name
Type
Description

D360-API-KEY

string

0vhh8CoPg8VS

Example

GET response was:

{ 
"messaging_product": "whatsapp", 
"url": https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=130345565692730173924&ext=1664537344507&hash=ATtBt0Cdio, 
"mime_type": "image/jpeg",
"sha256": "HASH", 
"file_size": "SIZE", 
"id": "ID"
}

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.

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

Use this edge to retrieve and delete media.

Headers

Name
Type
Description

D360-API-KEY

string

360Dialog API Key

{
  "success": true
}

Path Parameters

Name
Type
Description

media-id

string

MkbpAwcbdluI

Headers

Name
Type
Description

D360-API-KEY

string

hZnnW2gxjqN7

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 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.

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 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.

  • 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

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

Headers

Name
Type
Description

D360-API-KEY

string

360Dialog API KEY

{
    "id": "1094408688491179"
}

curl -X POST https://waba.360dialog.io/v1/media \

-H 'Content-Type: image/jpeg' \ # or other appropriate media type

--data-binary @your-file-path

Headers

Name
Type
Description

D360-API-KEY

string

efjrlA0y61FH

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.

Request example

curl -X GET https://waba.360dialog.io/v1/media/4b5bf27b-8672-4d55-bc21-d096dc200d0f

Path Parameters

Name
Type
Description

media_id

string

media_id

Headers

Name
Type
Description

D360-API-KEY

string

360Dialog API KEY

Content-Type: image/jpeg or other appropriate media type
Content-Length: content-size

binary-media-data

Path Parameters

Name
Type
Description

media_id

string

vDSOlq3uXRn9

Headers

Name
Type
Description

D360-API-KEY

string

MQJQuRAkOfdG

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.

{
    // Response
}

Path Parameters

Name
Type
Description

media-id*

String

SJ0xfUeb8DJy

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

audio

16 MB

document

100 MB

image

5 MB

sticker

100 KB

video

16 MB

In case you receive 308 Permanent Redirect errors using cURL, please use the --location to follow redirects.

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 .

option
See differences between On-premise API and Cloud API
Learn how to change hosting type of registered numbers
ttps://exiftool.org/TagNames/EXIF.html
Supported Media Types
Post-Processing Media Size table
Enable Cloud API in your Partner Hub to be able to register Cloud API numbers