Skip to main content
POST
Download media (unified)
Downloads the media of a received message. WhatsApp delivers encrypted media; this endpoint decrypts it using the metadata that arrives in the webhook (media_key, mimetype, direct_path or url, and the hashes). Set base64: true to receive the content embedded in the response, or use async for large downloads in the background.
The required fields (media_key, mimetype, file_sha256 etc.) come in the received message webhook payload — pass them straight through to this endpoint.

Official API (Cloud API)

On Official API connections, media is stored at Meta and identified by the media_id, which arrives in the webhook in media_data.media_id. Send media_id and mimetype instead of media_key, direct_path and hashes. The response is always synchronous — async is not accepted on these connections.

Accounts with “Do not store media”

With the Do not store media option enabled under My Account → Privacy, D-API does not keep any of the account’s media: nothing goes to storage, Redis, queues or the database. Received message webhooks carry only the metadata (media_key, direct_path, hashes or media_id), with no media_url and no base64, and the file is retrieved through this endpoint. On these accounts:
  • the response is always base64, even without base64: true;
  • async is rejected — download is synchronous only;
  • base64 media sends with async are also rejected; use synchronous sending or a URL.
Enabling or disabling the option restarts the account’s unofficial connections, which go offline for a few seconds.

Authorizations

Authorization
string
header
required

API Key for authentication. Format: <API_KEY>

Body

sessionId
string
required
Minimum string length: 1
mimetype
string
required
Minimum string length: 1
url
string
direct_path
string
media_key
string
Minimum string length: 1
media_id
string
Minimum string length: 1
media_type

Media type. Optional: when omitted, it is inferred from the mimetype.

Allowed value: "image"
file_enc_sha256
string
file_sha256
string
file_length
number
async
base64
boolean

Response

200

Successful response