Send USSD push (network-initiated) sessions end to end

A USSD push (network-initiated session) is the inverse of a dial-in session: your application asks the aggregator to open a session on the subscriber’s handset instead of waiting for the subscriber to dial the short code. This guide takes one from zero to live: wire the callback URL, save the menu, configure the provider, dispatch, make retries safe, and test before a carrier sees traffic. The primitives are few (ussd/callback, PUT /ussd/menu, PUT /ussd/push/config, POST /ussd/push) and the pitfalls are known (unconfigured provider, URL-safety rejects, aggregator failures, replay sessions). Follow it step for step.

1. What USSD is, and when push beats SMS or voice

USSD is the only channel that reaches a feature phone with no data plan, and the only session channel that works on 2G coverage. A session is synchronous: the network holds it open and every screen round-trips as plain text under ~182 characters, with the carrier closing the session after tens of seconds of inactivity. Dial-in USSD begins on the handset — the subscriber dials the short code. A push session begins at your application: you dispatch once, and the subscriber’s handset rings into the menu with the first screen already on it. Push is the right call when the subscriber did not ask for the interaction but must see it now:

Balance and statement prompts — push a balance screen straight to the handset, no short code to memorize.
Mobile-money confirmations — a payment step that must reach the subscriber immediately, with the keypad answer feeding back into a callback your application owns.
Feature-phone OTP — a one-shot code or a yes/no confirmation to a device that cannot run your app.

Against the alternatives: SMS is asynchronous and cheap but has no session — a reply arrives as a separate message minutes later and cannot gate a payment step. Voice carries rich prompts but costs an answered call per notice and reaches nobody on a handset that is off or out of coverage. Push USSD is the middle path: delivered like an SMS (no app, no data plan, works on 2G), interactive like a call (the subscriber answers inside the session). For anything longer than a few screens — surveys, rich content — push a notice and hand off to SMS or a voice call from the menu. Within push itself, two dispositions cover both shapes: pick END for the one-shot notice (“Your balance is 1,250 NGN.”) or CON for a session that stays open awaiting the subscriber’s reply. The same channel powers both — choose at dispatch time.

2. Point the aggregator at your callback URL

A push session only lives for one screen without one more piece of wiring. The dispatch (POST /api/v1/ussd/push) opens the session; every keypad step after still resolves through the same tenant-scoped callback a dial-in session uses. In your aggregator dashboard (Africa’s Talking, Infobip, or any HTTP-fronted gateway), set the session callback to:

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

The tenant-scoped path is the whole credential — the endpoint is public by design, and it accepts both JSON and form-encoded bodies with sessionId, phoneNumber, serviceCode, and the accumulated text. The end-to-end picture is: your application dispatches the push → the aggregator opens the session on the handset → every further keypress POSTs to that URL → Orbit replies with the next screen as plain text. Without this URL registered, an END push still delivers its one-shot notice, but a CON push has nowhere to take the reply. A push whose action is CON opens on the menu tree’s root, and every step after resolves against that tree exactly as a dial-in step would. The tree is one tenant-scoped definition persisted with PUT /api/v1/ussd/menu:

{
  "serviceCode": "*384*1#",
  "root": "main",
  "nodes": [
    { "id": "main", "prompt": "…", "options": [ { "key": "1", "label": "…", "next": "balance" } ] },
    { "id": "balance", "prompt": "…" }
  ]
}

Field by field:

serviceCode — optional, documentation only: the dial code this menu answers.
root — the id of the node shown when a session (dial-in or push with CON) opens.
nodes[] — 1 to 200 screens. Each node carries a unique id (≤64 chars) and prompt text (1–160 chars; a USSD page caps at roughly 182 including carrier framing).
Default to terminal — a node with no options ends the session with END. A node with options replies CON and waits. final: true forces termination even when options exist.
options[] — up to 12 branches. Each option has a DTMF-only key (digits, *, #; ^[0-9#*]+$ — a real handset can never send a letter), a label, and a next pointer.

The validator checks unique node ids and that root plus every option next resolves before anything is saved — a broken reference returns 422, so a malformed tree can never answer live traffic. GET /api/v1/ussd/menu reads the current definition back under data.menu (or null when none is set). Skip this step only when every push you dispatch is a one-shot END — the moment a CON push reaches the callback with no menu saved, the carrier shows “Service is not available.”

4. Worked example: a three-branch balance-and-topup tree

The menu below is the same three-branch shape the flow-builder guide uses for dial-in — which is the point: push and dial-in sessions share one tree, so a push that opens with CON lands on this root and offers balance, top up, and support. Save it once and both directions resolve:

curl -X PUT https://api.orbit.devotel.io/api/v1/ussd/menu \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCode": "*384*1#",
    "root": "main",
    "nodes": [
      {
        "id": "main",
        "prompt": "Acme. 1. Balance 2. Top up 3. Support",
        "options": [
          { "key": "1", "label": "Check balance", "next": "balance" },
          { "key": "2", "label": "Buy airtime", "next": "topup" },
          { "key": "3", "label": "Support", "next": "support" }
        ]
      },
      { "id": "balance", "prompt": "Your balance is 1,250 NGN." },
      { "id": "topup", "prompt": "Enter amount (NGN).", "final": true },
      { "id": "support", "prompt": "An agent will call you back." }
    ]
  }'

Three terminal leaves (balance, topup, support) hang off one root; the topup leaf is marked final explicitly so the engine terminates on it. When the push dispatch (section 6) sends action: "CON", the subscriber’s 1 reply POSTs to the callback from section 2 with accumulated text: "1" and the engine answers END Your balance is 1,250 NGN. Keep the answer as close to the root as a few keypresses allow — the carrier’s inactivity window applies to push sessions exactly as it does to dial-in.

5. Configure the push provider

The push provider is your own aggregator endpoint — registered per tenant; nothing is global and no company-wide credential exists. Set it once with PUT /api/v1/ussd/push/config:

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

Two fields matter at write time:

pushUrl must be an https:// URL. The validator also rejects URLs that resolve into internal address space, and it is re-validated and DNS-pinned against the SSRF guard on every dispatch — an aggregator endpoint behind a private hostname fails at write time rather than silently.
authHeaderValue is a write-only credential. Read back the config with GET /api/v1/ussd/push/config and the response shows authConfigured: true instead of the secret — the dashboard’s push panel mirrors it the same way (the push card on Numbers → USSD shows the saved endpoint plus an “auth header configured” flag, never the value).

Optional fields: serviceCode sets the default code every push opens against (section 4’s tree answers it); senderId carries the sender / channel id some aggregators require; authHeaderName picks the header the credential travels in.

6. Dispatch a session

Dispatch one push session per call to POST /api/v1/ussd/push:

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

phoneNumber accepts E.164 with or without the leading + (normalized on the way in). message is capped at the 182-character USSD payload ceiling, so a too-long prompt fails fast here rather than being silently truncated by the GSM network. action defaults to CON; send END for the one-shot notice. A successful call returns a 200 envelope with { "status": "accepted", "providerStatus": 200, "phoneNumber": "+234801234567" } — “accepted” is the aggregator confirming receipt, which is as far as the synchronous API can see. The session itself opens on the handset asynchronously after that.

7. Idempotency and retries

Push aggregators retry. Assume a dispatch can arrive twice at the provider and design for it. POST /api/v1/ussd/push accepts clientRequestId — a caller-supplied key echoed to the aggregator in the dispatch envelope — so a replayed request keys on the same value and your side can deduplicate. Key the id on what the session means (bal-20260910-001 above), not on a random nonce per attempt. The “exactly-once per hangup” rule for a push leg means the session lifecycle across retries resolves to one terminal step: a replayed CON that is open must close, not re-open; a replayed END must not re-show. With clientRequestId in the envelope you can assert both from your own callback — a duplicate key means the leg is already in flight or already closed. For END one-shot notices: key the dispatch by a tenant-side id, treat a duplicate END as a no-op, and never fire a second dispatch for the same logical prompt. Keep the side effects your callback records for the session (a balance lookup, a top-up confirmation) idempotent too, keyed on the sessionId the aggregator sends — the same callback discipline the dial-in side needs, because the push and the menu are two ends of one session.

8. Test before a carrier ever sees traffic

Three layers of testing, all before the first live dispatch. Simulate the menu in the dashboard. The Numbers → USSD page (/numbers/ussd) runs the same menu editor and session simulator the flow-builder guide documents, wired to POST /api/v1/ussd/simulate. Run the screen your push is about to open in a browser instead of burning live pushes: type the accumulated input exactly as the aggregator would send it (1 for the balance branch, empty for the opening screen) and check the CON/END disposition and the exact raw text the live callback would emit. The push card on the same page shows the saved provider endpoint — one surface, both halves. Simulate from curl. The same endpoint accepts a text and optionally an inline menu to preview an unsaved candidate:

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

The reply carries the resolved node_id, the pre-split action (CON/END) and message, and the exact raw body the aggregator would receive (e.g. "END Your balance is 1,250 NGN."). Walk every path the push can land on in a cheap loop before you re-point the aggregator — a red simulation is a failing test. Sandbox numbers for the follow-up leg. When a push step triggers a follow-up SMS, email, or voice confirmation (common on a top-up branch), exercise that leg in sandbox mode with the sandbox magic numbers: the trailing digit of the recipient deterministically selects the delivery outcome (delivered, undelivered, carrier-reject, expired), so your handler for the follow-up receipt is tested against every terminal state before a real MSISDN runs through it. The simulator covers the session screens; the magic numbers cover whatever the session kicks off.

9. Troubleshooting carrier-handled failures

Symptom	Status	Cause	Fix
Dispatch returns `CHANNEL_NOT_CONFIGURED`	409	No push provider is set for the tenant.	Run `PUT /api/v1/ussd/push/config` first (section 5), then retry.
Dispatch returns a body or URL-safety reject	422	The request body failed validation, or `pushUrl` was rejected.	For the body: check `phoneNumber` is E.164 and `message` is 1–182 chars. For the URL: it must be `https://` and must not resolve into internal address space — write time and dispatch time both enforce this.
Dispatch returns `MESSAGE_SEND_FAILED`	502	The aggregator endpoint was unreachable, timed out, or returned non-2xx.	Retry the dispatch with the same `clientRequestId`, then check the provider’s own console; a rejected signature/cert or a provider outage shows there first.
Handset shows “Service is not available.” after a `CON` push	terminal `END`	No menu tree is saved for the tenant, so the callback has nothing to resolve.	Save the menu tree (`PUT /api/v1/ussd/menu`, sections 3–4); a saved menu is what every step after the prompt resolves against.
Session closes on the carrier’s own message mid-flow	carrier timeout	The inactivity window (usually 30–90 seconds) elapsed between keypresses.	Put the answer within a handful of keypresses of the root and keep prompts short; the engine is pure, so a re-opened session that re-keys the same path lands on the same screens.
Prompt garbled or truncated on some handsets	rendering	Older MNO gateways insert their own header/footer into the screen; the page cap is 182 chars including brackets.	Keep `prompt` ≤160 chars and `message` ≤182 as the API requires, avoid decorative separators, and re-test against a real handset after every menu edit, not only the simulator.
A replayed dispatch re-opens or double-shows a session	duplicates	Replayed accumulated input without a stable key — the aggregator re-sent the dispatch and nothing told your side it was a duplicate.	Key every dispatch on `clientRequestId` (section 7); a duplicate key means the leg is already in flight or closed, so treat the replay as a no-op.
Callback URL works in the aggregator test console but not for live sessions	wrong tenant	The `/callback/<tenantId>` path segments were swapped on a dashboard save.	Re-paste the exact URL from the Numbers → USSD page and confirm the tenant id; the path is the whole credential.

Triage in the 409 → 422 → 502 order. The call layer checks config → body → dispatch, so a second retry may legitimately move from one class to the next as each layer passes.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Send USSD push (network-initiated) sessions end to end

1. What USSD is, and when push beats SMS or voice

2. Point the aggregator at your callback URL

3. Shape the menu the push resumes against

4. Worked example: a three-branch balance-and-topup tree

5. Configure the push provider

6. Dispatch a session

7. Idempotency and retries

8. Test before a carrier ever sees traffic

9. Troubleshooting carrier-handled failures

See Also

​1. What USSD is, and when push beats SMS or voice

​2. Point the aggregator at your callback URL

​3. Shape the menu the push resumes against

​4. Worked example: a three-branch balance-and-topup tree

​5. Configure the push provider

​6. Dispatch a session

​7. Idempotency and retries

​8. Test before a carrier ever sees traffic

​9. Troubleshooting carrier-handled failures

​See Also

1. What USSD is, and when push beats SMS or voice

2. Point the aggregator at your callback URL

3. Shape the menu the push resumes against

4. Worked example: a three-branch balance-and-topup tree

5. Configure the push provider

6. Dispatch a session

7. Idempotency and retries

8. Test before a carrier ever sees traffic

9. Troubleshooting carrier-handled failures

See Also