USSD

USSD (Unstructured Supplementary Service Data) is the menu-over-dial-code channel: a subscriber dials a short code (e.g. *384*1#), the mobile network opens a synchronous session and posts each keypress to your application, and the application replies with the next screen. It is the de-facto reach channel for feature phones with no data plan — table stakes for West-Africa and other emerging-market deployments (Africa’s Talking / Infobip parity). Orbit models a USSD service as a menu tree: a set of screens (nodes) navigated from a root. You configure the tree once, point your aggregator’s session callback at Orbit, and the engine resolves each step for you. The engine is pure and stateless — the next screen is a deterministic function of (menu, accumulated input) — so it stays correct across pod restarts and replicas without per-session storage.

The session protocol

Orbit speaks the de-facto African-aggregator protocol (Africa’s Talking). On every step the aggregator sends the full accumulated input string, with each prior keypress joined by * (the initial dial is an empty string). Your reply is a plain-text body whose first token is:

CON — show the message and keep the session open, awaiting more input.
END — show the message and terminate the session.

Because the aggregator replays the entire input chain on every callback, you never have to track session state yourself. PUT /api/v1/ussd/menu validates and persists the authenticated tenant’s menu, replacing any previously configured one.

curl -X PUT https://api.orbit.devotel.io/api/v1/ussd/menu \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCode": "*384*1#",
    "root": "main",
    "nodes": [
      {
        "id": "main",
        "prompt": "Welcome to Acme",
        "options": [
          { "key": "1", "label": "Check balance", "next": "balance" },
          { "key": "2", "label": "Buy airtime", "next": "airtime" }
        ]
      },
      { "id": "balance", "prompt": "Your balance is 1,250 NGN." },
      { "id": "airtime", "prompt": "Airtime top-up is coming soon.", "final": true }
    ]
  }'

The menu tree is checked for unique node ids and that root plus every option next resolves to an existing node; a broken reference returns 422 before anything is saved. Fetch the current menu with GET /api/v1/ussd/menu — it returns the definition under data.menu, or null when none has been configured.

Field	Where	Notes
`serviceCode`	menu	Optional dial code the menu answers (documentation only), e.g. `3841#`.
`root`	menu	Id of the node shown on the initial dial. Must reference an existing node.
`nodes`	menu	1–200 screens. Must include `root`.
`id`	node	Stable id (≤ 64 chars), referenced by `root` and option `next` pointers.
`prompt`	node	Screen text (≤ 160 chars — a USSD screen is ~182 chars max).
`options`	node	0–12 branch choices. Omit (or leave empty) for a terminal screen.
`final`	node	Set `true` to terminate the session even when the node has options.
`key`	option	The token the subscriber types to pick the option (digits, letters, `#` or `*`).
`label`	option	Human-readable text rendered next to the key.
`next`	option	Id of the node this option navigates to.

A node with no options (or final: true) is terminal: the engine renders it as an END screen and closes the session.

Simulate a session step

POST /api/v1/ussd/simulate runs the engine exactly as the live callback would, so you can build and test a menu before pointing your aggregator at it. Pass text (the accumulated *-joined input — empty for the initial dial) and, optionally, an inline menu to preview an unsaved definition. Without an inline menu, the tenant’s configured menu is used.

curl -X POST https://api.orbit.devotel.io/api/v1/ussd/simulate \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "1" }'

Response

{
  "data": {
    "action": "END",
    "message": "Your balance is 1,250 NGN.",
    "node_id": "balance",
    "raw": "END Your balance is 1,250 NGN."
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-06-21T00:00:00Z"
  }
}

raw is the exact plain-text body the aggregator receives (CON … or END …); action and message are the same value pre-split for convenience, and node_id is the screen the engine resolved to (useful for telemetry).

Wire the aggregator callback

POST /api/v1/ussd/callback/:tenantId is the public webhook your aggregator posts to on every step of a session. The :tenantId path segment scopes the call to the tenant that owns the menu, so the endpoint stays unauthenticated — the aggregator authenticates by hitting the tenant-scoped URL you configured in its dashboard. It accepts JSON or application/x-www-form-urlencoded bodies (the default for most aggregators) carrying sessionId, phoneNumber, serviceCode, and the accumulated text, and responds with a text/plain body beginning CON (continue) or END (terminate). In your Africa’s Talking (or equivalent) dashboard, set the callback URL to:

https://api.orbit.devotel.io/api/v1/ussd/callback/<your_tenant_id>

If no menu is configured for the tenant — or any error occurs — Orbit returns END Service is not available. so the session is closed cleanly rather than leaving the subscriber hanging.

Network-initiated (push) sessions

Everything above answers a session the subscriber opened by dialling a short code. A push session works in the opposite direction: your application asks your aggregator to open a USSD session on a subscriber’s handset — the primitive behind balance prompts, mobile-money confirmations, and feature-phone OTP flows. Push has no platform-wide provider. You register your own aggregator push endpoint per tenant — exactly like the inbound callback URL you set in your aggregator dashboard — and Orbit POSTs each push to it. The pushUrl must be an https:// URL; it is re-validated and DNS-pinned against the SSRF guard on every send. PUT /api/v1/ussd/push/config stores the provider endpoint. The authHeaderValue credential is write-only — GET /api/v1/ussd/push/config returns the config under data.config with the secret replaced by an authConfigured boolean, never the value itself.

curl -X PUT https://api.orbit.devotel.io/api/v1/ussd/push/config \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pushUrl": "https://ussd.aggregator.example/push",
    "serviceCode": "*384*1#",
    "senderId": "ACME",
    "authHeaderName": "Authorization",
    "authHeaderValue": "Bearer agg_secret_token"
  }'

With a provider configured, POST /api/v1/ussd/push opens the session. Pass the destination phoneNumber in E.164 and the first-screen message (≤ 182 chars); action: CON keeps the session open for a reply (the default), while END shows a one-shot notice. An optional clientRequestId is echoed to the aggregator for idempotency.

curl -X POST https://api.orbit.devotel.io/api/v1/ussd/push \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+234801234567",
    "message": "Your balance is 1,250 NGN. Reply 1 to top up.",
    "action": "CON",
    "clientRequestId": "bal-2026-06-29-001"
  }'

The response carries status: "accepted" and the providerStatus (the 2xx your aggregator returned). The subscriber’s reply, if any, then arrives on your callback like any other session step. The call returns 409 when no push provider is configured yet, 422 when the body is invalid or the configured pushUrl is rejected by the SSRF guard, and 502 when the aggregator can’t be reached or returns a non-2xx. For the full field reference, see the USSD API reference. USSD has no “back” affordance, so the engine never re-prompts on a bad key (the aggregator would replay the bad token on every subsequent callback and loop forever). Instead:

An input that doesn’t match any option ends the session with END Invalid selection. Session ended.
Extra input that arrives after a terminal screen re-renders that screen and ends the session.
A stray leading / trailing / double * separator is dropped before navigation, so it can’t desync the menu walk.

Capabilities

Stateless menu engine — deterministic (menu, input) → screen resolution; no per-session storage, resilient across restarts and replicas.
Up to 200 screens, 12 options each — branch trees with terminal and forced-final nodes.
Inline preview — simulate any step against a saved or unsaved menu with /simulate.
Form-encoded or JSON callbacks — works with the default body encoding African aggregators send.
Network-initiated push — open a session on a subscriber’s handset via your own per-tenant aggregator endpoint, for balance prompts, mobile-money confirmations and OTP flows.

USSD stays inside the GSM session channel in both directions: an inbound reply is answered synchronously within the open session, and a push session is opened through your own USSD aggregator. Neither path originates an outbound voice call or SMS, so no outbound-termination configuration is involved.

Pricing

Orbit charges a flat per-1M platform fee for USSD session callbacks; your aggregator (Africa’s Talking, Infobip, etc.) bills the underlying session minutes separately. See the pricing page.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

USSD

USSD

The session protocol

Configure a menu

Menu shape

Simulate a session step

Response

Wire the aggregator callback

Network-initiated (push) sessions

Navigation rules

Capabilities

Pricing

​USSD

​The session protocol

​Configure a menu

​Menu shape

​Simulate a session step

​Response

​Wire the aggregator callback

​Network-initiated (push) sessions

​Navigation rules

​Capabilities

​Pricing

USSD

The session protocol

Configure a menu

Menu shape

Simulate a session step

Response

Wire the aggregator callback

Network-initiated (push) sessions

Navigation rules

Capabilities

Pricing