A system needs SMS and USSD on a real SIM, and the operators give no API. A phone with a SIM can do the job. Nothing connected that phone to a system, and nothing watched it.
Diamond Line turns Android phones into gateways. A system sends SMS and runs USSD workflows, such as a balance check or a transfer, through a phone it has never touched. Most of the design is about one question: what do you do when you cannot tell whether money moved?
The socket only knocks
Each phone keeps a socket open, but the socket carries almost nothing. When there is work, the server sends one event saying a command is waiting, with its id. The phone fetches the command over HTTP, and it does the same on every reconnect.
- Knock
The server sends “command available” with an id. No message text travels on the socket.
- Fetch
The phone asks for its waiting commands over HTTP, with its own key.
- Work
The phone sends the SMS or starts the USSD run.
- Report
The phone reports back. A repeated report gets the same answer and changes nothing.
Live commands and missed commands take the same path, so a phone that was offline for an hour catches up the same way it works normally. HTTP brings authentication, idempotency and a real answer. The price is one extra request per command.
The phone runs the session, the server decides
USSD sessions time out fast: two minutes without an exchange and the operator ends them. A round trip to the server between every menu would lose sessions. So when a run starts, the server sends every step of the attempt at once. The phone dials and replies by itself and reports each step as it goes. The server answers continue or stop, and can jump forward to a named step.
A dropped socket in the middle of a session no longer kills the run. The cost is honest: if the server goes down mid-run, the session stalls, and the run ends by its timeout or by the stuck rule.
| Timing | Value |
|---|---|
| Heartbeat | Every 30 seconds. |
| Online | Heard from in the last 90 seconds. Reconnecting up to 5 minutes, then offline. |
| Dial and reply | A timeout between 5 and 120 seconds per step. |
| Waiting for an SMS | Between 30 and 900 seconds. |
| USSD session | Ends after 2 minutes with no exchange. |
| Stuck | The waits left in the run, plus 60 seconds, counted from the fetch. |
Nothing retries past the commit step
Every workflow has a commit step: the one that moves money. Before it, failing is cheap. A failed attempt retries twice on its own, 15 and then 60 seconds apart, or 5 and 30 seconds for a lost network or a lost dialog. Named failures, such as a wrong menu, do not retry at all.
A second send can pay twice.
Past the commit step, a timeout or an answer nobody recognises does not retry. The run goes to Needs review, and the retry action refuses it every time. Only a person closes it: marked as sent, with a reason and the operator’s reference, or marked as failed, with a reason. The API can never resolve a Needs review.
- #1open_menutimeout · retry in 15 s
- #2open_menumatched
- #2amountmatched
- #2confirmtimeout at commit → needs review · retries off
Every attempt at every step is its own row, unique on run, attempt and step, with what was expected, what came back, the outcome and how long it took. A report for an old attempt is refused. The live monitor and the reports read the same rows.
| Run | Means |
|---|---|
| Queued | Waiting for its phone and SIM. |
| Running | The phone is in the session. |
| Waiting for SMS | The session ended; the confirming SMS has not arrived. |
| Succeeded | Done and confirmed. |
| Failed | Failed before commit. Can be retried, or closed as failed. |
| Needs review | Unclear at or after commit. Only a person closes it. |
Hold it until it is taken
Nothing is thrown away because a connection dropped. The phone keeps every SMS it receives until the server accepts it, and the server keeps every command until the phone finishes it. Messages carry an id from the phone, so a message sent twice is stored once. The phone’s logs stay on its disk until the server answers with success.
A SIM runs one USSD session at a time, and it stays busy while a run waits for its SMS, so a late message can never be credited to the next run. A heartbeat never overwrites a SIM number a person has confirmed, and number detection dials a code rather than guessing.
Workflows belong to a device
A workflow is a list of steps with versions: draft, live, retired. A run copies the version it starts with. The first engine was a straight line. It later gained forward-only jumps, action steps and runs that span several sessions. Forward-only means no loops.
Workflows were offered as shared definitions per operator. We chose to give each device its own. A second tablet starts empty, with no copy tool yet. And because a scheduled trigger can move money with nobody watching, every trigger needs a daily limit, and the limit cannot be switched off.
Webhooks that prove who sent them
Every webhook carries a timestamp and an HMAC-SHA256 of that timestamp and the body. A receiver that fails is retried on a widening ladder, and after three days of failures the endpoint is switched off and the person who made it gets an email.
| Retry | After |
|---|---|
| 1–3 | 1 minute, 5 minutes, 30 minutes. |
| 4–5 | 2 hours, 6 hours. |
| 6–7 | 12 hours, 24 hours. |
| Day 3 | Still failing: the endpoint is switched off and its creator is told. |



