Media Uploads

Upload a document, image, or video before sending a WhatsApp template that has a media header.

How do I upload a PDF, image, or video for a WhatsApp template message using the SMSLeopard API?

Ask AI →

Upload Media

Use this endpoint when an approved WhatsApp template has a document, image, or video header. SMSLeopard uploads the file to Meta and returns a media_id that you can use with the send message endpoint.

Endpoint

POSThttps://whatsapp.smsleopard.com/v1/whatsapp/media

Authorization


Authorization: Basic <base64(api_key:api_secret)>

Request Body

Send the request as multipart/form-data.

Field	Type	Required	Description
`phone_number_id`	string	Yes	The WhatsApp `phone_number_id` that will send the template
`file`	file	Yes	The PDF, document, image, or video to upload
`type`	string	No	Optional media category: `document`, `image`, or `video`
`file_name`	string	No	Optional display filename. For documents, this is used as the attachment name

Supported Media

Category	Supported MIME types	Maximum size
`document`	`application/pdf`, `text/plain`, Microsoft Word, Excel, and PowerPoint files	100 MB
`image`	`image/jpeg`, `image/png`	5 MB
`video`	`video/mp4`, `video/3gpp`	16 MB

SMSLeopard stores only metadata such as the returned media_id, filename, type, and size. The uploaded file is forwarded to Meta and is not stored by SMSLeopard after the upload request completes.

Request

cURL


curl -X POST "https://whatsapp.smsleopard.com/v1/whatsapp/media" \
  -H "Authorization: Basic $(echo -n 'api_key:api_secret' | base64)" \
  -F "phone_number_id=46646XXXXXXX268" \
  -F "type=document" \
  -F "file_name=estimate.pdf" \
  -F "file=@./estimate.pdf;type=application/pdf"

JavaScript


async function uploadWhatsAppMedia({ apiKey, apiSecret, phoneNumberId, file }) {
  const formData = new FormData();
  formData.append("phone_number_id", phoneNumberId);
  formData.append("type", "document");
  formData.append("file_name", file.name);
  formData.append("file", file);
 
  const response = await fetch("https://whatsapp.smsleopard.com/v1/whatsapp/media", {
    method: "POST",
    headers: {
      Authorization: `Basic ${btoa(`${apiKey}:${apiSecret}`)}`,
    },
    body: formData,
  });
 
  return response.json();
}

Python


import base64
import requests
 
def upload_whatsapp_media(api_key, api_secret, phone_number_id, file_path):
    credentials = base64.b64encode(f"{api_key}:{api_secret}".encode()).decode()
 
    with open(file_path, "rb") as file:
        response = requests.post(
            "https://whatsapp.smsleopard.com/v1/whatsapp/media",
            headers={"Authorization": f"Basic {credentials}"},
            data={
                "phone_number_id": phone_number_id,
                "type": "document",
                "file_name": "estimate.pdf",
            },
            files={"file": ("estimate.pdf", file, "application/pdf")},
        )
 
    return response.json()

Response


{
  "id": 1,
  "phone_number_id": "46646XXXXXXX268",
  "media_id": "987654321098765",
  "media_type": "document",
  "mime_type": "application/pdf",
  "file_name": "estimate.pdf",
  "file_size": 245678
}

Send With Uploaded Media

Use the returned media_id with POST /v1/whatsapp/send.


{
  "destination": "254720000000",
  "template_id": "document_template_id",
  "phone_number_id": "46646XXXXXXX268",
  "media_id": "987654321098765",
  "file_name": "estimate.pdf",
  "component_list": {
    "components": [
      {
        "component_type": "BODY",
        "fields": [
          { "name": "1", "value": "Peter" },
          { "name": "2", "value": "INV-1001" },
          { "name": "3", "value": "KES 4,000" }
        ]
      }
    ]
  }
}

The uploaded media must match the template header type. A document media_id can only be used with a document-header template, an image media_id with an image-header template, and a video media_id with a video-header template.