Unstructured Supplementary Service Data or “USSD” is the stack used in Cellular Networks to offer interactive text based menus and systems to Subscribers.

If you remember topping up your mobile phone credit via a text menu on your flip phone, there’s a good chance that was USSD*.

For a period, USSD Services provided Sporting Scores, Stock Prices and horoscopes on phones and networks that were not enabled for packet data.

Unlike plain SMS-PP, USSD services are transaction stateful, which means that there is a session / dialog between the subscriber and the USSD gateway that keeps track of the session and what has happened in the session thus far.

Today USSD is primarily used in the network at times when a subscriber may not have balance to access packet data (Internet) services, so primarily is used for recharging with vouchers.

Osmocom’s HLR (osmo-hlr) has an External USSD interface to allow you to define the USSD logic in another entity, for example you could interface the USSD service with a chat bot, or interface with a billing system to manage credit.

Using the example code provided I made a little demo of how the service could be used:

Communication between the USSD Gateway and the HLR is MAP but carried GSUP (Rather than the full MTP3/SCCP/TCAP layers that traditionally MAP stits on top of), and inside the HLR you define the prefixes and which USSD Gateway to route them to (This would allow you to have multiple USSD gateways and route the requests to them based on the code the subscriber sends).

Here’s my Osmo-HLR config:

ctrl
 bind 127.0.0.1
hlr
 database /var/lib/osmocom/hlr.db
 subscriber-create-on-demand 15 cs+ps
 gsup
  bind ip 10.0.1.201
  ipa-name unnamed-HLR
 euse nicktest-00-00-00-00-00-00
 ussd route prefix *#100# internal own-msisdn
 ussd route prefix *#101# internal own-imsi
 ussd route prefix *#102# external nicktest-00-00-00-00-00-00
 ussd default-route external nicktest-00-00-00-00-00-00

Then I’m just running a slightly modified version of the example code that ships with Osmo-HLR.

(I had hoped to make a Python example and actually interface it with some external systems, but another day!)

The signaling is fairly straight forward, when the subscriber kicks off the USSD request, the HLR calls a MAP Invoke operation for “processUnstructuredSS-Request”

Unfortunately is seems the stock Android does not support interactive USSD.
This is exposed in the Android SDK so applications can access USSD interfaces (including interactive USSD) but the stock dialer on the few phones I played with did not, which threw a bit of a spanner in the works. There are a few apps that can help with this however I didn’t go into any of them.

(or maybe they used SIM Toolkit which had a similar interface)