Download WhatsApp Media

Download a media file (image, video, audio, document, or sticker) that a lead sent to your WhatsApp Business number. You can identify the file by its WhatsApp media ID or by its WhatsApp media URL.

The API returns the file bytes directly. It does not return a JSON body on success.

Common use cases include saving customer documents to your own system, showing received images in your CRM, or processing voice notes.

Endpoint

GET  /engage/v1/wa-messages/media
POST /engage/v1/wa-messages/media

Both methods behave the same. Use POST if you do not want the media URL to appear in request logs or proxies.

Authentication

All requests must include a business access token. You can send it in either header — if both are present, Authorization is used.

- Tokens are issued per business and are scoped to that business. You can only download media that your business's WhatsApp number received. - If the token is missing, invalid, or expired the API returns 401 Unauthorized. - Keep your token secret. Do not expose it in client-side code or public repositories.

Parameters

Send one of id or url. If you send both, url is used.

- For GET, send the parameter in the query string. URL-encode the url value. - For POST, send the parameter in a JSON body with Content-Type: application/json.

Which one to use

- id — Recommended. A media ID stays valid for about 30 days after the message is received. The API gets a fresh download URL for you. - url — A WhatsApp media URL expires about 5 minutes after it is issued. Use it only if you download the file immediately.

Request Examples

GET /engage/v1/wa-messages/media?id=1234567890123456 HTTP/1.1
Host: client-api.e-so.in
Authorization: Bearer YOUR_TOKEN

POST /engage/v1/wa-messages/media HTTP/1.1
Host: client-api.e-so.in
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{ "id": "1234567890123456" }

Responses

Success — 200 OK

The body is the raw file. Use the response headers to save it correctly.

Error Responses

Errors return a JSON body in this shape:

{
  "status": 404,
  "success": false,
  "message": "Media not found."
}

Validation error example:

{
  "status": 422,
  "success": false,
  "message": "VALIDATION_FAILURE",
  "messages": {
    "errors": [{ "rule": "requiredIfNotExists", "field": "id", "message": "Either id or url is required." }]
  }
}

> Always check the HTTP status before you save the body. On an error, the body is JSON, not the file.

Code Examples

> Replace YOUR_TOKEN with your business access token.

cURL

# GET by media ID — saves to file using the server-provided name
curl -G "https://client-api.e-so.in/engage/v1/wa-messages/media" \
  --data-urlencode "id=1234567890123456" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o media.bin

# POST by media URL
curl -X POST "https://client-api.e-so.in/engage/v1/wa-messages/media" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=..."}' \
  -o media.bin

JavaScript — fetch (Node.js)

import { writeFile } from "node:fs/promises";

const response = await fetch("https://client-api.e-so.in/engage/v1/wa-messages/media", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({ id: "1234567890123456" }),
});

if (!response.ok) {
  const body = await response.json();
  throw new Error(`Error ${body.status}: ${body.message}`);
}

const contentType = response.headers.get("content-type");
await writeFile("media.bin", Buffer.from(await response.arrayBuffer()));
console.log(`Saved ${contentType}`);

Python — requests

import requests

resp = requests.post(
    "https://client-api.e-so.in/engage/v1/wa-messages/media",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"id": "1234567890123456"},
    stream=True,
)

if resp.ok:
    with open("media.bin", "wb") as f:
        for chunk in resp.iter_content(chunk_size=65536):
            f.write(chunk)
    print("Saved", resp.headers.get("Content-Type"))
else:
    body = resp.json()
    print(f"Error {body['status']}: {body['message']}")

Related Endpoints

Support

If you have a problem with this endpoint, include this in your support request:

- The method and full request URL - The media id (do not send the access token) - The status and message from the error response - The time of the request (UTC)