Bulk SMS REST API

Authentication

Every request must carry your API key and API secret. Create them in the portal under API & Plugins → Generate API credentials; you can view them again at any time with View Key & Secret.

Option A — request headers (recommended)

X-Api-Key:    cw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Secret: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Option B — HTTP Basic auth

Authorization: Basic base64(API_KEY:API_SECRET)

Option C — query / form fields

For quick tests you may pass api_key and api_secret as query-string or form parameters. Prefer headers in production so the secret never appears in URLs or logs.

Quickstart

1. Generate credentialsOpen API & Plugins in the portal and click Generate API credentials. Copy the key and the secret.
2. Check your balanceCall GET /api/balance to confirm the credentials work and you have funds.
3. Send a testPOST to /api/send with a single number you control.
4. Check deliveryCall GET /api/history?campaign_id=… using the campaign_id returned by the send.

curl -X POST 'https://sms.cloudwavebd.com/api/send' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: cw_YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -d '{ "message": "Hello from the API!", "to": "01712345678" }'

Endpoints

All paths are relative to the base URL https://sms.cloudwavebd.com. Every response includes "ok": true|false.

GET /api/balance

Response

{
  "ok": true,
  "balance": 123.45,
  "currency": "BDT",
  "client": { "id": 3, "email": "client@example.com" }
}

GET /api/senders

Response

{
  "ok": true,
  "default_sender": "8809617611036",
  "senders": [
    { "sender_id": "8809617611036", "provider": "bulksmsbd", "rate_bdt": 0.35, "unicode": true }
  ]
}

Errors

Errors use standard HTTP status codes and a consistent JSON shape:

{ "ok": false, "error": "unauthorized", "message": "Invalid API key or secret." }

GET /api/history

Query parameters

Response — campaign list

{
  "ok": true,
  "campaigns": [
    { "id": 42, "name": "Eid offer", "sender_id": "8809617611036", "provider": "bulksmsbd",
      "recipients": 2, "parts": 1, "total_cost": 0.7, "status": "sent",
      "created_at": "2026-09-28 12:30:11" }
  ],
  "page": 1, "per_page": 25, "total": 1
}

Response — single campaign

{
  "ok": true,
  "campaign": { "id": 42, "name": "Eid offer", "status": "sent", "total_cost": 0.7, "recipients": 2, "parts": 1 },
  "messages": [
    { "id": 501, "recipient": "8801712345678", "status": "sent", "attempts": 1,
      "error": null, "parts": 1, "amount": 0.35, "sent_at": "2026-09-28 12:30:12" }
  ],
  "page": 1, "per_page": 25, "total": 2
}

Billing & message parts

An SMS is billed per part. Long messages and Bangla (Unicode) messages split into more parts, so the cost is parts × rate_per_part × recipients. The rate per part comes from GET /api/senders (your account may have custom rates).

Delivery statuses

Admin approval for large sends

Sends above the account's threshold (default 100 recipients) are queued as pending_approval. The full cost is reserved from the wallet immediately, but no message is transmitted until an operator approves it in the portal.

• You receive 202 Accepted with status: "pending_approval" and a campaign_id.
• Poll GET /api/history?campaign_id=… to watch it change to queued → sent (approved) or rejected.
• Approve dispatches the campaign; Reject refunds the entire reserved cost to the wallet.
• Split very large audiences into batches under the threshold if you need instant (non-approved) delivery.

Best practices

• Store credentials in environment variables or a secrets store — never in code or version control.
• Reuse one connection and set a sensible timeout (5–10s) on your HTTP client.
• Batch recipients up to 500 per request instead of one request per number.
• Handle 202 pending_approval as success-with-review, not as an error.
• De-duplicate your audience before sending unless duplicates are intentional.
• Poll history sparingly; the portal is the source of truth and delivery reports arrive asynchronously.
• Respect Bangladesh telemarketing / BTRC rules — send only to recipients who opted in.

Code samples

Send an SMS to two recipients. Replace the credentials and numbers.

curl -X POST 'https://sms.cloudwavebd.com/api/send' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: cw_YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -d '{
    "message": "Hello from the API!",
    "to": ["01712345678", "8801812345678"],
    "campaign": "API test"
  }'

<?php
$ch = curl_init("https://sms.cloudwavebd.com/api/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Content-Type: application/json",
        "X-Api-Key: cw_YOUR_API_KEY",
        "X-Api-Secret: YOUR_API_SECRET",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "message"  => "Hello from PHP!",
        "to"       => ["01712345678"],
        "campaign" => "PHP test",
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($result["ok"])) {
    echo "Queued campaign #" . $result["campaign_id"] . PHP_EOL;
} else {
    echo "Error: " . ($result["message"] ?? "unknown") . PHP_EOL;
}

import requests

resp = requests.post(
    "https://sms.cloudwavebd.com/api/send",
    headers={"X-Api-Key": "cw_YOUR_API_KEY", "X-Api-Secret": "YOUR_API_SECRET"},
    json={"message": "Hello from Python!", "to": ["01712345678"]},
    timeout=10,
)
print(resp.json())

const res = await fetch("https://sms.cloudwavebd.com/api/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "cw_YOUR_API_KEY",
    "X-Api-Secret": "YOUR_API_SECRET",
  },
  body: JSON.stringify({ message: "Hello from Node!", to: ["01712345678"] }),
});
console.log(await res.json());

Plugins & integrations

Prefer a ready-made integration over writing your own client? Both plugins authenticate with the same API key and secret from this page and bill the same wallet.

WHMCS Module

Send SMS for orders, invoices and tickets, run bulk campaigns, and let clients top up their wallet by paying a WHMCS invoice — all from your WHMCS admin area.

Download ZIP Setup guide

WordPress / WooCommerce Plugin

Order receipts, order-status updates, new-user and comment alerts, and bulk SMS — straight from your WordPress or WooCommerce site.

Download ZIP Setup guide

FAQ

My message went to sent but the recipient says they didn't get it.

sent means the gateway accepted it. Actual handset delivery depends on the recipient's network; a delivery report (when available) later flips the status to delivered.

Can I send the same message to the same number twice?

Yes — set allow_duplicates: true. Otherwise duplicates are removed and billed once.

Why is my cost higher than recipients × rate?

Because the message split into multiple parts (long text, or Bangla/Unicode). See Billing & parts.

Is there a webhook for delivery reports?

Not yet — poll GET /api/history?campaign_id=…. Delivery-report sync is on the roadmap.

What is the rate limit?

Requests are limited by your wallet balance and the 500-recipient cap. Avoid more than a few concurrent sends; split large audiences into sequential batches.