How USSD works

A USSD menu runs when a subscriber dials your USSD code. It works on any GSM phone without data. Ponitor calls your server for each screen.

USSD works the other way round

For SMS and WhatsApp, you call Ponitor. For USSD, Ponitor calls a webhook on your server for every screen. You don't call Ponitor to run a session.

How it works

A phone dials *123#; Ponitor posts the start turn to your USSD webhook, your webhook answers with a screen and two options, and the phone shows them as a menu.

A USSD session keeps a connection open between the phone and the network. Ponitor makes one webhook call to your server for each screen.

1. The subscriber dials your code.
2. The network passes the session to Ponitor.
3. Ponitor sends your webhook a signed JSON POST for the screen.
4. Your webhook returns the screen text and whether to continue or end.

Each reply from the subscriber repeats steps 3 and 4. Ponitor handles the connection to Orange and Lonestar Cell MTN.

• Ponitor shows your screens and options as you send them. It doesn't reorder them.
• Ponitor numbers your options the same way on both networks. Send only the choices.
• When the subscriber chooses 00 Home, your webhook gets a new start turn.

Session lifecycle

A session is a sequence of turns between one subscriber and your webhook, from the dial until your webhook ends it. All turns share one sessionId.

Purple arrows are requests and grey dashed arrows are responses. Ponitor passes each screen back through the network.

To see the exact request and response for every turn of a real session, see A session, step by step.

There are three turn types.

Turn type	When it happens	What Ponitor sends
start	The subscriber dials your USSD code. This is the first turn of a session.	input: null
input	The subscriber answers your previous screen.	What they typed
ping	A reachability check sent when you register or turn on your webhook. It never comes from a subscriber.	input: null

Your webhook's response controls what happens next.

• With action: "continue", Ponitor shows your screen text and waits for a reply. Send a menu in options or a text or number input in form.
• With action: "end", Ponitor shows your final screen text and closes the session.

A continue must include exactly one of options or form. A response with neither or both fails the turn. See the Response contract for the exact request and response schemas.

Try it in the sandbox

Every team has *123# in the sandbox. You don't request it.

1. In Test mode, open USSD › Codes, and set the webhook on *123# to your server's https URL. Ponitor sends it a ping and saves it only if it answers.
2. Copy the signing secret. It's shown once.
3. Open Simulator, then its Phone app, and dial *123#.

Each screen goes to your webhook, with the Simulator's number as the caller's.

Getting a USSD code

In live, you request your own code, such as *144#. You need your team's compliance review approved, and the app in Live mode.

1. Open USSD › Codes and request up to three codes, each a *, 2 to 4 digits and a #.
2. We review it. Once we approve it, we submit it to the Liberia Telecommunications Authority (LTA).
3. The LTA authorizes it.
4. We set it up on Orange and MTN, and it goes live. We email you at each decision, and your team webhooks get ussd_code.approved or ussd_code.rejected.
5. On the live code, set the webhook URL that Ponitor calls for each turn, and copy its signing secret.
6. Dial the code from your phone to test it.

Each code has one webhook. You can rotate its signing secret or turn it off without changing the code.

For request and response formats, signatures and timing, see the USSD webhook reference.