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.
- Get your API key (
sk_…) and a pair code from the Lihini admin. - Install the Lihini app on your phone, enter the pair code, and tap Allow running in background.
- 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
Send SMS
POST/v1/messages
Body fields
| Field | Type | Description | |
|---|---|---|---|
to | string | required | Phone number, +94771234567 or 0771234567. Spaces, dashes and brackets are ignored. 6–15 digits. |
body | string | required | Message 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_id | integer | optional | Send only through this phone of yours (see Your phones). Leave out to use any of your phones. |
idempotency_key | string | optional | Your 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_url | string | optional | We 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.
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
| Query | Description |
|---|---|
status | Only this status, e.g. failed. |
limit | 1–200, default 50. Newest first. |
before_id | For 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
| Status | Meaning |
|---|---|
queued | Waiting for your phone. Also used while waiting to retry. |
sending | Your phone has picked it up. |
sent | The mobile network accepted it. |
delivered | The recipient's handset confirmed it. Some networks never send this, so sent can be final. |
failed | Gave up. See error. |
cancelled | You 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:
| Error | Meaning | Retried? |
|---|---|---|
no_service, radio_off, ril_network_reject, generic_failure | Signal or network problem on the phone | Yes |
ril_network_err | The mobile network rejected the SMS | No. Use retry if you want to try again |
limit_exceeded, ril_rate_limited | Phone or network rate limit | Yes |
lease_expired | The phone went offline while sending | Yes |
delivery_failed_<code> | Network says the handset couldn't receive it (off, invalid number) | No |
short_code_not_allowed, fdn_check_failure, ril_sim_absent | Blocked number type, or no SIM | No |
no_sent_callback | The phone never got a result; not retried to avoid a double SMS | No |
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 speed | About 500 SMS per hour per phone (one every 7.2 s). Add phones to go faster. |
| Message length | 1600 characters |
| Batch size | 500 messages per request |
| Retries | Up to 3 attempts for temporary errors |
| Typical delay | A few seconds from request to sent when the queue is empty |
HTTP errors
| Code | Body | What 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. |
5xx | Retry with the same idempotency_key; you won't get duplicates. |