Lihini SMS API

Send SMS through your own Android phones. You queue a message with one HTTP call; your phone sends it within seconds and reports back.

Quick start

Base URL: https://lihini.calmray.team. Every request and response is JSON.

Prefer clicking? Everything here is also in your dashboard: send SMS, follow messages, manage phones and rotate your key.
  1. Get your API key (sk_…) and a pair code from the Lihini admin.
  2. Install the Lihini app on your phone, enter the pair code, and tap Allow running in background.
  3. Send your first SMS:
curl -X POST https://lihini.calmray.team/v1/messages \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"to":"+94771234567","body":"Hello from Lihini"}'

Response 202 Accepted:

{"id": 1042, "status": "queued", "duplicate": false}

Authentication

Send your API key as a Bearer token on every request:

Authorization: Bearer sk_your_key
Keep the key on your server only. Never put it in a mobile app, a website's JavaScript, or a public repo. If it leaks, ask the admin to revoke it and issue a new one.

Send SMS

POST/v1/messages

Body fields

FieldTypeDescription
tostringrequiredPhone number, +94771234567 or 0771234567. Spaces, dashes and brackets are ignored. 6–15 digits.
bodystringrequiredMessage text, 1–1600 characters. Long texts are split into parts automatically. Unicode (Sinhala, Tamil, emoji) is supported but uses shorter parts (70 chars vs 160).
device_idintegeroptionalSend only through this phone of yours (see Your phones). Leave out to use any of your phones.
idempotency_keystringoptionalYour own unique ID, up to 128 chars. Sending the same key again returns the first message instead of creating a duplicate. Use it whenever you retry a request. Also accepted as an Idempotency-Key header.
webhook_urlstringoptionalWe POST status changes here. See Webhooks.

Batch

Send up to 500 messages in one call. A top-level device_id applies to every message that doesn't set its own.

{
  "device_id": 3,
  "messages": [
    {"to": "+94771234567", "body": "Your appointment is at 10:00", "idempotency_key": "appt-881"},
    {"to": "+94712345678", "body": "Your appointment is at 10:30", "idempotency_key": "appt-882"}
  ]
}

Response 202, in the same order:

{"messages": [
  {"id": 1043, "status": "queued", "duplicate": false},
  {"id": 1044, "status": "queued", "duplicate": false}
]}

If any message is invalid, nothing is queued and you get 400 with the position of the bad one: {"error": "invalid \"to\"", "index": 1}.

Examples

curl -X POST https://lihini.calmray.team/v1/messages \
  -H "Authorization: Bearer $LIHINI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+94771234567","body":"Your OTP is 4821","idempotency_key":"otp-5521"}'
<?php
function lihini_send(string $to, string $body, ?string $idempotencyKey = null): array
{
    $ch = curl_init('https://lihini.calmray.team/v1/messages');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('LIHINI_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode(array_filter([
            'to' => $to, 'body' => $body, 'idempotency_key' => $idempotencyKey,
        ])),
    ]);
    $res = json_decode(curl_exec($ch), true);
    $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($code !== 202) throw new RuntimeException('Lihini: ' . ($res['error'] ?? "HTTP $code"));
    return $res; // ['id' => 1042, 'status' => 'queued', ...]
}

$msg = lihini_send('+94771234567', 'Your OTP is 4821', 'otp-5521');
// Node 18+ (server side only: never expose your key in a browser)
async function lihiniSend(to, body, idempotencyKey) {
  const res = await fetch("https://lihini.calmray.team/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LIHINI_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ to, body, idempotency_key: idempotencyKey }),
  });
  const data = await res.json();
  if (res.status !== 202) throw new Error(`Lihini: ${data.error ?? res.status}`);
  return data; // { id, status: "queued", duplicate }
}

await lihiniSend("+94771234567", "Your OTP is 4821", "otp-5521");
import os, requests

def lihini_send(to, body, idempotency_key=None):
    r = requests.post(
        "https://lihini.calmray.team/v1/messages",
        headers={"Authorization": f"Bearer {os.environ['LIHINI_KEY']}"},
        json={"to": to, "body": body, "idempotency_key": idempotency_key},
        timeout=15,
    )
    data = r.json()
    if r.status_code != 202:
        raise RuntimeError(f"Lihini: {data.get('error', r.status_code)}")
    return data  # {"id": ..., "status": "queued", ...}

lihini_send("+94771234567", "Your OTP is 4821", "otp-5521")

Bulk jobs (up to 5,000)

For big sends, create a batch, then add messages in chunks of up to 1,000. Messages start sending as soon as each chunk is added. The dashboard's Bulk tab does the same from a CSV or Excel file.

POST/v1/batches body {"name": "September promo", "device_id": 3, "expected": 3000} (all optional) → 201 with the batch. Set expected to the number of messages you'll add: until they've all arrived, the batch's state is adding. If your upload stops early, the batch gets "incomplete": true.

POST/v1/batches/{id}/messages body {"messages": [{"to": "…", "body": "…"}, …]} (1–1,000 per call, 5,000 per batch) → {"added": 1000, "total": 3000}

{
  "id": 12, "name": "September promo", "state": "running", "total": 3000,
  "counts": {"queued": 1850, "sending": 20, "sent": 400, "delivered": 700, "failed": 30, "cancelled": 0},
  "target_device_id": 3, "created_at": "…", "first_sent_at": "…", "last_sent_at": "…"
}

GET/v1/batches lists your latest batches. GET/v1/batches/{id} returns progress. POST/v1/batches/{id}/cancel cancels everything not yet picked up by a phone.

List a batch's messages with GET /v1/messages?batch_id=12. state is adding, running, done or cancelled.

At 500 SMS/hour per phone, 5,000 messages take about 10 hours on one phone. Add phones to split the load.

Check a message

GET/v1/messages/{id}

{
  "id": 1042,
  "to": "+94771234567",
  "body": "Your OTP is 4821",
  "status": "delivered",
  "device_id": 3,
  "target_device_id": null,
  "attempts": 1,
  "error": null,
  "created_at": "2026-09-25T04:10:02.114Z",
  "sent_at": "2026-09-25T04:10:05.870Z",
  "delivered_at": "2026-09-25T04:10:09.302Z"
}

device_id is the phone that sent it; target_device_id is the phone you asked for (if any). Times are UTC, ISO 8601.

Retry or cancel

POST/v1/messages/{id}/retry puts a failed message back in the queue with fresh attempts.

POST/v1/messages/{id}/cancel stops a queued message before a phone picks it up. Its status becomes cancelled.

Both return the updated message, or 409 if the message is in the wrong state.

List messages

GET/v1/messages

QueryDescription
statusOnly this status, e.g. failed.
limit1–200, default 50. Newest first.
before_idFor paging: pass the smallest id from the previous page.
curl "https://lihini.calmray.team/v1/messages?status=failed&limit=100" -H "Authorization: Bearer $LIHINI_KEY"

Statuses & errors

queued→sending→sent→delivered or failed
StatusMeaning
queuedWaiting for your phone. Also used while waiting to retry.
sendingYour phone has picked it up.
sentThe mobile network accepted it.
deliveredThe recipient's handset confirmed it. Some networks never send this, so sent can be final.
failedGave up. See error.
cancelledYou cancelled it before it was sent.

Temporary problems (no signal, network busy) are retried automatically, up to 3 attempts with growing delays. Common error values:

ErrorMeaningRetried?
no_service, radio_off, ril_network_reject, generic_failureSignal or network problem on the phoneYes
ril_network_errThe mobile network rejected the SMSNo. Use retry if you want to try again
limit_exceeded, ril_rate_limitedPhone or network rate limitYes
lease_expiredThe phone went offline while sendingYes
delivery_failed_<code>Network says the handset couldn't receive it (off, invalid number)No
short_code_not_allowed, fdn_check_failure, ril_sim_absentBlocked number type, or no SIMNo
no_sent_callbackThe phone never got a result; not retried to avoid a double SMSNo

Webhooks

Add webhook_url when sending and we POST every status change there:

POST https://your.app/sms-status
Content-Type: application/json
X-Signature: sha256=5f1c…

{"event": "message.status", "message": { …same fields as GET /v1/messages/{id}… }}

Reply with any 2xx within 5 seconds. We don't retry webhooks, so poll GET /v1/messages/{id} if you missed one.

Verify the signature

X-Signature is an HMAC-SHA256 of the raw request body. The HMAC key is the SHA-256 hex of your API key, so only you and Lihini can produce it.

$raw = file_get_contents('php://input');
$secret = hash('sha256', getenv('LIHINI_KEY'));
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
import crypto from "node:crypto";

function verifyLihini(rawBody, signatureHeader) {
  const secret = crypto.createHash("sha256").update(process.env.LIHINI_KEY).digest("hex");
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return signatureHeader?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}
import hashlib, hmac, os

def verify_lihini(raw_body: bytes, signature_header: str) -> bool:
    secret = hashlib.sha256(os.environ["LIHINI_KEY"].encode()).hexdigest().encode()
    expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Your phones

GET/v1/devices

Lists the phones paired to your account. Use an id from here as device_id when sending.

{"devices": [{
  "id": 3, "name": "Google Pixel 7", "enabled": true, "push": true,
  "stale": false, "seen_ago_sec": 42,
  "info": {"model": "Pixel 7", "android": "17", "battery": 81, "sim": {"slot": 1, "carrier": "Hutch"}},
  "last_seen": "2026-09-25T04:12:40.000Z"
}]}

stale: true means the phone hasn't checked in for 30+ minutes: check it's on, online and charging.

PATCH/v1/devices/{id} with {"name": "Front desk"} and/or {"enabled": false} renames or pauses a phone. DELETE/v1/devices/{id} removes it.

POST/v1/pair-codes

Creates a one-time code (valid 10 minutes) to pair another phone to your account. Enter it in the Lihini app.

{"code": "MFHEX3", "client_id": 5, "expires_at": "2026-09-25T04:16:34.437Z"}

Limits & pacing

Sending speedAbout 500 SMS per hour per phone (one every 7.2 s). Add phones to go faster.
Message length1600 characters
Batch size500 messages per request
RetriesUp to 3 attempts for temporary errors
Typical delayA few seconds from request to sent when the queue is empty
Keep the phone charging, on a stable network, with Lihini allowed to run in the background. Mobile networks may block SIMs that send large volumes of identical texts, so personalise messages where you can.

HTTP errors

CodeBodyWhat to do
400{"error": "…", "index": 2}Fix the request. index points to the bad message in a batch.
401{"error": "unauthorized"}Missing, wrong or revoked API key.
404{"error": "not_found"}No such message or phone on your account.
409{"error": "…"}Retry/cancel on a message in the wrong state.
5xxRetry with the same idempotency_key; you won't get duplicates.