Mon-Fri 10am - 6pm
Send Media
Base URL for your account: https://cpaas.studio
POST
/api/whatsapp/v1/send/media
Send an image, video, audio, document or sticker inside the 24-hour window — from your media library (media) or an https link.
Parameters
| Param | Type | Required | Notes |
|---|---|---|---|
channel |
string | if the key is not restricted | Your number's uid. |
to |
string | yes | Recipient phone. |
type |
string | with link | image, video, audio, document or sticker. Optional with media (the library item's own type is used). |
media |
string | or link | Media uid from your library. |
link |
https url | or media | A public https URL Meta can fetch. |
caption |
string, max 1024 | no | Not for audio / sticker. |
filename |
string | no | Documents only. |
Request example
curl -X POST "https://cpaas.studio/api/whatsapp/v1/send/media" \
-H "X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: 6f1c2a9e-order-4471" \
-H "Content-Type: application/json" \
-d '{"channel":"WCH54DZ7M7M5V","to":"+919876543210","type":"document","media":"WMD7Q2M4X8A1B","caption":"Your invoice"}'
Success response (data)
{
"message": {
"type": "document",
"category": "service",
"ref": "1aB3-202610",
"channel": "WCH54DZ7M7M5V",
"to": "+919876543210",
"status": "queued",
"billing": {
"status": "billed",
"amount": 0.115
},
"created_at": "2026-10-10T09:15:00+00:00"
}
}
Errors
| Code | Status | When |
|---|---|---|
WA_WINDOW_CLOSED |
422 | 24-hour window closed — use a template with a media header. |
WA_RECIPIENT_EXCLUDED |
422 | The number opted out, is blacklisted, is not on WhatsApp, or is a username-only contact (error.details.reason). Nothing is charged. |
WA_CHANNEL_UNAVAILABLE |
422 | The number is disabled, restricted or disconnected. |
BILLING_NO_ACTIVE_PLAN |
402 | No active WhatsApp plan. |
WA_CATEGORY_DISABLED |
402 | The message's category is not on your plan. |
BILLING_PLAN_QUOTA_EXHAUSTED |
402 | The category allowance and the shared allowance are used up. |
REQ_IDEMPOTENCY_KEY_CONFLICT |
409 | The Idempotency-Key was used with a different body (or that request is still being processed). |
REQ_VALIDATION_FAILED |
422 | A field is missing or invalid (error.fields), including a number that is not a valid WhatsApp number. |
Notes
- 202 Accepted means recorded, charged and queued — not delivered. The message is sent by our worker within your number's messages-per-second limit; follow it with Message Status or the status webhook.
- Idempotency-Key header (recommended): the same key within 24 hours returns the original response (header Idempotent-Replayed: true) and sends nothing. A different body under the same key is 409.
- to: a phone number in international format; a 10-digit Indian mobile, 0 + 10 digits and +91 forms are all accepted. A number that is not yet a contact becomes one (your API terms cover the opt-in).
- channel: the uid of one of your numbers (Channels). Optional when the API key is restricted to one number.
- Rate limit: 6,000 requests per minute per account by default (all your keys share it; ask us to raise it). Above it: HTTP 429 SYS_RATE_LIMITED with a Retry-After header. Sends are additionally paced by each number's messages-per-second limit after acceptance.
Need more context? See Getting started for authentication, the response envelope, and the full error-code reference.