WilCybertek SMS Gateway

Creating an Account

Every feature on this page — the API, the dashboard, the AI assistant — sits behind a free developer account.

Registering with an email that already has an account redirects you to /login instead of failing silently. Forgot your password? /forgot-password emails a recovery link (valid for 1 hour) to reset it — the response message is intentionally identical whether or not the email exists, so the flow can't be used to find out which emails are registered.

Android Gateway App

The WilCybertek Gateway app turns a spare Android phone into a physical SMS relay on whatever mobile network its SIM card belongs to — anywhere in the world. It's the hardware behind every message this platform sends — install it before your first API call or the message never leaves QUEUED status.

Setup

What's New & Features

Everything the platform does today, in one place.

Gateway app

Sending & reliability

WhatsApp, AI & commerce

Airtel airtime & bundles NEW

Quickstart

Send your first SMS in under 5 minutes.

curl -X POST https://sms.wilcybertek.com/api \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "to":      "260977000000",
    "message": "Hello! This is my first WilCybertek SMS."
  }'

Authentication

The platform uses two independent authentication mechanisms depending on whether you're calling the API or using the web app.

API Key (developer / device endpoints)

Every API and device endpoint below resolves your account from an API key. The key can be supplied in any of these ways, checked in this order — the first one found wins:

X-API-Key: wp_live_a1b2c3d4-e5f6-...

Session Cookie (web dashboard)

Logging in at /login issues a signed session cookie. All dashboard pages (Dashboard, Devices, Messages, Send SMS, AI Assistant) and their POST actions run behind this session — see Security Model for CSRF details. Session-based routes do not accept an API key.

Send SMS

The core endpoint. Queues one SMS for delivery through your default (or a specified) gateway device.

Accepts either application/json or application/x-www-form-urlencoded.

Body Parameters

POST /api HTTP/1.1
Host: sms.wilcybertek.com
Content-Type: application/json
X-API-Key: wp_live_xxxx-xxxx-...

{
  "to": "260977000000",
  "message": "Your order #4821 has shipped.",
  "sim_slot": 0
}

{
  "success": true,
  "id": 4821,
  "status": "QUEUED"
}

Message Status Values

Every queued message moves through this lifecycle. You'll see these values in your dashboard logs and in /update_status.php reports.

Register a Device

Registers (or updates) a gateway device under your account. The official Android app calls this automatically — you only need it directly if you're building a custom gateway client.

{ "success": true }

Push Token Registration

Registers a device's push (Firebase Cloud Messaging) token so it can be woken instantly when a new job is queued, instead of waiting for its next poll.

Job Polling (gateway devices)

Used by a gateway device to ask "do you have a message for me to send?" This is how the Android app fetches queued jobs; build against it directly only if you're writing your own gateway client.

Any active device on the account may claim an unpinned job. The claim is atomic, so two phones can never receive the same message. A job with a device_id only goes to that phone.

{
  "status": "found",
  "id": "4821",
  "phone": "260977000000",
  "message": "Your order #4821 has shipped.",
  "sim_slot": 0
}

{ "status": "none" }

Delivery Status Report

Called by a gateway device after it attempts to send, to report the outcome back to the platform.

Receive Inbound SMS

Called by the gateway app the moment it receives an SMS on the phone, forwarding it into your inbox in real time (single message — see the next section for bulk sync).

Bulk Message Sync

Bulk-syncs a batch of native SMS threads (inbox and/or sent) from the phone into the platform's Messages view. /sync_inbox.php and /sync_messages.php are aliases — both run the exact same handler.

Message Object

{ "success": true, "inserted": 14 }

How OTP Automation Works

Banks, mobile-money portals and carrier self-service sites send a one-time code to a phone number. If that SIM lives in your gateway phone, your server can read the code and finish the login or purchase automatically, with nobody typing it.

Why this needs a "wake" step

Your gateway phone is a normal Android phone. When the screen is off and it hasn't been touched for a while, Android puts apps into a deep-sleep mode (Doze) and some brands (Tecno, Infinix, Xiaomi, etc.) kill background apps outright. A sleeping phone may not upload the incoming SMS for minutes, and by then the OTP has expired.

The wake endpoint sends a high-priority push (Firebase) that Android lets through even in Doze. The app wakes, reads its SMS inbox and uploads new messages immediately. You call it just before you trigger the OTP, so the phone is awake when the code lands.

The 3-step flow

Complete example

import requests
BASE = "https://sms.wilcybertek.com/api/v2/sms"
H = {"X-API-Key": "wp_live_xxxx-xxxx-..."}

# 1. wake the phone so it is ready to receive and upload the SMS
requests.post(BASE + "/wake", headers=H)

# 2. trigger the OTP on the third-party service (your own code)
request_otp_from_portal()

# 3. wait up to 20 s for the new code to arrive
r = requests.get(BASE + "/otp", headers=H, timeout=30, params={
    "sender": "Airtel",          # who sends the OTP
    "purpose": "Bundle Purchase",# text the SMS must contain
    "wait": 20,                  # long-poll seconds (max 25)
    "new": 1,                    # ignore older codes
}).json()

if r["found"]:
    submit_otp_to_portal(r["code"])
else:
    print("No OTP arrived in time")

Wake Devices

Sends a burst of high-priority push messages to every active gateway phone on your account, telling each to sync its SMS inbox right now. Call it just before you trigger an OTP.

Authenticate with the X-API-Key header. No body is needed. Use the header rather than a URL parameter so the key never appears in server or proxy logs.

What it does

Carrier OTPs usually arrive within a few seconds, so repeating the push across 25 seconds makes sure the phone is awake and syncing whenever the SMS lands. The call returns immediately and the burst continues in the background.

curl -X POST https://sms.wilcybertek.com/api/v2/sms/wake \
  -H "X-API-Key: wp_live_xxxx-xxxx-..."

{ "success": true }

Fetch an OTP

Returns the most recent one-time code received on your gateway phones. It can long-poll, so your script makes one call and gets the code as soon as it arrives.

Query Parameters

How the code is found

Only messages that contain a 4 to 8 digit number are considered. The code is the number right after a word like OTP, code, PIN or passcode. If there is no such label, the first 4 to 8 digit number in the SMS is used. Both live-received and bulk-synced messages are searched and duplicates are removed.

curl "https://sms.wilcybertek.com/api/v2/sms/otp?sender=Airtel&purpose=Bundle%20Purchase&wait=20&new=1" \
  -H "X-API-Key: wp_live_xxxx-xxxx-..."

{
  "found": true,
  "code": "327445",
  "sender": "Airtel",
  "message": "Your OTP for Bundle Purchase is 327445. Do not share it.",
  "received_at": "2026-10-18T09:41:12+02:00",
  "codes": [
    { "code": "327445", "sender": "Airtel", "message": "...", "received_at": "..." },
    { "code": "881920", "sender": "Airtel", "message": "...", "received_at": "..." }
  ]
}

{ "found": false }

Verify an OTP

Checks a code typed by a user against the codes actually received on your gateway phone. Use it when your gateway SIM is the destination for the OTP and your application needs to confirm what the user entered.

Body Parameters (JSON)

The code is compared against all recent OTPs from that sender (the last 10), not only the newest. If two OTPs were sent back to back, either one verifies.

curl -X POST https://sms.wilcybertek.com/api/v2/sms/otp/verify \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"sender":"Airtel","code":"327445","purpose":"Bundle Purchase","max_age":300,"wait":8}'

{
  "verified": true,
  "received_at": "2026-10-18T09:41:12+02:00",
  "sender": "Airtel",
  "message": "Your OTP for Bundle Purchase is 327445."
}

{ "verified": false, "reason": "code does not match any recent OTP — it may be wrong or expired" }
// or: "no recent OTP found — it may have expired, request a new one"

Read Inbox

Pull recent inbound messages programmatically. Use these for polling-based integrations, or when you want every message and not just OTPs. For real-time delivery, set a webhook instead.

Returns up to the 50 newest SMS from the last 30 days.

{
  "messages": [
    { "sender": "Airtel", "message": "Your OTP is 327445", "created_at": "2026-10-18T09:41:12+02:00" }
  ]
}

Returns your 50 most recent inbound WhatsApp messages across all your numbers, newest first.

{
  "messages": [
    { "chat_id": "260977000000", "message": "Hi", "status": "...", "created_at": "..." }
  ]
}

API Sandbox NEW

A virtual handset for building and testing your integration before you spend any credit. It uses your API key and the same paths and body fields as the live API. Nothing is sent to a real phone or WhatsApp account, and no credit is used.

How it behaves

Every send appears on the sandbox handset in the dashboard, with delivery states that move from queued to read. Simulated replies arrive on the same handset. Each request is written to the Activity log on the API & terminal page. Sandbox data is kept for 7 days and is separate from your real messages, balance and devices.

SMS

Send an SMS

curl -X POST https://sms.wilcybertek.com/api/v2/sandbox/sms \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." \
  -H "Content-Type: application/json" \
  -d '{"to":"+260977000000","message":"Your order has shipped."}'

{
  "success": true,
  "sandbox": true,
  "id": 318,
  "status": "QUEUED",
  "to": "+260977000000"
}

Send SMS to many numbers

curl -X POST https://sms.wilcybertek.com/api/v2/sandbox/sms/bulk \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+260977000000","0966000000","10123"],"message":"Broadcast message"}'

{
  "success": true,
  "channel": "sms",
  "queued_count": 3,
  "failed_count": 0,
  "queued": [
    { "id": "sbx_319", "to": "+260977000000", "status": "QUEUED" },
    { "id": "sbx_320", "to": "0966000000", "status": "QUEUED" },
    { "id": "sbx_321", "to": "10123", "status": "QUEUED" }
  ],
  "failed": []
}

Read received SMS

Returns up to 50 of the newest received SMS. Add sender to filter by one number or short code. The match ignores upper and lower case.

curl "https://sms.wilcybertek.com/api/v2/sandbox/sms/inbox?sender=10123" \
  -H "X-API-Key: wp_live_xxxx-xxxx-..."

{
  "messages": [
    { "sender": "10123", "message": "Thanks, got it!", "created_at": "2026-10-31T20:48:12+02:00" }
  ]
}

Simulate an incoming SMS

curl -X POST https://sms.wilcybertek.com/api/v2/sandbox/simulate/sms \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." \
  -H "Content-Type: application/json" \
  -d '{"from":"10123","message":"Yes, I want two."}'

WhatsApp

Send a WhatsApp message

curl -X POST https://sms.wilcybertek.com/api/v2/sandbox/whatsapp/send \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." \
  -H "Content-Type: application/json" \
  -d '{"chatId":"260977000000","text":"Hello from the API"}'

{
  "success": true,
  "sandbox": true,
  "id": 322,
  "status": "QUEUED",
  "chatId": "260977000000"
}

Send a WhatsApp message to many chats

curl -X POST https://sms.wilcybertek.com/api/v2/sandbox/whatsapp/send-bulk \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." \
  -H "Content-Type: application/json" \
  -d '{"numbers":["260977000000","260966000000"],"text":"Broadcast message"}'

{
  "success": true,
  "channel": "whatsapp",
  "queued_count": 2,
  "failed_count": 0,
  "queued": [
    { "id": "sbx_323", "to": "260977000000", "status": "QUEUED" },
    { "id": "sbx_324", "to": "260966000000", "status": "QUEUED" }
  ],
  "failed": []
}

Read received WhatsApp messages

Returns up to 50 of the newest received messages across all chats.

curl "https://sms.wilcybertek.com/api/v2/sandbox/whatsapp/inbox" \
  -H "X-API-Key: wp_live_xxxx-xxxx-..."

{
  "messages": [
    { "chat_id": "260977000000", "message": "Hi, is this still available?", "status": "RECEIVED", "created_at": "2026-10-31T20:50:03+02:00" }
  ]
}

Simulate an incoming WhatsApp message

curl -X POST https://sms.wilcybertek.com/api/v2/sandbox/simulate/whatsapp \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." \
  -H "Content-Type: application/json" \
  -d '{"chatId":"260977000000","text":"Payment received. Thank you."}'

Status and Reset

Check delivery status

Pass the id returned by a send, for example sbx_318. The state moves through QUEUED, SENT, DELIVERED and READ.

curl "https://sms.wilcybertek.com/api/v2/sandbox/status?id=sbx_318" \
  -H "X-API-Key: wp_live_xxxx-xxxx-..."

{
  "success": true,
  "id": "sbx_318",
  "channel": "sms",
  "to": "+260977000000",
  "status": "READ"
}

Clear the sandbox

Deletes all sandbox messages and request logs for your account. Your real messages, balance and devices are not affected.

curl -X POST https://sms.wilcybertek.com/api/v2/sandbox/reset \
  -H "X-API-Key: wp_live_xxxx-xxxx-..."

Errors

Where you see it

The API Sandbox page has a separate SMS and WhatsApp section. Each section shows its own handset, so SMS and WhatsApp never appear together. The Devices page shows a Sandbox phone card with counts. The Messages page lists the Sandbox phone next to your real phones, and replies you send from it stay inside the sandbox.

Dashboard

Your account's home base at /dashboard — everything below is a real, working feature, not a placeholder.

Wallet & Top-Up

Buy more SMS credits instantly from the dashboard by card or mobile money, wherever you're topping up from.

Every plan works out to the same rate: 1 credit = US$0.0042. Custom amounts are accepted too, with a US$2.63 minimum per top-up. All prices are in US dollars — cards and mobile money settle in your own currency at the day's rate.

Devices Page

Manage every gateway phone connected to your account at /devices.

Messages & Inbox

A two-way messaging view at /messages — not just an outbox.

Send SMS (Web Form)

A manual, one-off sending form at /send-sms for testing or ad-hoc messages without touching the API — useful for verifying a device is wired up correctly.

Lets you pick a specific active device and SIM slot per send, and debits the same 1-credit-per-message balance as the API.

AI Assistant

A built-in chat assistant, available to logged-in accounts.

Global Network Coverage

WilCybertek isn't tied to any single carrier or country. Because messages go out through a physical Android phone rather than an international SMS relay, coverage is simply whatever your SIM card supports.

Phone Number Formatting

Numbers already in full international format (country code + number, no leading + or 0) are always accepted unchanged. Non-digit characters are stripped before validation.

Rate Limits

Rate limits currently apply to authentication endpoints only, tracked per client IP address. The /api send endpoint and device endpoints are not IP-rate-limited — your SMS balance is the natural throttle.

Error Reference

Actual error payloads returned by the API and device endpoints — every response is JSON with an error field describing what went wrong.

Security Model

WhatsApp

Same API key as SMS. Up to 5 numbers per account, fully isolated from every other developer. Every endpoint below is live today at /api/v2/whatsapp/<path> — add ?id=<number-id> to any request to target a specific number (default: your primary/most-recently-connected number if omitted). Get each number's id from GET /numbers or GET /accounts — see below.

Accounts & Sessions

curl -X POST https://sms.wilcybertek.com/api/v2/whatsapp/numbers \
  -H "X-API-Key: wp_live_xxxx-xxxx-..."
# [{"id":2318,"phone":"260574385641","nickname":"","connected":true,"primary":false}, ...]

curl -X POST "https://sms.wilcybertek.com/api/v2/whatsapp/send?id=2318" \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"chatId":"260772044852","text":"Hello from number 2318"}'

Messaging

Body Parameters

curl -X POST https://sms.wilcybertek.com/api/v2/whatsapp/send \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"chatId":"260977000000","text":"Hello from the API"}'

1 credit per number that actually sends. Failed numbers are not charged.

Body Parameters

curl -X POST https://sms.wilcybertek.com/api/v2/whatsapp/send-bulk \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"numbers":["260977000000","260966000000"],"text":"Broadcast message"}'

Body Parameters

curl -X POST "https://sms.wilcybertek.com/api/v2/whatsapp/upload?id=2318" \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -F "file=@/path/to/file.pdf"
# use the returned "path" as filePath below
curl -X POST "https://sms.wilcybertek.com/api/v2/whatsapp/send-document?id=2318" \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"chatId":"260977000000","filePath":"","caption":"See attached"}'
# voice notes are transcoded to Opus/OGG server-side — same shape, different path
curl -X POST "https://sms.wilcybertek.com/api/v2/whatsapp/send-voice?id=2318" \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"chatId":"260977000000","filePath":""}'

Chats & Search

Groups

Full group lifecycle — create, rename, set description, manage membership and admin roles, and invite links. Group fields use groupId and members, not chatId/participants.

Body Parameters

curl -X POST https://sms.wilcybertek.com/api/v2/whatsapp/group/create \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"name":"Support Team","participants":["260977000000","260966000000"]}'

Channels

One-way broadcast threads (what WhatsApp's own app calls "Channels"). Unlike groups, WhatsApp never exposes individual follower identities to the owner — only a subscriberCount is available, so there is no member-list or remove-member endpoint for channels, on any platform. Name, description, and photo can only be set at creation; there is currently no endpoint to change them afterward.

Body Parameters

curl -X POST https://sms.wilcybertek.com/api/v2/whatsapp/channel/create \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"name":"Company Updates","description":"Product news and outages"}'

Status / Stories

Presence & Receipts

Contacts & Profile

AI Auto-Reply & Scheduling

Webhooks & Events

One URL, shared with SMS, HTTPS only.

Body Parameters

curl -X POST https://sms.wilcybertek.com/api/v2/webhook \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://yourapp.com/hooks/wilcybertek"}'

Airtel Platform: Overview NEW

Buy Airtel Zambia airtime and data / voice / social bundles for any prepaid Airtel number, from a website, from WhatsApp, or from your own code. Everything is controlled from one console that you open from this SMS Gateway, using the same login and the same API key.

Three ways to buy, one set of switches

Airtel Platform: Getting Started NEW

You do not create a separate account. You sign in to this SMS Gateway as usual and open the Airtel console from the menu. The gateway proves who you are to the Airtel platform with a one-time signed link.

Setup checklist shown in Overview

Airtel Platform: Developer Console NEW

Everything you do is scoped to your own account in a signed session. One developer can never see or change another developer's settings, orders or wallets.

Overview

Four live counters (Completed, Failed / expired, Spent, all time, Spent today in Lusaka time), your six most recent orders, the setup checklist, the feature switches and your paying number.

WhatsApp bot

Three steps: gateway connected (automatic), your sales WhatsApp number with country code (for example 260977123456), then Bot enabled. The bot can only be switched on after the key is linked and the sales number is saved. Here you also choose Whitelist only or Open to everyone.

Whitelist

Strangers who message your bot are listed with how many messages they sent. Approve adds them, Dismiss hides the request, and you can add a number with a label or remove one at any time. In Open mode the whitelist is not used.

Orders

Your last 50 purchases from WhatsApp, the API and the website, with order number, time, source, type, recipient, paying number, amount and status. Hover a row to see the failure reason.

Wallets & PINs

Create or change the console PIN, then save, verify and delete paying numbers. See Wallets, PINs & Console PIN.

Integration

Shows your gateway link status, paying number, saved-PIN setting and whether the API is ON or OFF, with a shortcut back to this documentation. Your API key is the same wp_live_... key used for SMS and WhatsApp.

Airtel Platform: Buy Page (Website) NEW

The public page at https://sms.wilcybertek.com lets anyone buy for any prepaid Airtel number in three steps.

Airtel Money payment

Airtel sends a 6-digit code to the paying number. You type it, Airtel confirms it, then you enter your 4-digit Airtel Money PIN to approve the payment. The bundle or airtime is delivered to the recipient straight away.

Signed-in developers get it automatic

When you open the buy page from your console, the page knows you are signed in and uses three developer endpoints behind the scenes:

Airtel Platform: Bundles & Packages NEW

Bundles are fetched live from Airtel for each number, so the list and prices always match what Airtel offers that SIM today. Nothing is hard-coded, which is why new Airtel packages appear without any update here.

How to see every package

Bundle types (Airtel's own categories)

Types are shown in the order above, then alphabetically. Short types (8 plans or fewer) and Social / App types are listed straight away without asking for a plan length.

Plan length

What each package shows

How to get each package, step by step

Airtel Platform: Airtime NEW

Top up any prepaid Airtel number with any whole amount from K1 to K1000 per purchase.

Airtel Platform: Wallets, PINs & Console PIN NEW

A wallet is a paying Airtel Money number with its 4-digit PIN saved encrypted, so purchases need no typing. A separate 6-digit console PIN protects the wallets.

Console PIN

Saving a wallet

Safety rules built in

Airtel Platform: Automatic Code Reading NEW

Airtel confirms every payment with a 6-digit SMS code sent to the paying number. When that SIM sits in your SMS Gateway phone, the platform reads the code for you using the same OTP tools described in OTP Automation.

Airtel Platform: WhatsApp Bot & Whitelist NEW

Your customers chat with your sales WhatsApp number and buy by replying with numbers. The SMS Gateway hands each message to the bot automatically, so you never configure a webhook.

Conversation flow

Commands

Who can use your bot

Airtel API: Authentication & Basics NEW

Buy airtime and bundles programmatically. Every request carries the same wp_live_... key you use for SMS and WhatsApp.

curl https://sms.wilcybertek.com/api/v2/airtel/bundles?msisdn=0977123456 \
  -H "X-API-Key: wp_live_xxxx-xxxx-..."

Endpoints

Number formats

Any of 0977123456, 260977123456 or 977123456 is accepted and cleaned to the 9-digit form.

Order status values

Airtel API: Setup & Line Type NEW

Copy the setup block once, and every example in the sections below runs as written. Pick your language with the tabs. Your choice is remembered for the whole page.

Setup: copy this once

Replace the key with yours from the dashboard. 0977000111 is the recipient, the Airtel number that will receive the airtime or bundle. In JavaScript, run the examples inside an async function or an ES module.

KEY="wp_live_xxxx-xxxx-..."
API="https://sms.wilcybertek.com/api/v2/airtel"
B="$API/bundles?msisdn=0977000111"     # list URL used in the examples

const BASE = "https://sms.wilcybertek.com/api/v2/airtel";
const H = { "X-API-Key": "wp_live_xxxx-xxxx-...", "Content-Type": "application/json" };
const RECIPIENT = "0977000111";

async function api(method, path, body) {
  const r = await fetch(BASE + path, { method, headers: H, body: body ? JSON.stringify(body) : undefined });
  return r.json();
}
function bundles(filters = {}) {
  const qs = new URLSearchParams({ msisdn: RECIPIENT, ...filters });
  return api("GET", "/bundles?" + qs);
}

import time, requests

BASE = "https://sms.wilcybertek.com/api/v2/airtel"
H = {"X-API-Key": "wp_live_xxxx-xxxx-..."}
RECIPIENT = "0977000111"

def api(method, path, **kw):
    return requests.request(method, BASE + path, headers=H, timeout=30, **kw).json()

def bundles(**filters):
    return api("GET", "/bundles", params={"msisdn": RECIPIENT, **filters})

<?php
$BASE = "https://sms.wilcybertek.com/api/v2/airtel";
$KEY  = "wp_live_xxxx-xxxx-...";
$RECIPIENT = "0977000111";

function api($method, $path, $body = null) {
    global $BASE, $KEY;
    $ch = curl_init($BASE . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => ["X-API-Key: $KEY", "Content-Type: application/json"],
        CURLOPT_POSTFIELDS     => $body ? json_encode($body) : null,
    ]);
    $out = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $out;
}
function bundles($filters = []) {
    global $RECIPIENT;
    return api("GET", "/bundles?" . http_build_query(array_merge(["msisdn" => $RECIPIENT], $filters)));
}

Check that a number is prepaid

curl -X POST "$API/line-type" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"msisdn":"0977000111"}'

const r = await api("POST", "/line-type", { msisdn: "0977000111" });
console.log(r.result);          // "PREPAID"
if (r.result !== "PREPAID") throw new Error("Only prepaid Airtel numbers can receive purchases");

r = api("POST", "/line-type", json={"msisdn": "0977000111"})
print(r["result"])              # "PREPAID"
assert r["result"] == "PREPAID", "Only prepaid Airtel numbers can receive purchases"

$r = api("POST", "/line-type", ["msisdn" => "0977000111"]);
echo $r["result"];              // PREPAID
if ($r["result"] !== "PREPAID") { die("Only prepaid Airtel numbers can receive purchases"); }

{ "status": "success", "result": "PREPAID" }

Airtel API: Find the Right Bundle NEW

One endpoint lists everything Airtel offers a number, and optional filters narrow it to exactly what you want. You never guess a product_code: you search, then copy the productCode from the result. Every recipe below has all four languages and the response. These examples use the Setup block.

All filters

All are optional and can be combined. With no filters you get everything. Lists accept commas: category=social,app%20only.

The response, field by field

{
  "status": "success",
  "msisdn": "977000111",
  "total": 64,              // everything Airtel offers this number
  "matched": 2,             // how many passed your filters
  "count": 2,               // how many are in this response
  "filters": { "min_data_gb": "30" },
  "categories": [           // ALL types available, even when you filter
    { "name": "Data",  "count": 30, "from": 2,  "to": 600 },
    { "name": "Combo", "count": 12, "from": 25, "to": 400 },
    { "name": "Voice", "count": 10, "from": 5,  "to": 150 }
  ],
  "result": [
    {
      "productCode": "EXAMPLE30",     // send this to POST /purchase
      "amount": 300,                  // price in ZMW
      "description": "Monthly big data",
      "category": "Data",
      "data": 30, "dataUnit": "GB",
      "voice": 0, "sms": 0,
      "validity": 30, "validityUnit": "days",
      "isBestOffer": false,
      "data_mb": 30720, "data_gb": 30,   // added: no unit conversion needed
      "validity_days": 30,               // added
      "plan": "Monthly",                 // added
      "summary": "30 GB data · 30 days"  // added: ready to show your customer
    }
  ]
}

Recipes: copy the one you need

curl -s "$B" -H "X-API-Key: $KEY"

const r = await bundles();
console.log(r.total + " bundles");
console.table(r.categories);                 // all types with counts and price range
r.result.forEach(b => console.log("K" + b.amount, b.productCode, b.summary));

r = bundles()
print(r["total"], "bundles")
for c in r["categories"]:
    print(c["name"], c["count"], "from K%s to K%s" % (c["from"], c["to"]))
for b in r["result"]:
    print("K%s" % b["amount"], b["productCode"], b["summary"])

$r = bundles();
echo $r["total"] . " bundles\n";
foreach ($r["categories"] as $c) { echo "{$c['name']}: {$c['count']} (K{$c['from']} to K{$c['to']})\n"; }
foreach ($r["result"] as $b) { echo "K{$b['amount']} {$b['productCode']} {$b['summary']}\n"; }

64 bundles
Data   30  from K2 to K600
Combo  12  from K25 to K400
Voice  10  from K5 to K150
K2   D001  100 MB data · 1 day
K20  D020  2 GB data · 7 days
...

curl -s "$B&price=20" -H "X-API-Key: $KEY"

const r = await bundles({ price: 20 });
r.result.forEach(b => console.log(b.productCode, b.category, b.summary));

r = bundles(price=20)
for b in r["result"]:
    print(b["productCode"], b["category"], b["summary"])

$r = bundles(["price" => 20]);
foreach ($r["result"] as $b) { echo "{$b['productCode']} {$b['category']} {$b['summary']}\n"; }

{ "status": "success", "total": 64, "matched": 2, "count": 2,
  "filters": { "price": "20" },
  "result": [
    { "productCode": "D020", "amount": 20, "category": "Data",  "summary": "2 GB data · 7 days" },
    { "productCode": "V020", "amount": 20, "category": "Voice", "summary": "40 min (Airtel only) · 7 days" }
  ] }

curl -s "$B&price=20&category=data" -H "X-API-Key: $KEY"

const r = await bundles({ price: 20, category: "data" });
console.log(r.result);

r = bundles(price=20, category="data")
print(r["result"])

$r = bundles(["price" => 20, "category" => "data"]);
print_r($r["result"]);

curl -s "$B&data_gb=30" -H "X-API-Key: $KEY"

const r = await bundles({ data_gb: 30 });
console.log(r.count ? r.result : "No exact 30GB bundle for this number");

r = bundles(data_gb=30)
print(r["result"] if r["count"] else "No exact 30GB bundle for this number")

$r = bundles(["data_gb" => 30]);
print_r($r["count"] ? $r["result"] : "No exact 30GB bundle for this number");

curl -s "$B&min_data_gb=30&sort=price&limit=1" -H "X-API-Key: $KEY"

const r = await bundles({ min_data_gb: 30, sort: "price", limit: 1 });
const pick = r.result[0];
console.log(pick ? pick.productCode + " " + pick.summary + " K" + pick.amount : "none");

r = bundles(min_data_gb=30, sort="price", limit=1)
pick = r["result"][0] if r["count"] else None
print(pick and "%s %s K%s" % (pick["productCode"], pick["summary"], pick["amount"]))

$r = bundles(["min_data_gb" => 30, "sort" => "price", "limit" => 1]);
$pick = $r["result"][0] ?? null;
echo $pick ? "{$pick['productCode']} {$pick['summary']} K{$pick['amount']}" : "none";

{ "status": "success", "total": 64, "matched": 5, "count": 1,
  "filters": { "min_data_gb": "30", "sort": "price", "limit": "1" },
  "result": [
    { "productCode": "EXAMPLE30", "amount": 300, "category": "Data",
      "data_gb": 30, "validity_days": 30, "summary": "30 GB data · 30 days" }
  ] }

curl -s "$B&min_minutes=100" -H "X-API-Key: $KEY"

const r = await bundles({ min_minutes: 100 });
r.result.forEach(b => console.log("K" + b.amount, b.productCode, b.summary));

for b in bundles(min_minutes=100)["result"]:
    print("K%s" % b["amount"], b["productCode"], b["summary"])

foreach (bundles(["min_minutes" => 100])["result"] as $b) { echo "K{$b['amount']} {$b['productCode']} {$b['summary']}\n"; }

# any bundle that includes SMS
curl -s "$B&has=sms" -H "X-API-Key: $KEY"

# 50 SMS or more
curl -s "$B&min_sms=50" -H "X-API-Key: $KEY"

const anySms  = await bundles({ has: "sms" });
const fiftyUp = await bundles({ min_sms: 50 });
console.log(anySms.count, fiftyUp.result);

any_sms  = bundles(has="sms")
fifty_up = bundles(min_sms=50)
print(any_sms["count"], fifty_up["result"])

$anySms  = bundles(["has" => "sms"]);
$fiftyUp = bundles(["min_sms" => 50]);
echo $anySms["count"]; print_r($fiftyUp["result"]);

curl -s "$B&has=data,voice,sms" -H "X-API-Key: $KEY"

const r = await bundles({ has: "data,voice,sms" });
r.result.forEach(b => console.log("K" + b.amount, b.summary));

for b in bundles(has="data,voice,sms")["result"]:
    print("K%s" % b["amount"], b["summary"])

foreach (bundles(["has" => "data,voice,sms"])["result"] as $b) { echo "K{$b['amount']} {$b['summary']}\n"; }

{ "count": 1, "result": [
  { "productCode": "C100", "amount": 100, "category": "Combo",
    "summary": "5 GB data · 100 min (Airtel only) · 50 SMS · 30 days" } ] }

# daily
curl -s "$B&plan=daily" -H "X-API-Key: $KEY"
# weekly data bundles
curl -s "$B&plan=weekly&category=data" -H "X-API-Key: $KEY"
# valid at least 30 days
curl -s "$B&min_days=30" -H "X-API-Key: $KEY"

const daily   = await bundles({ plan: "daily" });
const weekly  = await bundles({ plan: "weekly", category: "data" });
const thirty  = await bundles({ min_days: 30 });

daily  = bundles(plan="daily")
weekly = bundles(plan="weekly", category="data")
thirty = bundles(min_days=30)

$daily  = bundles(["plan" => "daily"]);
$weekly = bundles(["plan" => "weekly", "category" => "data"]);
$thirty = bundles(["min_days" => 30]);

curl -s "$B&category=social" -H "X-API-Key: $KEY"
curl -s "$B&category=social,app%20only" -H "X-API-Key: $KEY"   # two types together

const social = await bundles({ category: "social" });
const both   = await bundles({ category: "social,app only" });   // spaces are encoded for you

social = bundles(category="social")
both   = bundles(category="social,app only")                     # spaces are encoded for you

$social = bundles(["category" => "social"]);
$both   = bundles(["category" => "social,app only"]);           // http_build_query encodes spaces

curl -s "$B&max_price=50" -H "X-API-Key: $KEY"
curl -s "$B&min_price=30&max_price=100" -H "X-API-Key: $KEY"

const under50 = await bundles({ max_price: 50 });
const range   = await bundles({ min_price: 30, max_price: 100 });

under50 = bundles(max_price=50)
price_range = bundles(min_price=30, max_price=100)

$under50 = bundles(["max_price" => 50]);
$range   = bundles(["min_price" => 30, "max_price" => 100]);

curl -s "$B&q=whatsapp" -H "X-API-Key: $KEY"
curl -s "$B&best_offer=1" -H "X-API-Key: $KEY"

const wa   = await bundles({ q: "whatsapp" });
const best = await bundles({ best_offer: 1 });

wa   = bundles(q="whatsapp")
best = bundles(best_offer=1)

$wa   = bundles(["q" => "whatsapp"]);
$best = bundles(["best_offer" => 1]);

curl -s "$B&product_code=EXAMPLE30" -H "X-API-Key: $KEY"

const ok = (await bundles({ product_code: "EXAMPLE30" })).count > 0;
console.log(ok ? "Available" : "Not offered to this number");

ok = bundles(product_code="EXAMPLE30")["count"] > 0
print("Available" if ok else "Not offered to this number")

$ok = bundles(["product_code" => "EXAMPLE30"])["count"] > 0;
echo $ok ? "Available" : "Not offered to this number";

curl -s "$B&grouped=1" -H "X-API-Key: $KEY"

const r = await bundles({ grouped: 1 });
r.groups.forEach(g => console.log(g.category, g.count, "bundles"));

for g in bundles(grouped=1)["groups"]:
    print(g["category"], g["count"], "bundles")

foreach (bundles(["grouped" => 1])["groups"] as $g) { echo "{$g['category']}: {$g['count']} bundles\n"; }

When there is no match, or several

Airtel API: Purchase NEW

Start an airtime or bundle purchase. The call returns at once with an order_id. Airtel texts a 6-digit code to the paying number, your gateway phone reads it, and the purchase completes in the background. You then poll the order. These examples use the Setup block.

Parameters

Buy a bundle

curl -X POST "$API/purchase" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "type": "bundle",
    "recipient": "0977000111",
    "product_code": "EXAMPLE30",
    "pay_number": "0977123456",
    "pin": "1234",
    "idempotency_key": "order-8843"
  }'

const order = await api("POST", "/purchase", {
  type: "bundle",
  recipient: "0977000111",
  product_code: "EXAMPLE30",       // from the bundle search
  pay_number: "0977123456",
  pin: "1234",                     // leave out when a PIN is saved
  idempotency_key: "order-8843"
});
console.log(order.order_id, order.status);

order = api("POST", "/purchase", json={
    "type": "bundle",
    "recipient": "0977000111",
    "product_code": "EXAMPLE30",   # from the bundle search
    "pay_number": "0977123456",
    "pin": "1234",                 # leave out when a PIN is saved
    "idempotency_key": "order-8843",
})
print(order["order_id"], order["status"])

$order = api("POST", "/purchase", [
    "type" => "bundle",
    "recipient" => "0977000111",
    "product_code" => "EXAMPLE30",   // from the bundle search
    "pay_number" => "0977123456",
    "pin" => "1234",                  // leave out when a PIN is saved
    "idempotency_key" => "order-8843",
]);
echo $order["order_id"] . " " . $order["status"];

Buy airtime: K2, K20, K30, K500 are the same call

curl -X POST "$API/purchase" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "type": "airtime",
    "recipient": "0977000111",
    "amount": 20,
    "pay_number": "0977123456",
    "idempotency_key": "order-8844"
  }'

// change "amount" only: 2, 20, 30, 500 ... any whole number from 1 to 1000
const order = await api("POST", "/purchase", {
  type: "airtime", recipient: "0977000111", amount: 20,
  pay_number: "0977123456", idempotency_key: "order-8844"
});

# change "amount" only: 2, 20, 30, 500 ... any whole number from 1 to 1000
order = api("POST", "/purchase", json={
    "type": "airtime", "recipient": "0977000111", "amount": 20,
    "pay_number": "0977123456", "idempotency_key": "order-8844",
})

// change "amount" only: 2, 20, 30, 500 ... any whole number from 1 to 1000
$order = api("POST", "/purchase", [
    "type" => "airtime", "recipient" => "0977000111", "amount" => 20,
    "pay_number" => "0977123456", "idempotency_key" => "order-8844",
]);

Response

{
  "order_id": 1042,
  "status": "awaiting_otp",
  "type": "bundle",
  "recipient": "977000111",
  "pay_number": "977123456",
  "amount": 300,
  "message": "Airtel sent a code to +260 977123456. It is being read from your phone. Check GET /api/v2/airtel/orders/1042 every few seconds. If auto-verification is off, send the code to POST /api/v2/airtel/orders/1042/otp."
}

{ "status": "error", "error": "unknown_bundle",
  "message": "That bundle is not available for this number. List them with GET /api/v2/airtel/bundles." }

Airtel API: Orders & Manual Code NEW

Track a purchase by its order_id, wait for the final result, and send the 6-digit code yourself when automatic reading is OFF. These examples use the Setup block.

Check an order

curl "$API/orders/1042" -H "X-API-Key: $KEY"

const o = await api("GET", "/orders/1042");
console.log(o.status, o.message);

o = api("GET", "/orders/1042")
print(o["status"], o["message"])

$o = api("GET", "/orders/1042");
echo $o["status"] . " " . $o["message"];

{ "order_id": 1042, "status": "completed", "type": "bundle",
  "recipient": "977000111", "pay_number": "977123456", "amount": 300,
  "message": "Purchase completed." }

{ "order_id": 1043, "status": "failed", "type": "airtime",
  "recipient": "977000111", "pay_number": "977123456", "amount": 20,
  "message": "Purchase failed: Incorrect PIN. Use a new idempotency_key to try again." }

Wait until it finishes

Poll every 4 seconds. Stop on completed, failed or expired. Do not stop on processing, because Airtel has not answered yet.

while true; do
  S=$(curl -s "$API/orders/1042" -H "X-API-Key: $KEY" | jq -r .status)
  echo "$S"
  case "$S" in completed|failed|expired) break;; esac
  sleep 4
done

async function waitForOrder(id) {
  for (let i = 0; i < 60; i++) {                       // about 4 minutes
    const o = await api("GET", "/orders/" + id);
    if (["completed", "failed", "expired"].includes(o.status)) return o;
    await new Promise(r => setTimeout(r, 4000));
  }
  throw new Error("Still not final. Check order " + id + " again later. Do NOT create a new order.");
}
const done = await waitForOrder(1042);
console.log(done.status, done.message);

def wait_for_order(order_id):
    for _ in range(60):                                   # about 4 minutes
        o = api("GET", "/orders/%s" % order_id)
        if o["status"] in ("completed", "failed", "expired"):
            return o
        time.sleep(4)
    raise TimeoutError("Still not final. Check order %s again later. Do NOT create a new order." % order_id)

done = wait_for_order(1042)
print(done["status"], done["message"])

function waitForOrder($id) {
    for ($i = 0; $i < 60; $i++) {                        // about 4 minutes
        $o = api("GET", "/orders/$id");
        if (in_array($o["status"], ["completed", "failed", "expired"])) { return $o; }
        sleep(4);
    }
    throw new Exception("Still not final. Check order $id again later. Do NOT create a new order.");
}
$done = waitForOrder(1042);
echo $done["status"] . " " . $done["message"];

Send the code yourself

Use this when the order is awaiting_otp and automatic reading is OFF, or the paying SIM is not in your gateway phone. Send the 6-digit code from the Airtel SMS.

curl -X POST "$API/orders/1042/otp" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"otp":"123456","pin":"1234"}'

const r = await api("POST", "/orders/1042/otp", { otp: "123456", pin: "1234" });
console.log(r.status, r.message);

r = api("POST", "/orders/1042/otp", json={"otp": "123456", "pin": "1234"})
print(r["status"], r["message"])

$r = api("POST", "/orders/1042/otp", ["otp" => "123456", "pin" => "1234"]);
echo $r["status"] . " " . $r["message"];

{ "order_id": 1042, "status": "completed", "type": "bundle",
  "recipient": "977000111", "pay_number": "977123456", "amount": 300,
  "message": "Purchase completed." }

{ "order_id": 1042, "status": "awaiting_otp", "type": "bundle",
  "recipient": "977000111", "pay_number": "977123456", "amount": 300,
  "message": "Airtel did not accept that code. Send the latest 6-digit code from your SMS." }

Complete example: a customer asks for 30GB

Search, pick the cheapest match, buy, and wait for the result.

# 1. find the cheapest 30GB or more and keep its code
CODE=$(curl -s "$B&min_data_gb=30&limit=1" -H "X-API-Key: $KEY" | jq -r '.result[0].productCode')

# 2. buy it
curl -X POST "$API/purchase" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"type\":\"bundle\",\"recipient\":\"0977000111\",\"product_code\":\"$CODE\",
       \"pay_number\":\"0977123456\",\"idempotency_key\":\"order-9500\"}"

# 3. check it (use the order_id from step 2)
curl "$API/orders/1042" -H "X-API-Key: $KEY"

async function sell30GB(payNumber, orderId) {
  const found = await bundles({ min_data_gb: 30, sort: "price", limit: 1 });
  if (!found.count) return { ok: false, reason: "No 30GB bundle. Types: " + found.categories.map(c => c.name).join(", ") };

  const pick = found.result[0];
  const order = await api("POST", "/purchase", {
    type: "bundle", recipient: RECIPIENT, product_code: pick.productCode,
    pay_number: payNumber, idempotency_key: orderId
  });
  if (!order.order_id) return { ok: false, reason: order.message };

  const done = await waitForOrder(order.order_id);        // from the section above
  return { ok: done.status === "completed", bundle: pick.summary, price: pick.amount, status: done.status };
}
console.log(await sell30GB("0977123456", "order-9500"));

def sell_30gb(pay_number, order_id):
    found = bundles(min_data_gb=30, sort="price", limit=1)
    if not found["count"]:
        return {"ok": False, "reason": "No 30GB bundle. Types: " + ", ".join(c["name"] for c in found["categories"])}

    pick = found["result"][0]
    order = api("POST", "/purchase", json={
        "type": "bundle", "recipient": RECIPIENT, "product_code": pick["productCode"],
        "pay_number": pay_number, "idempotency_key": order_id})
    if "order_id" not in order:
        return {"ok": False, "reason": order.get("message")}

    done = wait_for_order(order["order_id"])              # from the section above
    return {"ok": done["status"] == "completed", "bundle": pick["summary"], "price": pick["amount"], "status": done["status"]}

print(sell_30gb("0977123456", "order-9500"))

function sell30GB($payNumber, $orderId) {
    global $RECIPIENT;
    $found = bundles(["min_data_gb" => 30, "sort" => "price", "limit" => 1]);
    if (!$found["count"]) {
        return ["ok" => false, "reason" => "No 30GB bundle. Types: " . implode(", ", array_column($found["categories"], "name"))];
    }
    $pick = $found["result"][0];
    $order = api("POST", "/purchase", [
        "type" => "bundle", "recipient" => $RECIPIENT, "product_code" => $pick["productCode"],
        "pay_number" => $payNumber, "idempotency_key" => $orderId,
    ]);
    if (empty($order["order_id"])) { return ["ok" => false, "reason" => $order["message"] ?? "failed"]; }

    $done = waitForOrder($order["order_id"]);             // from the section above
    return ["ok" => $done["status"] === "completed", "bundle" => $pick["summary"], "price" => $pick["amount"], "status" => $done["status"]];
}
print_r(sell30GB("0977123456", "order-9500"));

Airtel API: Wallet NEW

Save a paying number and its Airtel Money PIN (stored encrypted) so purchases do not need a pin field. Needs Saved PINs switched ON in the console, otherwise you get saving_disabled (403). These examples use the Setup block.

Save a wallet

curl -X POST "$API/wallet" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"pay_number":"0977123456","pin":"1234"}'

const r = await api("POST", "/wallet", { pay_number: "0977123456", pin: "1234" });
console.log(r.message);

r = api("POST", "/wallet", json={"pay_number": "0977123456", "pin": "1234"})
print(r["message"])

$r = api("POST", "/wallet", ["pay_number" => "0977123456", "pin" => "1234"]);
echo $r["message"];

{ "status": "success", "pay_number": "977123456", "pin_verified": false,
  "message": "Saved. It will be used for purchases from this number." }

Then buy with no PIN

curl -X POST "$API/purchase" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"type":"airtime","recipient":"0977000111","amount":10,
       "pay_number":"0977123456","idempotency_key":"order-9001"}'

await api("POST", "/purchase", { type: "airtime", recipient: "0977000111", amount: 10,
                                 pay_number: "0977123456", idempotency_key: "order-9001" });

api("POST", "/purchase", json={"type": "airtime", "recipient": "0977000111", "amount": 10,
                               "pay_number": "0977123456", "idempotency_key": "order-9001"})

api("POST", "/purchase", ["type" => "airtime", "recipient" => "0977000111", "amount" => 10,
                          "pay_number" => "0977123456", "idempotency_key" => "order-9001"]);

Remove a wallet

curl -X DELETE "$API/wallet?pay_number=0977123456" -H "X-API-Key: $KEY"

await api("DELETE", "/wallet?pay_number=0977123456");

api("DELETE", "/wallet", params={"pay_number": "0977123456"})

api("DELETE", "/wallet?pay_number=0977123456");

Airtel API: Whitelist NEW

Manage from code which WhatsApp numbers may use your Airtel bot. It only matters when the bot is set to Whitelist only. In Open mode everyone is allowed. These examples use the Setup block.

List approved numbers

curl "$API/allowlist" -H "X-API-Key: $KEY"

const r = await api("GET", "/allowlist");
r.numbers.forEach(n => console.log(n.number, n.label));

for n in api("GET", "/allowlist")["numbers"]:
    print(n["number"], n["label"])

foreach (api("GET", "/allowlist")["numbers"] as $n) { echo "{$n['number']} {$n['label']}\n"; }

{ "status": "success", "count": 2,
  "numbers": [ { "number": "260977123456", "label": "John (shop)" },
               { "number": "260966000111", "label": "" } ] }

Approve one number

* Send number or numbers. Approving a number that is already listed just updates its label.

curl -X POST "$API/allowlist" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"number":"0977123456","label":"John (shop)"}'

await api("POST", "/allowlist", { number: "0977123456", label: "John (shop)" });

api("POST", "/allowlist", json={"number": "0977123456", "label": "John (shop)"})

api("POST", "/allowlist", ["number" => "0977123456", "label" => "John (shop)"]);

Approve many numbers at once

curl -X POST "$API/allowlist" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"numbers":[
        {"number":"260977123456","label":"John"},
        {"number":"260966000111","label":"Mary"},
        {"number":"12"}
      ]}'

const r = await api("POST", "/allowlist", { numbers: [
  { number: "260977123456", label: "John" },
  { number: "260966000111", label: "Mary" },
  { number: "12" }                                   // too short: reported in "invalid"
] });
console.log(r.added, r.invalid);

r = api("POST", "/allowlist", json={"numbers": [
    {"number": "260977123456", "label": "John"},
    {"number": "260966000111", "label": "Mary"},
    {"number": "12"},                                # too short: reported in "invalid"
]})
print(r["added"], r["invalid"])

$r = api("POST", "/allowlist", ["numbers" => [
    ["number" => "260977123456", "label" => "John"],
    ["number" => "260966000111", "label" => "Mary"],
    ["number" => "12"],                              // too short: reported in "invalid"
]]);
print_r($r["added"]); print_r($r["invalid"]);

{ "status": "success",
  "added": ["260977123456", "260966000111"],
  "invalid": ["12"],
  "message": "Whitelisted. These numbers can now use your WhatsApp bot." }

Remove a number

curl -X DELETE "$API/allowlist?number=260977123456" -H "X-API-Key: $KEY"

await api("DELETE", "/allowlist?number=260977123456");

api("DELETE", "/allowlist", params={"number": "260977123456"})

api("DELETE", "/allowlist?number=260977123456");

Airtel Platform: Error Reference NEW

Every API error has the shape {"status":"error","error":"code","message":"..."}.

Why a purchase can fail

Wrong Airtel Money PIN (the saved PIN is then removed), not enough Airtel Money balance, no code received within 3 minutes, or Airtel declining the transaction. The reason is saved on the order and shown in the console. Check your balance before retrying a processing order.

Airtel Platform: Security Model NEW

Money and PINs are involved, so every layer is locked down.

Airtel API: Code Examples NEW

Copy, paste, replace the key. Each example lists or buys, then checks the order.

JavaScript: list all bundles, buy, poll

const BASE = "https://sms.wilcybertek.com/api/v2/airtel";
const H = { "X-API-Key": "wp_live_xxxx-xxxx-...", "Content-Type": "application/json" };

// 1. list every bundle, grouped by type
const list = await (await fetch(BASE + "/bundles?msisdn=0977123456", { headers: H })).json();
const byType = {};
for (const b of list.result) (byType[b.category || "Other"] ||= []).push(b);
console.table(Object.entries(byType).map(([t, a]) => ({ type: t, plans: a.length })));

// 2. buy one
const buy = await (await fetch(BASE + "/purchase", {
  method: "POST", headers: H,
  body: JSON.stringify({ type: "bundle", recipient: "0977000111", product_code: list.result[0].productCode,
                         pay_number: "0977123456", idempotency_key: "order-" + Date.now() })
})).json();

// 3. poll until it finishes
let o = buy;
while (["created", "awaiting_otp", "processing"].includes(o.status)) {
  await new Promise(r => setTimeout(r, 4000));
  o = await (await fetch(BASE + "/orders/" + buy.order_id, { headers: H })).json();
}
console.log(o.status, o.message);

Python: airtime

import time, requests
BASE = "https://sms.wilcybertek.com/api/v2/airtel"
H = {"X-API-Key": "wp_live_xxxx-xxxx-..."}

# airtime
r = requests.post(BASE + "/purchase", headers=H, json={
    "type": "airtime", "recipient": "0977000111", "amount": 20,
    "pay_number": "0977123456", "idempotency_key": "order-8842"}).json()

# poll
while r.get("status") in ("created", "awaiting_otp", "processing"):
    time.sleep(4)
    r = requests.get(BASE + "/orders/%s" % r["order_id"], headers=H).json()
print(r["status"], r["message"])

PHP: airtime

<?php
$base = "https://sms.wilcybertek.com/api/v2/airtel";
$ch = curl_init($base . "/purchase");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: wp_live_xxxx-xxxx-...", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode([
    "type" => "airtime", "recipient" => "0977000111", "amount" => 20,
    "pay_number" => "0977123456", "idempotency_key" => "order-8842"
  ]),
]);
$order = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $order["status"] . " - " . $order["message"];

cURL: save a wallet, then buy without a PIN

curl -X POST https://sms.wilcybertek.com/api/v2/airtel/wallet \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"pay_number":"0977123456","pin":"1234"}'

curl -X POST https://sms.wilcybertek.com/api/v2/airtel/purchase \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." -H "Content-Type: application/json" \
  -d '{"type":"airtime","recipient":"0977000111","amount":10,
       "pay_number":"0977123456","idempotency_key":"order-9001"}'

cURL

curl -X POST https://sms.wilcybertek.com/api \
  -H "X-API-Key: wp_live_xxxx-xxxx-..." \
  -H "Content-Type: application/json" \
  -d '{"to":"260977000000","message":"Hello from cURL"}'

JavaScript (fetch)

const res = await fetch("https://sms.wilcybertek.com/api", {
  method: "POST",
  headers: {
    "X-API-Key": "wp_live_xxxx-xxxx-...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    to: "260977000000",
    message: "Hello from JavaScript"
  })
});
const data = await res.json();
console.log(data);

Python

import requests

resp = requests.post(
    "https://sms.wilcybertek.com/api",
    headers={"X-API-Key": "wp_live_xxxx-xxxx-..."},
    json={"to": "260977000000", "message": "Hello from Python"},
)
print(resp.json())

PHP

<?php
$ch = curl_init("https://sms.wilcybertek.com/api");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: wp_live_xxxx-xxxx-...",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "to" => "260977000000",
        "message" => "Hello from PHP",
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;