Skip to main content
The Numbers → USSD page is the dashboard editor for the USSD channel. It covers the whole build-and-test loop: configure the menu subscribers see when they dial your short code, simulate a session against that menu, and open a network-initiated (push) session on a handset — all against the same endpoints the public API exposes. This guide walks the page top to bottom.

​
1. What the page does

Open it as the USSD tab inside the Numbers hub, or deep-link straight to /numbers/ussd — the same surface renders both ways. The page is organized as a stack of cards, each wired to one endpoint:
  • Aggregator callback URL — a copyable template for the public session callback. Replace the {your-tenant-id} segment with your workspace tenant id and paste the URL into your aggregator dashboard (Africa’s Talking, Infobip, or any HTTP-fronted gateway).
  • Menu editor — create, edit, and save the screen tree against GET/PUT /api/v1/ussd/menu.
  • Session simulator — run a step exactly as the live aggregator callback would against POST /api/v1/ussd/simulate, including unsaved edits.
  • Push provider — store the aggregator endpoint the platform POSTs network-initiated sessions to (GET/PUT /api/v1/ussd/push/config).
  • Send push — dispatch a network-initiated session to a handset (POST /api/v1/ussd/push).
Everything the reference guides do by curl, this page does visually — it is the better default day-to-day surface, and its validation mirrors the server so a broken menu rarely reaches the wire.

​
2. The menu tree model and the session protocol

Orbit models a USSD flow as a menu tree: screens (nodes) with option branches, persisted as one definition against your tenant. Two protocol rules drive the whole interaction model, and the editor speaks in their terms:
  • CON keeps the session open. A screen with options shows the numbered choices and waits for the next keypress. The subscriber’s selection token is appended to the accumulated *-joined input the aggregator replays on every step.
  • END closes the session. A screen with no options — or one you explicitly mark Terminate the session on this screen — renders terminally and the carrier closes the session.
Because the aggregator replays the accumulated input on every step, the next screen is a deterministic function of the menu and that input — the engine is stateless, and that is exactly what makes the simulator below a faithful preview of live traffic. The full semantics are in the USSD session model.

​
3. Create a menu in the editor

The editor card starts from a starter tree when no menu is saved yet. To build your own:
  1. Add a screen — give it an id (letters, digits, _ or -, up to 64 characters) and a prompt of up to 160 characters (a USSD page caps at roughly 182 including carrier framing).
  2. Add branch screens for each answer, and check Terminate the session on this screen on the ones that deliver a final answer (“Your balance is…”, a confirmation).
  3. On a menu screen, add options — each option has a key, a label, and a target screen. Keys may only be digits, *, or #: a real handset can never send a letter over a USSD session, so a letter key would create an option no phone could reach.
  4. Pick the start screen — the root the initial dial opens on.
  5. Save. The editor validates the tree client-side with the same integrity rules the API enforces, so a broken reference is caught before anything round-trips:
  • every screen id must be unique;
  • the start screen and every option target must point at a screen that exists;
  • up to 200 screens per menu, up to 12 options per screen;
  • no implicitly-terminal screens — a non-final screen with zero options requires either an option or the explicit terminate checkbox, because the engine ends the session there either way and saving that by accident is impossible here.

​
4. Simulate a session

Below the editor, the simulator panel walks the menu the way the live callback does. Type the accumulated input exactly as the aggregator would send it — each keypress joined by *, empty for the initial dial (1*2 for a subscriber who pressed 1 then 2). The panel rejects non-DTMF input (digits, *, # only) instead of running a session against a string no handset could produce. Each run returns the resolved screen id, the pre-split CON/END action, the screen body, and the exact raw text the live callback would emit. An END the engine flagged as a fault — an unmatched keypress or an unmapped route — renders as an error badge, not a clean close. Walk every path before you take a menu live:
  1. Initial dial (empty input) → CON with the start screen.
  2. One key per branch → the answer screens.
  3. A bad key (9 on a two-option menu) → END Invalid selection. — the only behavior that stops a mis-keyed token from replaying forever, so confirm it shows.
The simulator accepts unsaved edits, so it doubles as a regression harness for menu changes: simulate the same inputs before and after an edit and compare.

​
5. Open a push session from the page

A push session is the inverse of a dial-in — your application opens the session on the subscriber’s handset, for balance prompts, mobile-money confirmations, or feature-phone OTP. The page covers both halves:
  1. Push provider — paste the aggregator endpoint (an https:// URL) the platform POSTs the session to, plus an optional default service code, sender id, and a provider auth header. The credential is write-only — the page never reads it back, only that one is stored — and saving replaces the whole config, so re-enter the credential to keep it or leave it blank to store the config without one.
  2. Send push — enter the recipient phone number and the first screen (capped at 182 characters), pick a disposition — END for a one-shot notice, CON for a session that resumes against the menu tree awaiting the subscriber’s reply — and dispatch.
A CON push only takes replies if the aggregator callback URL from the top card is registered in your aggregator dashboard, exactly as dial-in sessions require. The end-to-end dispatch walk-through with retries and failure triage is in Send USSD push sessions.

​
6. Deeper guides

The Numbers → USSD page is the surface; these guides go deeper on the same endpoints:
  • Build an interactive USSD flow — the full end-to-end build by API: short-code provisioning, menu-tree design, session expiry and terminal-response rules.
  • USSD menus cookbook — the whole build threaded in one pass: dial-in versus push, stepwise menu growth, SMS fallback, production rules.
  • Send USSD push sessions — network-initiated dispatch end to end: provider config, idempotent retries, failure triage.
  • USSD session model — the stateless session semantics the editor and simulator both rely on.
  • USSD API reference — every field on every endpoint the page calls.