---
title: "Send WhatsApp Media"
description: "Send images, PDF invoices, documents, audio notes, or video attachments via WhatsApp API v2."
---

# Send WhatsApp Media

Bulkit allows you to send media attachments up to **50MB** to WhatsApp recipients.

You can send media using two methods:
1. **Remote Media URL (`application/json`)**: Bulkit fetches the file from your server or cloud storage (e.g. S3, GCS) and delivers it via WhatsApp.
2. **Multipart File Upload (`multipart/form-data`)**: Direct binary upload from your server.

## Endpoint

```http
POST /api/v2/messages/whatsapp
```

## Method 1: Remote Media URL (Recommended)

Pass the publicly accessible URL of your file in `media_url`. Bulkit downloads, encrypts, and delivers the file as a native WhatsApp attachment.

### Request Body (`application/json`)

```json
{
  "recipient": "254700000001",
  "media_url": "https://example.com/invoices/INV-2026-001.pdf",
  "file_name": "Invoice-September.pdf",
  "message": "Hi Jane, please find attached your monthly statement."
}
```

### Parameters

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `recipient` | Yes | string | Destination phone number (e.g. `254700000001`). Aliases: `mobile`, `phone`. |
| `media_url` | Yes | string | Fully-qualified public HTTP/HTTPS URL of the file (max 50MB). |
| `file_name` | No | string | Custom display file name (especially useful for PDFs and documents). |
| `message` | No | string | Optional caption sent alongside the media. Aliases: `caption`, `text`. |

### Example with cURL

```bash
curl -X POST "https://api.bulkitsms.com/api/v2/messages/whatsapp" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "254700000001",
    "media_url": "https://assets.example.com/flyer.png",
    "message": "Check out our weekend special offers! 🔥"
  }'
```

---

## Method 2: Multipart File Upload

Directly upload the binary file from your local disk using `multipart/form-data`.

### Request Parameters (`multipart/form-data`)

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `recipient` | Yes | string | Destination phone number (e.g. `254700000001`). |
| `file` | Yes | file | The binary file to send (max 50MB). |
| `message` | No | string | Optional caption for the attachment. |

### Example with cURL

```bash
curl -X POST "https://api.bulkitsms.com/api/v2/messages/whatsapp" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md" \
  -F "recipient=254700000001" \
  -F "file=@/path/to/receipt.pdf" \
  -F "message=Here is your official receipt."
```

### Python Example (Multipart Upload)

```python
import requests

url = "https://api.bulkitsms.com/api/v2/messages/whatsapp"
headers = {
    "Authorization": "Bearer bk_live_8n6JQv3K1h9Lp0Md",
}

data = {
    "recipient": "254700000001",
    "message": "Here is your booking confirmation voucher.",
}

with open("voucher.pdf", "rb") as f:
    files = {"file": ("voucher.pdf", f, "application/pdf")}
    response = requests.post(url, data=data, files=files, headers=headers)

print(response.json())
```

---

## Success Response

```json
{
  "status": "success",
  "message": "WhatsApp media message sent successfully",
  "data": {
    "id": "2d8f993e-c651-46ab-bb12-98442e9fa501",
    "message_id": "3EB0E56A1B29D381",
    "recipient": "254700000001",
    "chat_jid": "254700000001@s.whatsapp.net",
    "text": "Hi Jane, please find attached your monthly statement.",
    "media_type": "document",
    "media_url": "/api/v2/messages/whatsapp/2d8f993e-c651-46ab-bb12-98442e9fa501/media",
    "file_name": "Invoice-September.pdf",
    "file_size": 245760,
    "mime_type": "application/pdf",
    "cost": 0.03,
    "currency": "KES",
    "status": "sent",
    "timestamp": "2026-09-19T06:35:00Z"
  }
}
```

<Tip>
The `media_url` in the response provides a secure link to re-download the decrypted media attachment via Bulkit API v2 at any time.
</Tip>