API Reference v1.0

Send Media

Send images, videos, audio files, and documents to WhatsApp users. Media messages support captions and are delivered with rich previews in the chat.

POST https://whatsbizapi.com/api/wpbox/sendmedia

Sends a media message (image, video, audio, or document) to a single recipient. The media file must be hosted at a publicly accessible URL. You can optionally include a caption with the media.

⚠

Media messages can only be sent within the 24-hour customer service window. To send media outside this window, use a template message with a media header via the Send Template endpoint.

Parameters

Parameter	Type	Description
token required	string	Your API authentication token.
phone required	string	Recipient phone number with country code. E.g., `+919876543210`.
type required	string	Media type. Must be one of: `image`, `video`, `audio`, `document`.
media_url required	string	Publicly accessible URL of the media file. Must use HTTPS. WhatsApp will download the file from this URL.
caption optional	string	Caption text displayed below the media. Maximum 1024 characters. Not supported for audio messages.
filename optional	string	Custom filename for document messages. Displayed to the recipient as the download name. E.g., `invoice-2025.pdf`.

Supported Media Types & Size Limits

Type	Supported Formats	Max Size	Caption
image	JPEG, PNG	5 MB	Yes
video	MP4, 3GPP	16 MB	Yes
audio	MP3, AAC, OGG, AMR	16 MB	No
document	PDF, DOC, DOCX, XLSX, PPTX, TXT, etc.	100 MB	Yes

Examples

1. Send Image with Caption

cURL

curl -X POST https://whatsbizapi.com/api/wpbox/sendmedia \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "phone": "+919876543210",
    "type": "image",
    "media_url": "https://example.com/images/product-photo.jpg",
    "caption": "Check out our latest product! Available now at 20% off."
  }'

Request Body

{
  "token": "YOUR_API_TOKEN",
  "phone": "+919876543210",
  "type": "image",
  "media_url": "https://example.com/images/product-photo.jpg",
  "caption": "Check out our latest product! Available now at 20% off."
}

Response 200

{
  "status": "success",
  "message_id": 301,
  "message_wamid": "wamid.HBgNOTE5ODc2NTQzMjEwFQIAERgSQTJC..."
}

2. Send PDF Document

cURL

curl -X POST https://whatsbizapi.com/api/wpbox/sendmedia \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "phone": "+919876543210",
    "type": "document",
    "media_url": "https://example.com/docs/invoice-2025-001.pdf",
    "caption": "Here is your invoice for January 2025.",
    "filename": "Invoice-Jan-2025.pdf"
  }'

Request Body

{
  "token": "YOUR_API_TOKEN",
  "phone": "+919876543210",
  "type": "document",
  "media_url": "https://example.com/docs/invoice-2025-001.pdf",
  "caption": "Here is your invoice for January 2025.",
  "filename": "Invoice-Jan-2025.pdf"
}

Response 200

{
  "status": "success",
  "message_id": 302,
  "message_wamid": "wamid.HBgNOTE5ODc2NTQzMjEwFQIAERgSQzRE..."
}

3. Send Video

cURL

curl -X POST https://whatsbizapi.com/api/wpbox/sendmedia \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "phone": "+919876543210",
    "type": "video",
    "media_url": "https://example.com/videos/product-demo.mp4",
    "caption": "Watch our 60-second product demo!"
  }'

Request Body

{
  "token": "YOUR_API_TOKEN",
  "phone": "+919876543210",
  "type": "video",
  "media_url": "https://example.com/videos/product-demo.mp4",
  "caption": "Watch our 60-second product demo!"
}

Response 200

{
  "status": "success",
  "message_id": 303,
  "message_wamid": "wamid.HBgNOTE5ODc2NTQzMjEwFQIAERgSRTZG..."
}

Error Responses

Error - Invalid Media Type 400

{
  "status": "error",
  "message": "Invalid media type. Must be one of: image, video, audio, document."
}

Error - Inaccessible URL 400

{
  "status": "error",
  "message": "Media URL is not accessible. Ensure the URL is public and uses HTTPS."
}

Error - File Too Large 400

{
  "status": "error",
  "message": "Media file exceeds the maximum allowed size."
}

Error - Authentication 401

{
  "status": "error",
  "message": "Invalid API token."
}

Notes

✗

Public URLs Required: Media URLs must be publicly accessible over HTTPS. WhatsApp servers download the file directly from your URL. URLs behind authentication, firewalls, or using HTTP (not HTTPS) will fail.

ℹ

Audio Captions: The caption parameter is not supported for audio messages. If you include a caption with an audio file, it will be silently ignored.

ℹ

Document Filenames: When sending documents, use the filename parameter to provide a human-readable filename. If omitted, the recipient will see the filename from the URL, which is often not user-friendly.

⚠

File Size Limits: WhatsApp enforces strict file size limits per media type. If your file exceeds the limit, the API will return an error. Compress or resize your media before sending if needed.

✓

Best Practice: For images, use JPEG format for photos and PNG for graphics with transparency. Keep image dimensions reasonable (recommended: 800x800 to 1600x1600 pixels). Very large images will be compressed by WhatsApp, which may reduce quality.