Quickstart

From nothing to a delivered SMS. There’s nothing to install — every step is one request.

Create an account and get your key

Sign up , confirm your phone number and email, then open API Keys in the dashboard. Your key looks like sk_live_ followed by a long string.

New accounts get 5 free SMS, which is enough to finish this page.

The full key is shown once, when it’s created or rotated. Copy it then. We only ever store a hash of it, so we can’t show it to you again — but you can generate a new one whenever you need.

Send your first message

Put your own number in recipients so you can watch it arrive.

curl


curl -X POST https://api.wakalisms.com/sms/send -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" -d '{"recipients":["+254712345678"],"message":"Hello from Wakali SMS"}'

Node.js


const res = await fetch("https://api.wakalisms.com/sms/send", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.WAKALI_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    recipients: ["+254712345678"],
    message: "Hello from Wakali SMS",
  }),
});
 
const data = await res.json();
console.log(data.status, data.cost_kes);

Python


import os, requests
 
res = requests.post(
    "https://api.wakalisms.com/sms/send",
    headers={"X-API-Key": os.environ["WAKALI_API_KEY"]},
    json={
        "recipients": ["+254712345678"],
        "message": "Hello from Wakali SMS",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

PHP


<?php
$ch = curl_init("https://api.wakalisms.com/sms/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: " . getenv("WAKALI_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "recipients" => ["+254712345678"],
        "message"    => "Hello from Wakali SMS",
    ]),
]);
echo curl_exec($ch);

A 202 means we accepted it and your wallet has been charged:


{
  "job_id": "b6b2b6f0-7c21-4b0a-9f3e-2a1d5c7e9b40",
  "recipients_count": 1,
  "cost_kes": 0.45,
  "status": "sent",
  "invalid_recipients": []
}

202 means accepted for delivery, not delivered. Handsets are reached a moment later, and that’s what the next step is for.

Confirm it arrived

Look the message up by the provider id returned with it:


curl https://api.wakalisms.com/sms/messages?page_size=1 -H "X-API-Key: YOUR_KEY"

Each message carries a status:

Status	Meaning
`queued`	With us, on its way to the carrier
`sent`	The carrier accepted it
`delivered`	It reached the handset
`failed`	It didn’t get there — see `provider_status`
`skipped`	A merge tag had no value for this contact, so nothing was sent

Polling is fine while you’re testing. In production, let us tell you instead — see Delivery & webhooks.

Send to more people

recipients takes up to 10,000 numbers in one call, and every format Kenyans actually type is accepted:


curl -X POST https://api.wakalisms.com/sms/send -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" -d '{"recipients":["0712345678","254733123456","+254110456789"],"message":"Doors open at 6pm."}'

Anything we can’t read comes back in invalid_recipients and isn’t charged. The rest still go. See Phone numbers for exactly what we accept.

Before you go live

Register a Sender ID so messages come from your brand rather than a shared name — and read Sender IDs first, because the shared one only reaches Safaricom.
Set up a webhook so you learn about delivery without polling.
Handle errors properly — Handling errors covers what’s worth retrying and what isn’t.
Top up your wallet. A send fails with 402 when the balance won’t cover it, and nothing is sent.

Common first-timer problems

What you see	Why
`401 Invalid or missing credentials`	The key is wrong, or you sent it as `Authorization` instead of `X-API-Key`
`402 Insufficient balance`	Top up on the Wallet page. Nothing was sent and nothing was charged
`422 No valid phone numbers to send to`	None of the numbers parsed — check Phone numbers
Message sent but nothing arrived	Usually the Sender ID doesn’t cover that recipient’s network. See Sender IDs