SendHub API

SendHub sends WhatsApp messages and SMS for your business. Your system calls a simple JSON API; SendHub queues each message, sends it from your numbers with their limits and pauses, and tells you what happened (sent, delivered, read or failed) by webhook.

• WhatsApp numbers are linked by scanning a QR code, or connected to Meta's official Cloud API.
• SMS numbers are Android phones with a SIM, running the SendHub Sender app.

The API's address (every path below goes after it):

https://your-sendhub/

Requests and answers are JSON (Content-Type: application/json). Times are in UTC (ISO 8601). Phone numbers can be written like 03001234567, +92 300 1234567 or 923001234567; SendHub answers with the international digits (923001234567).

Quick start

1. In the dashboard, open API keys and create a Test key. It starts with wag_test_. Nothing sent with it is really sent, so you can try anything.
2. Send a message:

curl -X POST https://your-sendhub/v1/messages \
  -H "Authorization: Bearer wag_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "03001234567", "text": "Hello from SendHub!"}'

$ch = curl_init('https://your-sendhub/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer wag_test_YOUR_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['to' => '03001234567', 'text' => 'Hello from SendHub!']),
]);
$answer = json_decode(curl_exec($ch), true);
echo $answer['message']['id'], ' ', $answer['message']['status'];   // 42 pending

const res = await fetch('https://your-sendhub/v1/messages', {
    method: 'POST',
    headers: { Authorization: 'Bearer wag_test_YOUR_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ to: '03001234567', text: 'Hello from SendHub!' }),
});
const { message } = await res.json();
console.log(message.id, message.status);   // 42 pending

3. The answer (202) is the queued message. Ask for it again to see how it went, or add a webhook to be told:

curl https://your-sendhub/v1/messages/42 -H "Authorization: Bearer wag_test_YOUR_KEY"

{"message": {"id": 42, "number_id": 1, "channel": "whatsapp", "sandbox": true, "to": "923001234567",
  "text": "Hello from SendHub!", "status": "read", "sent_at": "2026-11-05T09:01:02Z", "delivered_at": "…", "read_at": "…"}}

4. When it works, create a Live key and use it instead. Nothing else changes.

Keys: live and test

Every request sends a key in the Authorization header:

Authorization: Bearer wag_YOUR_KEY

Keys are made, and revoked, by the account owner on the dashboard's API keys page. A key is shown once; SendHub keeps only a hash of it. Keep live keys on your server, never in a web page or app. GET /v1/me says which account and mode a key is for.

Sandbox

With a test key (or the dashboard switched to Sandbox, top left), the same calls work and are checked the same way, but a simulator plays each message's journey instead of sending it. Your webhooks get the same events, with "sandbox": true in their data. Sandbox messages, campaigns and USSD codes are kept apart from live ones, never reach WhatsApp or a phone, and don't count against your plan.

Choose what happens with the last four digits of the number:

Sending messages

POST /v1/messages with one message, or up to 1000 in {"messages": [ … ]}.

One message answers 202 with {"message": {…}}. A batch answers 202 with {"results": [ … ]}, one per message in the same order: {"message": {…}} or {"error": "…"} (the others still go).

curl -X POST https://your-sendhub/v1/messages \
  -H "Authorization: Bearer wag_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"messages": [
        {"number_id": 1, "to": "03001234567", "text": "Dear Ali, the fee of Rs 5000 is due.", "client_ref": "fee-2026-11-17"},
        {"number_id": 1, "to": "03007654321", "text": "Dear Sara, the fee of Rs 4500 is due.", "client_ref": "fee-2026-11-18"}
      ]}'

$messages = [];
foreach ($students as $s) {
    $messages[] = ['number_id' => 1, 'to' => $s['phone'], 'client_ref' => 'fee-2026-11-' . $s['id'],
        'text' => "Dear {$s['name']}, the fee of Rs {$s['fee']} is due."];
}
$ch = curl_init('https://your-sendhub/v1/messages');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer wag_YOUR_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['messages' => $messages])]);
$answer = json_decode(curl_exec($ch), true);
foreach ($answer['results'] as $i => $r) {
    if (isset($r['error'])) { echo $messages[$i]['to'], ': ', $r['error'], "\n"; }
}

const messages = students.map((s) => ({
    number_id: 1, to: s.phone, client_ref: 'fee-2026-11-' + s.id,
    text: `Dear ${s.name}, the fee of Rs ${s.fee} is due.`,
}));
const res = await fetch('https://your-sendhub/v1/messages', {
    method: 'POST',
    headers: { Authorization: 'Bearer wag_YOUR_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ messages }),
});
const { results } = await res.json();
results.forEach((r, i) => r.error && console.log(messages[i].to, r.error));

Messages go out from each number one at a time, with its own pauses, per-minute and daily limits, and quiet hours (set on the number in the dashboard). Sending a thousand messages queues them all at once; they are then sent over time. SMS longer than one part are split: 160 English characters (153 per part when longer), or 70 Urdu / emoji characters (67 per part); the message's parts says how many.

Templates

Save messages you send often on the dashboard's Templates page (or with POST /v1/templates), with {{1}}, {{2}}… for the parts that change, and send them by name:

{"to": "03001234567", "template": {"name": "fee_reminder", "params": ["Ali", "5000", "10 Nov"]}}

The template Dear {{1}}, the fee of Rs {{2}} is due on {{3}}. becomes Dear Ali, the fee of Rs 5000 is due on 10 Nov. This works for SMS and QR-linked WhatsApp numbers. Cloud API numbers use templates approved by Meta instead (GET /v1/numbers/:id/templates), with "language": {"name": "fee_reminder", "language": "en", "params": ["Ali"]}.

Several numbers and fallback

Each message names its number (number_id). To share many messages across several numbers so they go out faster, give each message a different number_id in turn.

Fallback: add "fallback": [5] to try number 5 if the message fails for good on its own number, for example a WhatsApp number first and an SMS number if the person is not on WhatsApp. The same text is sent once more; nothing is sent twice when the first one works.

{"number_id": 1, "fallback": [7], "to": "03001234567", "text": "Your fee is due on 10 Nov."}

The failed message stays failed with retried_as (the new message's id); the new message has fallback_of. A Meta-approved template can only fall back to Cloud API numbers (an SMS has nothing to fill it with); use text or your own template to fall back to SMS.

Campaigns do all this for you with number_ids and send_mode.

Status and the message log

A message's status moves through pending → sending → sent → delivered → read (SMS stops at delivered), or ends as failed (with error) or cancelled. A message that fails for a passing reason is tried again, up to the number's "tries" setting, before it is failed.

Webhooks

A webhook is your URL that SendHub calls when something happens, so you don't have to keep asking. Add it on the dashboard's Webhooks page or with the API (account owner, and a plan with webhooks):

POST /v1/webhooks
{"url": "https://your-site.com/sendhub-webhook", "events": ["message.delivered", "message.failed"]}

Leave out events to get all of them. The answer contains the webhook's secret, shown only this once: keep it to check signatures.

What SendHub sends:

POST https://your-site.com/sendhub-webhook
Content-Type: application/json
X-Webhook-Id: 1234
X-Webhook-Event: message.delivered
X-Signature: t=1762333262,v1=5f8e1c…

{"id": 1234, "event": "message.delivered", "created_at": "2026-11-05T09:01:02Z",
 "data": {"id": 42, "to": "923001234567", "status": "delivered", "client_ref": "fee-2026-11-17", …}}

Answer with any 2xx within 15 seconds. Otherwise SendHub tries again after 10 s, 1 min, 5 min, 30 min, 2 h and 6 h, then gives up (the dashboard shows each call). A retry has the same X-Webhook-Id: use it to ignore duplicates. Events can arrive out of order; trust the times in the message, or ask GET /v1/messages/:id.

Checking a webhook's signature

To be sure a call really comes from SendHub, check its signature: an HMAC-SHA256 of "<t>.<raw body>" with your webhook's secret, where t is the time in the X-Signature header. Use the raw body exactly as received, before parsing it, and refuse calls older than 5 minutes.

$secret = 'YOUR_WEBHOOK_SECRET';
$body = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $_SERVER['HTTP_X_SIGNATURE'] ?? '', $m);
$expected = hash_hmac('sha256', ($m[1] ?? '') . '.' . $body, $secret);
if (!$m || !hash_equals($expected, $m[2]) || abs(time() - (int) $m[1]) > 300) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
if ($event['event'] === 'message.failed') {
    // e.g. mark $event['data']['client_ref'] as not sent
}
http_response_code(200);

// Node.js with Express: keep the raw body for the signature
import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.post('/sendhub-webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const [, t, sig] = (req.get('X-Signature') || '').match(/t=(\d+),v1=([a-f0-9]+)/) || [];
    const expected = crypto.createHmac('sha256', process.env.SENDHUB_WEBHOOK_SECRET).update(t + '.' + req.body).digest('hex');
    const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
    if (!sig || !fresh || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
        return res.sendStatus(401);
    }
    const event = JSON.parse(req.body);
    console.log(event.event, event.data.id, event.data.status);
    res.sendStatus(200);
});

# Signatures are checked on your server; to look at the calls SendHub made:
curl https://your-sendhub/v1/webhooks/1/deliveries -H "Authorization: Bearer wag_YOUR_KEY"

Numbers

Numbers are usually added and linked in the dashboard (scan the QR code, enter Cloud API details, or pair an SMS phone). The API can do it too:

Groups

Lists of people for campaigns: a number, a name, and values for {1}, {2}… in the message.

Campaigns and schedules

A campaign sends one message to groups and/or a list of numbers, now, at a set time, or again every day, week or month. Each person's message is personalised: {name} is their name, {1}, {2}… their values.

curl -X POST https://your-sendhub/v1/campaigns \
  -H "Authorization: Bearer wag_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"name": "November fee reminder", "number_ids": [1, 7], "send_mode": "fallback", "first_channel": "whatsapp",
       "group_ids": [3], "text": "Dear {name}, the fee of Rs {1} is due on {2}.",
       "send_at": "2026-11-20T09:00:00+05:00"}'

$campaign = ['name' => 'November fee reminder', 'number_ids' => [1, 7], 'send_mode' => 'fallback', 'first_channel' => 'whatsapp',
    'group_ids' => [3], 'text' => 'Dear {name}, the fee of Rs {1} is due on {2}.', 'send_at' => '2026-11-20T09:00:00+05:00'];
$ch = curl_init('https://your-sendhub/v1/campaigns');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer wag_YOUR_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($campaign)]);
$c = json_decode(curl_exec($ch), true)['campaign'];
echo $c['id'], ' ', $c['status'];   // 12 scheduled

const res = await fetch('https://your-sendhub/v1/campaigns', {
    method: 'POST',
    headers: { Authorization: 'Bearer wag_YOUR_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({
        name: 'November fee reminder', number_ids: [1, 7], send_mode: 'fallback', first_channel: 'whatsapp',
        group_ids: [3], text: 'Dear {name}, the fee of Rs {1} is due on {2}.', send_at: '2026-11-20T09:00:00+05:00',
    }),
});
const { campaign } = await res.json();

USSD

Run a code like *444# (balance, package status) on your SMS phones and get the network's answer. Only single-step codes: Android gives an app the first answer but no way to choose from a menu.

Or get the answer by webhook: ussd.done / ussd.failed.

Your plan and limits

GET /v1/plan shows your plan, its end date, its allowances, your usage in the current plan cycle (period, usage), this calendar month's messages for reference (month), and the plans on offer (to buy or renew one, see Billing). Allowances count a month at a time from the day your plan started: a plan started on 18 November counts 18 November – 17 December, and so on; a new plan starts a new cycle at zero. When the allowance for a cycle is used up, depending on the plan, new messages are either refused with 402 or accepted and held until the next cycle. Adding more numbers, phones or team members than the plan allows also answers 402; a feature the plan doesn't include answers 403. Test keys are never limited.

Billing and invoices

Plans are paid for outside SendHub (bank transfer, JazzCash, Easypaisa…). The account owner asks for an invoice for a plan and a number of months, pays it with one of the payment methods shown, then uploads the receipt. Once SendHub approves it, the plan starts, or, when it's the same plan, its end date moves on by those months. Most people do this on the dashboard's Plan & usage and Billing pages; the API is the same:

Changing plan

Every invoice has a change:

Errors

Errors answer with a status code and a sentence you can show or log:

{"error": "to must be a phone number"}

All endpoints

With a key (Authorization: Bearer …). Owner-only ones also work with a key.