Media Uploads

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

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

POST /v1/whatsapp/media

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

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.

Templates Sending Messages