Skip to main content
flag
Mon - Fri   10:00 – 18:00

Send Media

API Documentation / WhatsApp / 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.