API Documentation

Follow these steps to start sending SMS in under 5 minutes:

1. **Sign in** with the account your reseller or the platform owner created for you

2. **Resellers:** add your Android devices from the Devices page

3. **Resellers:** create clients and assign devices to them (specific device or automatic round-robin)

4. **Generate an API key** from the dashboard

5. **Start sending** SMS from the dashboard or API

Send an SMS message using a simple POST request:

POST /api/v1/gateway/send-sms

Headers:
  x-api-key: YOUR_API_KEY
  Content-Type: application/json

Body:
{
  "recipients": ["+12025550123"],
  "message": "Your verification code is 482913",
  "clientRef": "order-1234"
}

The device that sends the message is resolved server-side: clients automatically use the device(s) their reseller assigned (round-robin by default).

**Idempotency:** pass an optional `clientRef` string (unique per account) to make sends safe to retry. If a request times out and you retry with the same ref, the original message is returned instead of sending a duplicate — the response includes `"duplicate": true` when a replay happens. Quota is charged only once.

**OTP & verification focus:** self-serve customer accounts send OTP and verification messages — a numeric code (4–8 digits) and no links. Reseller-managed client accounts can send any content (OTP, transactional, or marketing) through their assigned senders.

Enable SMS receiving in the mobile app, then access incoming messages via:

REST API:

GET /api/v1/gateway/messages?direction=received

Headers:
  x-api-key: YOUR_API_KEY

**Webhooks:** Configure a webhook URL in your dashboard to receive real-time notifications when messages arrive.

This is how a client sends SMS from their own website. You only need two things: your API key (Dashboard → API Keys → Generate Key) and your koipabo URL.

Step 1 — Get your API key

Sign in, go to **API Keys**, click **Generate Key**, and copy the key that starts with `tb_`. Treat it like a password.

Step 2 — Call the API from your backend

curl -X POST https://api.koipabo.com/api/v1/gateway/send-sms \
  -H "x-api-key: tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"recipients": ["+12025550123"], "message": "Your verification code is 482913"}'

> **Non-masking only:** messages are sent from the phone number of the device that carries them — there is no branded sender ID. Your recipients will see that number, so send from a number you're comfortable sharing.

Node.js (Next.js API route, Express, etc.)

// Store the key in your server environment, never in the browser
const KOIPABO_KEY = process.env.KOIPABO_API_KEY;

async function sendSms(recipients, message) {
  const res = await fetch("https://api.koipabo.com/api/v1/gateway/send-sms", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": KOIPABO_KEY,
    },
    body: JSON.stringify({ recipients, message, clientRef: "order-" + orderId }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error);
  return data;
}

Python (Flask, Django, FastAPI)

import requests

resp = requests.post(
    "https://api.koipabo.com/api/v1/gateway/send-sms",
    headers={"x-api-key": "tb_your_api_key"},
    json={"recipients": ["+12025550123"], "message": "Your verification code is 482913"},
)
print(resp.json())

PHP

$ch = curl_init("https://api.koipabo.com/api/v1/gateway/send-sms");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json", "x-api-key: tb_your_api_key"],
    CURLOPT_POSTFIELDS => json_encode([
        "recipients" => ["+12025550123"],
        "message" => "Your verification code is 482913",
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);

**Important — keep your key server-side.** Never put the `x-api-key` header in browser JavaScript: anyone can open your page source and steal it. If your site is a static frontend with no backend, add a tiny serverless function (Next.js API route, Vercel/Netlify function, Cloudflare Worker) that holds the key and forwards the request.

That is it — the device that sends the SMS is chosen automatically by your reseller's assignment, so your website does not need to know anything about phones.

Send to multiple recipients in a single API call:

POST /api/v1/gateway/send-sms

{
  "recipients": [
    "+12025550123",
    "+12025550456",
    "+12025550789"
  ],
  "message": "Your verification code is 482913"
}

API keys authenticate your requests. You can create unlimited keys per account.

• **Create:** Dashboard → API Keys → Generate Key

• **Use:** Pass as `x-api-key` header in all API requests

• **Rotate:** Generate a new key and update your applications

• **Revoke:** Delete keys you no longer need

**Security tip:** Never expose API keys in client-side code. Always use them server-side.

Configure webhooks to receive real-time notifications:

1. Go to Dashboard → Webhooks

2. Add your endpoint URL

3. Select events to subscribe to

4. koipabo will POST a JSON payload to your URL when events occur

Payload format:

{
  "event": "message.received",
  "data": {
    "from": "+12025550123",
    "message": "Reply text",
    "receivedAt": "2024-01-15T10:30:00Z"
  }
}

Turn any Android phone into a sending device with the Koipabo Gateway app (source: `flutter/` in this repo). Download the APK from the [Download page](/download) — it works on **Android 7.0 (Nougat) or newer**, including 32-bit and 64-bit phones, and is distributed from this website (not Google Play).

Pairing flow (QR code):

1. **Dashboard → Devices → Register Device** (resellers / super admins)

2. The pairing QR code is shown immediately — or click the QR icon on any existing device

3. Install and open the Koipabo Gateway app on the phone

4. Tap **Scan QR code** and point it at the QR

**How pairing works:** the QR encodes a pairing URL like `https://your-server/api/v1/device/pair?token=...`. The app learns the server address from the URL itself — no passwords in the QR, no hardcoded URLs. The same flow works against localhost during development and your public domain in production. The one-time token (5 minute expiry) is exchanged for a permanent device token the app stores.

**SIM selection:** after pairing, the app lists every SIM slot on the phone and asks which SIMs may send SMS. Toggle any SIM on or off anytime from the app's home screen — messages are spread (round-robin) across the enabled SIMs. The chosen SIMs are also reported to the server so resellers can see them on the Devices page.

**How messages flow:** when an SMS is queued for the device, the app polls it, sends it via an enabled SIM, and reports `sent`/`failed` back.

**Device API** (authenticated with `Authorization: Bearer <deviceToken>`):

POST /api/v1/device/pair           # exchange one-time token for a device token
POST /api/v1/device/heartbeat      # report liveness + SIM slots (every ~60s)
GET  /api/v1/device/messages       # fetch queued messages for this device
POST /api/v1/device/messages/{id}/status   # report sent/failed

**Building the app:** `cd flutter && flutter build apk --release`, then copy the APK into `apk-file/` at the repo root — the public download page serves it automatically. Development builds allow plain http:// (localhost / LAN) via `usesCleartextTraffic`; switch to HTTPS for production.