Documentation

How Lacspace SMS works, step by step.

What actually happens between an app asking for an OTP and a phone in Nepal receiving it — and what the portal shows at each step.

1
An app asks for an SMS
A Lacspace product (StockYatra, for example) or an activated workspace calls the SMS API with its API key: an OTP or a transactional message to a Nepal mobile number.
2
The router picks a SIM
The gateway looks at every pool SIM: is it enabled, is its phone heartbeating, is today's pack used up, is it paced, has its pack expired, has it been failing? Among the healthy ones it prefers a SIM on the recipient's own network (NTC to NTC, Ncell to Ncell) and saves the unlimited SIM for when the limited ones run out.
3
The phone sends it
Pool phones check for work every few seconds. The chosen phone picks the message up and sends it from that exact SIM — never a different one — then reports back when it is sent and, where the network supports it, delivered.
4
Failures move on
If a phone does not confirm in time, or reports a failure, the message moves to the next eligible SIM, and then to the next route if the whole pool is out. Every attempt is kept in the message's history.
5
Staff watch it here
This portal shows each SIM's quota for today, each phone's heartbeat, battery, network and app version, and the sent / delivered / failed / fallback counts per SIM and route — with the full log one click away.

The pool

Each SIM is a normal prepaid or business SIM with a daily SMS pack (for example 100 a day). One business SIM is unlimited.

Each phone holds one or two SIMs and runs the Lacspace SMS app, which picks up messages assigned to its SIMs, sends them and reports status.

Every SIM has its own reset hour in Nepal time, matching when its pack renews, so quota is counted per pack day — not per calendar day.

A SIM is OK, Paced, Quota used, Stale, Pack expired, Failing or Disabled. Only OK SIMs are picked; the reason is always shown.

OK: Enabled, phone heartbeating, quota left, not paced. Eligible to send.
Paced: Android limits how many SMS one app may send in a window. The SIM sits out until a slot frees up.
Quota used: Today's pack is used up. Comes back at the SIM's reset hour (Nepal time).
Stale: The phone has not sent a heartbeat for a few minutes. Check power, network and the app.
Pack expired: The pack expiry date set in the portal has passed. Renew the pack and update the date.
Failing: Several sends in a row failed. Skipped until reset by staff or a successful send.
Disabled: Switched off, or a new SIM that has not been set up yet (no number).

Platform staff pair phones from Devices in the portal. The same checklist is shown there next to the QR code.

1Keep it on a charger
Pool phones stay plugged in, in a spot with good signal for every SIM's network. A phone on low battery goes into power saving and stops heartbeating.
2Battery: Unrestricted
Settings → Apps → Lacspace SMS → Battery → Unrestricted (on some phones: "Don't optimise" / "No restrictions"). Without this, Android pauses the app in the background and messages wait.
3Allow auto-start
On Xiaomi, Oppo, Vivo, Realme, Samsung and similar: Settings → Apps → Lacspace SMS → Auto-start / "Allow background activity" ON, and lock the app in the recent-apps screen so it is never swept away.
4Turn off RCS chat
Messages app → Settings → RCS chats → off, for every SIM. With RCS on, some messages go as chat instead of SMS and never report a normal SMS status.
5Pick the default SMS SIM
Settings → SIM manager → SMS → choose one SIM (not "Ask every time"). The gateway names the SIM for each send, but a prompt can still block sending on some phones.
6Grant permissions
Open the app and allow SMS, phone and notifications. The device page shows which permissions the phone reported.
7Raise Android's SMS send cap (adb)
Android limits how many SMS one app may send per window (about 30 per 30 minutes by default). From a computer with USB debugging enabled on the phone, run:
```
adb shell settings put global sms_outgoing_check_max_count 1000
adb shell settings put global sms_outgoing_check_interval_ms 60000
```

8Exempt from Doze (adb)

Belt and braces for the battery setting above:

adb shell dumpsys deviceidle whitelist +com.lacspace.sms
adb shell cmd appops set com.lacspace.sms RUN_ANY_IN_BACKGROUND allow

9Scan the pairing QR
In the app, scan the QR shown when you create the device (or rotate its key). It holds a lacspacesms://pair link with the server address and the device key, and it is shown only once. The phone then checks for messages every few seconds and sends a heartbeat every minute.
10Set up each SIM here
New SIMs arrive disabled. Open SIMs, set the number (98XXXXXXXX), label, daily limit, reset hour, pack expiry, priority and networks, send a test, then enable it.