Dispatch API guide

Getting started

Three steps, about five minutes.

Get your API key

It lives in your portal — you never need to ask us for it.

Authentication

Every request carries one header.

x-api-key: your-api-key-here
Content-Type: application/json

Send a text message

The workhorse. Order confirmations, reminders, OTPs, notifications.

curl -X POST https://dispatch.onebloc.io/send-message \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientPhone": "60123456789",
    "message": "Hi Sarah! Your booking BK-2291 is confirmed ✅"
  }'

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post,
    "https://dispatch.onebloc.io/send-message");
req.Headers.Add("x-api-key", apiKey);
req.Content = JsonContent.Create(new {
    recipientPhone = "60123456789",
    message = "Hi Sarah! Your booking BK-2291 is confirmed ✅"
});
var resp = await http.SendAsync(req);
if (!resp.IsSuccessStatusCode)
    logger.LogWarning("WhatsApp send failed: {Status}", resp.StatusCode);

const res = await fetch('https://dispatch.onebloc.io/send-message', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.DISPATCH_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipientPhone: '60123456789',
    message: 'Hi Sarah! Your booking BK-2291 is confirmed ✅'
  })
});
const data = await res.json();
console.log(data.conversationId, data.tokensRemaining);

$ch = curl_init('https://dispatch.onebloc.io/send-message');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['x-api-key: ' . $apiKey, 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'recipientPhone' => '60123456789',
    'message'        => 'Hi Sarah! Your booking BK-2291 is confirmed ✅'
  ])
]);
$out = json_decode(curl_exec($ch), true);

import requests

r = requests.post(
    "https://dispatch.onebloc.io/send-message",
    headers={"x-api-key": API_KEY},
    json={
        "recipientPhone": "60123456789",
        "message": "Hi Sarah! Your booking BK-2291 is confirmed ✅",
    },
    timeout=15,
)
r.raise_for_status()

Body fields

Response

{
  "success": true,
  "message": "Message queued for delivery",
  "conversationId": "CVS-9A3F-2B71-C044",
  "tokensRemaining": 487,
  "whatsAppStatus": "connected",   // connected | connecting | disconnected | logged_out
  "willDeliver": true          // false = accepted but HELD, going nowhere yet
}

// held because the sending number is logged out
{
  "success": true,
  "message": "Message accepted but HELD — WhatsApp is not connected",
  "whatsAppStatus": "logged_out",
  "willDeliver": false,
  "warning": "This WhatsApp number is logged out and must be re-linked in the portal..."
}

Send a photo

Receipts, site photos, product shots, payment slips.

Two ways to supply the picture. Base64 is the reliable one — the bytes go straight to WhatsApp and there's no URL that can break.

Option A — upload the file itself (recommended)

{
  "recipientPhone": "60123456789",
  "messageType": "image",
  "fileData": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
  "caption": "Payment received ✅ Thank you!"
}

fileData accepts a data: URI or plain base64. In C#: Convert.ToBase64String(bytes). In Node: fs.readFileSync(p).toString('base64').

Option B — a public image URL

{
  "recipientPhone": "60123456789",
  "messageType": "image",
  "message": "https://yoursite.com/photos/unit-a1203.jpg",
  "caption": "Unit A-12-03 after cleaning"
}

Send a PDF or file

Invoices, statements, tenancy agreements, quotations.

{
  "recipientPhone": "60123456789",
  "messageType": "document",
  "fileData": "JVBERi0xLjQKJeLjz9MKM...",
  "fileName": "Invoice-INV-3312.pdf",
  "mimetype": "application/pdf",
  "caption": "Hi! Here's your invoice for August. Thank you 🙏"
}

Send a job to a worker

For field teams — dispatch a task and track its status as the worker replies.

{
  "workerPhone": "601120438890",
  "clientName": "Vista Genting",
  "location": "Unit A-12-03",
  "task": "Deep clean before 11am checkout. Key at reception.",
  "mapLink": "https://maps.google.com/?q=3.4231,101.7935"
}

The worker gets a formatted job card and can reply with a keyword to update it — no app required:

Phone number formats

Send whatever your database has — we normalise it.

A number without a country code is treated as Malaysian. For any other country, include its country code, with or without a +: 6591234567, +1 415 555 0123.

Check if a number is on WhatsApp

Essential for OTP, password resets, and anything that must reach every customer.

Recommended: check once, store the answer

Ask when you first capture the number — at sign-up, or when a customer record is created — and save the result against the customer. Every later message just reads your own flag, so you never sprinkle fallback logic through the rest of your app.

curl "https://dispatch.onebloc.io/check-number?phone=60123456789,60199999999"   -H "x-api-key: YOUR_API_KEY"

{ "success": true, "data": [
    { "phone": "60123456789", "onWhatsApp": true  },
    { "phone": "60199999999", "onWhatsApp": false } ] }

The pattern

// 1. ONCE — when the customer gives you their number
const res  = await fetch(`${DISPATCH}/check-number?phone=${phone}`, { headers: { 'x-api-key': KEY } });
const info = (await res.json()).data[0];
await db.saveCustomer({ phone, hasWhatsApp: info.onWhatsApp });

// 2. EVERYWHERE ELSE — no error handling, just read your own flag
if (customer.hasWhatsApp) await dispatch.send(customer.phone, text);
else                     await sms.send(customer.phone, text);

Safety net: verify at send time

If you'd rather not store anything, add "requireWhatsApp": true to a send. The message is refused with 422 when the recipient has no WhatsApp, and no token is charged — useful as a backstop even when you do pre-check.

{
  "recipientPhone": "60123456789",
  "message": "Your reset code is 481920",
  "requireWhatsApp": true
}

// 422 — not on WhatsApp. Nothing sent, no token used.
{ "error": "Recipient is not on WhatsApp", "code": "NOT_ON_WHATSAPP" }

Post to a WhatsApp group

Reach a whole team in one message, e.g. a job notice to your cleaners' group.

{
  "recipientPhone": "120363041234567890@g.us",
  "message": "🧹 Unit A-12-3 checks out at 11am. Reply to this message when it's cleaned.",
  "referenceId": "CLEAN-12345"
}

// 200
{ "success": true, "groupJid": "120363041234567890@g.us", "groupName": "KL Cleaners",
  "referenceId": "CLEAN-12345", "willDeliver": true, "tokensRemaining": 486 }

Receiving replies (webhooks)

Get every incoming WhatsApp message POSTed to your server in real time.

curl -X POST https://dispatch.onebloc.io/tenant/webhook \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"webhookUrl": "https://yourapp.com/hooks/whatsapp"}'

From then on, every inbound message is POSTed to you:

{
  "event": "message.received",
  "tenantId": "FD152A71-...",
  "timestamp": "2026-08-08T09:14:22.117Z",
  "data": {
    "senderPhone": "60123456789",
    "senderJid":   "60123456789@s.whatsapp.net",
    "isLid":       false,
    "message":     "Paid already, slip attached",
    "messageType": "image",
    "mediaUrl":    "https://dispatch.onebloc.io/tenant/inbox/media/...?token=...",
    "whatsAppMsgId": "3EB0C767D...",
    "referenceId": "INV-3312"
  }
}

Replying to the sender

Take data.senderJid and use it as recipientPhone to reply. It works for every sender, always:

{ "recipientPhone": "60123456789@s.whatsapp.net", "message": "Got it, thank you! ✅" }

Downloading the photo or file

mediaUrl is a signed link, ready to GET with no API key, valid for about an hour. Fetch and store it on your side when the webhook arrives.

Delivery receipts

Know when a message actually reached the phone — and when it was read.

If you've registered a webhook, we push a message.status event each time WhatsApp reports progress on something you sent. No extra setup.

{
  "event": "message.status",
  "data": {
    "status":        "delivered",        // "delivered" then later "read"
    "whatsAppMsgId": "3EB0C767D...",
    "senderPhone":   "60123456789",     // who you sent it to
    "senderJid":     "60123456789@s.whatsapp.net"
  }
}

Receipts also show in your Team Inbox and in the admin console's Messages list, so you can eyeball them without writing code.

Group messages

Get your team's replies, like "done" or a photo of the finished unit, at your webhook.

Groups start switched off, so a busy group can't flood your webhook. Switch on the ones you want in your portal under Groups. Their messages then arrive at your webhook as their own event type, so you'll never mix them up with direct messages:

{
  "event": "group.message.received",
  "data": {
    "groupJid":        "120363041234567890@g.us",
    "groupName":       "KL Cleaners",
    "senderPhone":     "60198887702",        // the member; null when WhatsApp hides their number
    "senderJid":       "60198887702@s.whatsapp.net",
    "pushName":        "Siti",
    "message":         "Done, unit A-12-3 is clean",
    "messageType":     "image",              // text | image | voice | video | document | location
    "mediaUrl":        "https://…/tenant/inbox/media/…?token=…",  // photos + voice notes
    "quotedMessageId": "3EB0C767D…",        // set when they replied to a specific message
    "referenceId":     "CLEAN-12345",        // YOUR id, when they replied to your post
    "mentionsMe":      false                  // true when they @mention your number
  }
}

Which job is this reply about?

A group has many posts going at once, so a bare "done" doesn't tell you much. Ask members to swipe (or long-press) your post and reply to it. That reply comes back with your referenceId, so you can close the right job:

app.post("/hooks/whatsapp", async (req, res) => {
  const { event, data } = req.body;
  if (event === "group.message.received" && data.referenceId) {
    await markCleaningDone(data.referenceId, { by: data.senderPhone, photo: data.mediaUrl });
  }
  res.sendStatus(200);
});

Status & usage

curl https://dispatch.onebloc.io/tenant/status -H "x-api-key: YOUR_API_KEY"

# { "success": true, "data": { "status": "connected", "phoneNumber": "60123456789" } }

Worth calling /tenant/status from your own health check — if it ever reads disconnected, someone needs to re-link the number in the portal.

Token costs

Your daily allowance is counted in tokens, not messages.

Check what's left any time with GET /tenant/usage, or read tokensRemaining on every send response. Counters reset daily.

Errors

Errors always come back as JSON: { "error": "Daily message limit reached", "usage": { "used": 50, "limit": 50 } }

A complete integration

Send a message, handle the failure cases, and receive replies — the whole loop.

// appsettings.json → "Dispatch": { "Url": "...", "ApiKey": "..." }
public sealed class DispatchClient(HttpClient http, IConfiguration cfg, ILogger<DispatchClient> log)
{
    private Uri Endpoint => new($"{cfg["Dispatch:Url"]}/send-message");

    public async Task<bool> SendTextAsync(string phone, string text, CancellationToken ct = default)
        => await PostAsync(new { recipientPhone = phone, message = text }, ct);

    public async Task<bool> SendPdfAsync(string phone, byte[] pdf, string fileName, string caption, CancellationToken ct = default)
        => await PostAsync(new {
               recipientPhone = phone, messageType = "document",
               fileData = Convert.ToBase64String(pdf), fileName, mimetype = "application/pdf", caption
           }, ct);

    private async Task<bool> PostAsync(object body, CancellationToken ct)
    {
        using var req = new HttpRequestMessage(HttpMethod.Post, Endpoint) { Content = JsonContent.Create(body) };
        req.Headers.Add("x-api-key", cfg["Dispatch:ApiKey"]);

        using var resp = await http.SendAsync(req, ct);
        if (resp.IsSuccessStatusCode) return true;

        var detail = await resp.Content.ReadAsStringAsync(ct);
        log.LogWarning("Dispatch send failed ({Status}): {Detail}", (int)resp.StatusCode, detail);
        return false;   // 429 = out of tokens, 500 = WhatsApp not connected
    }
}

const DISPATCH = 'https://dispatch.onebloc.io';

async function send(body) {
  const r = await fetch(`${DISPATCH}/send-message`, {
    method: 'POST',
    headers: { 'x-api-key': process.env.DISPATCH_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  const data = await r.json();
  if (!r.ok) throw new Error(data.error || `HTTP ${r.status}`);
  return data;
}

// receive replies
app.post('/hooks/whatsapp', (req, res) => {
  res.sendStatus(200);                      // ack immediately
  const { senderJid, isLid, senderPhone, message, mediaUrl } = req.body.data;

  queue.push(async () => {
    if (mediaUrl) await downloadAndStore(mediaUrl);   // signed, ~1h
    const phone = isLid ? null : senderPhone;         // only real when isLid=false
    await recordReply({ phone, jid: senderJid, message });
    await send({ recipientPhone: senderJid, message: 'Got it, thank you! ✅' });
  });
});

import os, requests
from flask import Flask, request

DISPATCH = "https://dispatch.onebloc.io"
KEY = os.environ["DISPATCH_KEY"]

def send(**body):
    r = requests.post(f"{DISPATCH}/send-message", headers={"x-api-key": KEY}, json=body, timeout=15)
    if r.status_code == 429:
        raise RuntimeError("out of tokens today")
    r.raise_for_status()
    return r.json()

app = Flask(__name__)

@app.post("/hooks/whatsapp")
def inbound():
    d = request.json["data"]
    phone = None if d["isLid"] else d["senderPhone"]     # may be hidden
    enqueue(save_reply, phone=phone, jid=d["senderJid"], text=d["message"], media=d.get("mediaUrl"))
    return "", 200                                     # ack fast

FAQ