Two phones face down on terracotta tile

Diamond Line

Android phones as SMS and USSD gateways, running watched USSD workflows with safe retries.

StatusWorking
What it isSMS and USSD
Read the essay

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.

  1. Knock

    The server sends “command available” with an id. No message text travels on the socket.

  2. Fetch

    The phone asks for its waiting commands over HTTP, with its own key.

  3. Work

    The phone sends the SMS or starts the USSD run.

  4. 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.

TimingValue
HeartbeatEvery 30 seconds.
OnlineHeard from in the last 90 seconds. Reconnecting up to 5 minutes, then offline.
Dial and replyA timeout between 5 and 120 seconds per step.
Waiting for an SMSBetween 30 and 900 seconds.
USSD sessionEnds after 2 minutes with no exchange.
StuckThe 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.

  1. #1open_menutimeout · retry in 15 s
  2. #2open_menumatched
  3. #2amountmatched
  4. #2confirmtimeout at commit → needs review · retries off
Example run. Each attempt redials from the first step, because a USSD session cannot be resumed.

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.

RunMeans
QueuedWaiting for its phone and SIM.
RunningThe phone is in the session.
Waiting for SMSThe session ended; the confirming SMS has not arrived.
SucceededDone and confirmed.
FailedFailed before commit. Can be retried, or closed as failed.
Needs reviewUnclear 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.

RetryAfter
1–31 minute, 5 minutes, 30 minutes.
4–52 hours, 6 hours.
6–712 hours, 24 hours.
Day 3Still failing: the endpoint is switched off and its creator is told.

If you build, dream, or make, you belong here.

Find your way in