USSD Runtime

What it does

An open-source Go service that runs USSD menu flows on Africa's Talking, Hubtel, Nalo and Arkesel. It runs USSD Flow Studio exports unchanged, and adds typed answers with validation, variables in prompts, and signed calls to your backend with a hard time limit. Sessions live in Redis, so several instances can share the work.

The problem

USSD still reaches people without smartphones or data, but every network gives you only a few seconds per reply, and every gateway speaks a different format. Slow servers mean dropped sessions and lost customers.

What you get

How to use it

Design your menu in USSD Flow Studio (or write the JSON), run it with the runtime, and point your gateway's callback URL at it. Add input screens and actions when you need typed answers or data from your own system.

git clone https://github.com/Jacksonoseikojo1122/ussd-runtime.git
cd ussd-runtime
FLOW_FILE=flows/demo-wallet.json SIMULATOR=on go run ./cmd/ussd-runtime
# open http://localhost:8080 and press Dial

Africa's Talking  https://<your-host>/ussd/africastalking?token=<GATEWAY_TOKEN>
Hubtel            https://<your-host>/ussd/hubtel?token=<GATEWAY_TOKEN>
Nalo              https://<your-host>/ussd/nalo?token=<GATEWAY_TOKEN>
Arkesel           https://<your-host>/ussd/arkesel?token=<GATEWAY_TOKEN>

"pay_student": {
  "prompt": "Enter the student ID", "kind": "input",
  "input": { "name": "student_id", "type": "digits", "min_length": 4, "next": "pay_lookup" }
},
"pay_lookup": {
  "prompt": "Pay for {{student_name}}?\nOutstanding: GHS {{balance}}", "kind": "menu",
  "action": { "url": "$BACKEND_URL/ussd/student", "timeout_ms": 2000, "can_go_to": ["not_found"] },
  "options": [{ "key": "1", "label": "Yes", "next": "pay_amount" }]
}

app.post("/ussd/student", express.raw({ type: "application/json" }), (req, res) => {
  if (!validSignature(req)) return res.status(401).end(); // X-USSD-Signature, see docs/actions.md
  const { vars } = JSON.parse(req.body.toString());
  const s = findStudent(vars.student_id);
  if (!s) return res.json({ next: "not_found" });
  res.json({ vars: { student_name: s.name, balance: s.balance } });
});

Documentation

• Getting started Run the demo, your Flow Studio export, and a flow with a backend
• Flow format Screens, input types, variables, actions and validation
• Actions The backend contract and signature checks in Node, Python, PHP and Go
• Gateways Africa's Talking, Hubtel, Nalo and Arkesel formats, with sources
• Operations Load-test results, Redis, Docker, Kubernetes, metrics and alerts
• OpenAPI spec Every endpoint, plus the action webhook

Features

• Adapters for Africa's Talking, Hubtel, Nalo and Arkesel, built from each provider's documentation
• Runs USSD Flow Studio exports unchanged: the Studio's engine tests run against it in CI
• Input screens for text, digits, amounts and Ghana phone numbers, checked before your backend sees them
• Signed backend calls with a 2-second budget and an allow-list of screens the backend can send callers to
• Sessions in Redis (several instances) or memory (one), with a phone simulator for testing
• Prometheus metrics and a load-test tool with published results

What building it covers

• Go
• Low-latency services
• Load testing
• Session state at scale

Stack

• Go
• Redis
• Prometheus
• Docker
• Kubernetes

Questions