WILCYBERTEK
DOCS v1.0
Back to Gateway Dashboard Get API Key
▶ API Reference Documentation

WilCybertek SMS Gateway API

A direct, low-latency SMS gateway connecting your applications to Zambia's three major mobile networks — MTN, Airtel, and Zamtel — via physical on-premise GSM hardware. No international routing. No hidden relay fees.

All Networks Online TLS 1.3 Encrypted <5s Avg. Delivery REST / JSON

Quickstart

Send your first SMS message in under 5 minutes. Follow these three steps:

1
Register & Get Your API Key
Create a free developer account at wilcybertek.com. Your unique 32-character API key is generated automatically and displayed in your dashboard.
2
Refill Your SMS Credits
Top up your balance via MTN, Airtel, or Zamtel Mobile Money directly from your dashboard. Credits are added instantly after payment confirmation.
3
Make Your First API Call
POST a JSON payload to our endpoint with your API key, a recipient phone number, and your message. That's it.
cURL — Quick Test
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

Every API request must include your unique API Key. This key identifies your account and authorizes credit deduction.

Keep your API key secret. Never expose it in client-side JavaScript, public repositories, or shared environments. Anyone with your key can send messages and drain your credit balance.
You can regenerate your API key at any time from your dashboard. Regenerating immediately invalidates the previous key — update all your integrations before regenerating.

Including Your Key

Include your key in the JSON body of each POST request under the api_key field:

JSON
{
  "api_key": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6",
  "to": "260977000000",
  "message": "Your message here"
}

Send SMS

The primary endpoint for sending a single SMS message to any Zambian mobile number.

POST https://sms.wilcybertek.com/api

Request Parameters

Parameter Type Required Description
api_key string Required Your 32-character developer API key from the dashboard.
to string Required Recipient phone number in international format. E.g. 260977000000. See Phone Formatting.
message string Required The SMS message body. Max 160 characters per SMS. Longer messages are split automatically.
sender_id string Optional Custom sender name (max 11 chars, alphanumeric). Defaults to your registered account name. Subject to network support.

Example Request

PHP
<?php
// Send a single SMS via WilCybertek API
$url = "https://sms.wilcybertek.com/api";

$payload = json_encode([
    "api_key"   => "YOUR_API_KEY",
    "to"        => "260977000000",
    "message"   => "Your account balance is K250.00",
    "sender_id" => "MyBusiness"  // optional
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Content-Type: application/json"]
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['status'] === 'queued') {
    echo "✓ Message queued: " . $response['message_id'];
}

Response

200 OK — Success
{
  "status":     "queued",
  "message_id": "MSG-1712345678-A3F9",
  "recipient":  "260977000000",
  "credits_used": 1,
  "credits_remaining": 249
}
401 Unauthorized — Error
{
  "status":  "error",
  "code":    "INVALID_KEY",
  "message": "The provided API key is invalid or inactive."
}

Bulk SMS

Send the same message to multiple recipients in a single API call. Ideal for marketing campaigns, OTP broadcasts, or system alerts.

POST https://sms.wilcybertek.com/api/bulk
Bulk sends are processed asynchronously. Each message is queued individually and deducts 1 credit. Maximum 500 recipients per bulk request.

Example Request

JSON Body
{
  "api_key": "YOUR_API_KEY",
  "recipients": [
    "260977000001",
    "260966000002",
    "260955000003"
  ],
  "message": "Flash sale! 30% off all services today only."
}

Check Balance

Retrieve your current SMS credit balance programmatically without logging into the dashboard.

GET https://sms.wilcybertek.com/api/balance?api_key=YOUR_KEY
200 OK
{
  "status":  "ok",
  "balance": 249,
  "currency": "SMS_CREDITS"
}

Message Logs

Retrieve a paginated list of your recent message activity including delivery statuses.

GET https://sms.wilcybertek.com/api/logs?api_key=KEY&page=1&limit=50

Query Parameters

ParamTypeDefaultDescription
pageinteger1Page number for pagination.
limitinteger50Results per page. Max 100.
statusstringallFilter by: SENT, FAILED, QUEUED

Supported Networks

WilCybertek routes messages through physical Android gateway hardware with active local SIM cards — ensuring your messages never leave Zambia's mobile network infrastructure.

MTN Zambia
Prefixes: 076, 096, 097
Airtel Zambia
Prefixes: 075, 095, 077
Zamtel
Prefixes: 050, 055, 056
All three networks are active and online. The gateway polls for new messages every 5 seconds, ensuring typical delivery within 5–30 seconds of queueing.

Phone Number Formatting

All phone numbers must be submitted in Zambian international format.

FormatExampleAccepted?
International (recommended) 260977123456 ✅ Yes
With + prefix +260977123456 ✅ Yes (auto-stripped)
Local format 0977123456 ⚠️ Auto-converted
Without country code 977123456 ❌ Will fail

Rate Limits

To maintain fair usage and quality of service across all developers, the following rate limits apply:

Single SMS
120
requests per minute
Bulk SMS
10
bulk requests per minute
Balance / Logs
300
requests per minute
Max Bulk Recipients
500
numbers per bulk call
When you exceed rate limits, the API returns HTTP 429 Too Many Requests. Implement exponential backoff in your retry logic.

Error Codes

All errors return a JSON body with a code and human-readable message field.

HTTP StatusError CodeDescription
400 MISSING_PARAMS One or more required fields are missing from the request body.
401 INVALID_KEY The provided API key is invalid, expired, or has been regenerated.
402 INSUFFICIENT_CREDITS Your credit balance is zero or below the required amount for this request.
400 INVALID_RECIPIENT The phone number is malformed or does not match a supported Zambian network.
422 MESSAGE_TOO_LONG Message exceeds the 1,600 character limit (10 concatenated SMS segments).
429 RATE_LIMITED You have exceeded the API rate limit. Slow down and retry with backoff.
503 GATEWAY_UNAVAILABLE The GSM gateway device is temporarily offline. Messages are queued and will be sent on reconnect.
500 INTERNAL_ERROR An unexpected server-side error occurred. Contact support if this persists.

Security Best Practices

Follow these guidelines to keep your account and your users' data safe.

Never embed your API key in client-side code. Browsers and mobile apps are public. Your key should only live in server-side backend code where users cannot access it.
Rotate your key regularly. Especially if you suspect exposure. Use the Regenerate Key feature in your dashboard — old keys are invalidated immediately.
Use environment variables. Store your API key as an environment variable (WCT_API_KEY) rather than hardcoding it in source files that may end up in version control.
All traffic is TLS 1.3 encrypted. Your requests and our responses are encrypted in transit. API keys are stored using Argon2id hashing — we can never view your plain-text key.

PHP Examples

PHP — Send OTP
<?php
function sendOTP($phone, $otp): bool {
    $url     = "https://sms.wilcybertek.com/api";
    $api_key = getenv("WCT_API_KEY");  // Store in environment

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ["Content-Type: application/json"],
        CURLOPT_POSTFIELDS     => json_encode([
            "api_key" => $api_key,
            "to"      => $phone,
            "message" => "Your verification code is: {$otp}. Valid for 5 minutes."
        ])
    ]);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return ($res['status'] ?? '') === 'queued';
}

// Usage
$otp = rand(100000, 999999);
if (sendOTP("260977000000", $otp)) {
    echo "OTP sent successfully!";
}

Python Examples

Python — Send with requests
import os
import requests

def send_sms(to: str, message: str) -> dict:
    response = requests.post(
        "https://sms.wilcybertek.com/api",
        json={
            "api_key": os.environ["WCT_API_KEY"],
            "to": to,
            "message": message
        },
        timeout=10
    )
    response.raise_for_status()
    return response.json()

# Usage
try:
    result = send_sms("260977000000", "Payment confirmed. Thank you!")
    print(f"Queued: {result['message_id']}")
    print(f"Credits remaining: {result['credits_remaining']}")
except requests.HTTPError as e:
    print(f"API Error: {e.response.json()['message']}")

JavaScript Examples

Node.js — Async/Await
// Never use this in browser-side code!
const sendSMS = async (to, message) => {
  const response = await fetch("https://sms.wilcybertek.com/api", {
    method:  "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: process.env.WCT_API_KEY,
      to,
      message
    })
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.message);
  }

  return response.json();
};

// Usage
sendSMS("260977000000", "Your order is ready for pickup!")
  .then(data => console.log(`Sent: ${data.message_id}`))
  .catch(err => console.error(`Failed: ${err.message}`));

cURL Examples

cURL — Bulk Send
curl -X POST https://sms.wilcybertek.com/api/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "api_key":    "YOUR_API_KEY",
    "recipients": [
      "260977000001",
      "260966000002",
      "260955000003"
    ],
    "message": "System maintenance tonight 22:00-23:00. Thank you for your patience."
  }'
READY TO BUILD?

Start Sending SMS in Minutes

Create your free developer account, get your API key, and connect your application to Zambia's fastest SMS gateway.

Create Free Account View Dashboard