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

Send Session Message

API Documentation / WhatsApp / Send Session Message

Base URL for your account: https://cpaas.studio

POST /api/whatsapp/v1/send/session

Send free-form text (or an interactive message) inside the 24-hour customer-service window — i.e. within 24 hours of the contact's last message to you.

Parameters

Param Type Required Notes
channel string if the key is not restricted Your number's uid.
to string yes Recipient phone.
type string no text (default) or interactive.
text string, max 4096 for text The message.
preview_url boolean no Show a link preview.
interactive object for interactive A Cloud API interactive object (buttons / list).

Request example

curl -X POST "https://cpaas.studio/api/whatsapp/v1/send/session" \
  -H "X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 6f1c2a9e-order-4471" \
  -H "Content-Type: application/json" \
  -d '{"channel":"WCH54DZ7M7M5V","to":"+919876543210","text":"Your order ORD-4471 has shipped."}'

Success response (data)

{
    "message": {
        "type": "text",
        "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 The contact's 24-hour window is closed (or they never wrote to you). Send a template instead — it reopens the conversation.
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

  • WA_WINDOW_CLOSED is the error to handle in code: switch to send/template for that recipient. Nothing is charged for a refused message.
  • 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.