Worked USSD session samples

USSD is not a message channel — it is a session channel. The subscriber dials a short code (for example *384*1#), the aggregator POSTs each step of the session to your callback URL, and your synchronous HTTP response is the next screen: a text/plain body that starts with CON (keep the session open, render the menu) or END (show a final message and terminate). Samples on this page therefore pair the aggregator’s callback and your reply body — one is meaningless without the other. For the interactive builder surface, see the USSD flow builder guide. Bodies are UTF-8 — menus routinely carry non-English prompts in the regions where USSD reaches feature phones, and any characters a GSM handset can render are valid in a prompt.

1. Define the session flow

PUT /api/v1/ussd/menu

A session flow is one menu tree: unique node ids, a root the initial dial renders, and option branches whose next points at another node. A node with no options — or with final: true — is a terminal screen (END); anything else renders its choices and continues (CON). Request

{
  "serviceCode": "*384*1#",
  "root": "main",
  "nodes": [
    {
      "id": "main",
      "prompt": "Karibu Acme. 1. Salio 2. Kununua",
      "options": [
        { "key": "1", "label": "Angalia salio", "next": "balance" },
        { "key": "2", "label": "Nunua airtime", "next": "topup" }
      ]
    },
    { "id": "balance", "prompt": "Salio lako ni TZS 4,200." },
    { "id": "topup", "prompt": "Ingiza kiasi (TZS).", "final": true }
  ]
}

The Swahili prompts above are ordinary UTF-8 in the body — no special encoding is needed.

{
  "data": {
    "menu": {
      "serviceCode": "*384*1#",
      "root": "main",
      "nodes": [
        {
          "id": "main",
          "prompt": "Karibu Acme. 1. Salio 2. Kununua",
          "options": [
            { "key": "1", "label": "Angalia salio", "next": "balance" },
            { "key": "2", "label": "Nunua airtime", "next": "topup" }
          ]
        },
        { "id": "balance", "prompt": "Salio lako ni TZS 4,200." },
        { "id": "topup", "prompt": "Ingiza kiasi (TZS).", "final": true }
      ]
    }
  },
  "meta": {
    "request_id": "req_menu_put",
    "timestamp": "2026-09-01T12:00:00.000Z"
  }
}

The tree is validated before anything is saved — duplicate node ids, a root naming no node, or an option next pointing at a missing node all return 422 (see step 4), so a broken graph never answers live sessions.

2. Handle a session callback

POST /api/v1/ussd/callback/{tenantId}

The public callback your aggregator (e.g. Africa’s Talking) POSTs to on every step of a session. On the initial dial the accumulated text is empty and the reply renders the root menu; on each later step the aggregator replays the full *-joined input and the reply renders the screen that input resolves to. Read the request and response together — the response is the screen. Aggregator request (form-encoded or JSON — both are accepted)

POST /api/v1/ussd/callback/<your_tenant_id>
Content-Type: application/x-www-form-urlencoded

sessionId=ATUid_3f9c1e2a7b4d85f0c1a2b3d4&serviceCode=*384*1%23&phoneNumber=%2B254700123456&text=

Your response — CON renders the next menu and keeps the session open

CON Karibu Acme.
1. Salio
2. Kununua

Text is UTF-8 end to end; the first token of the response body is all the protocol carries (CON / END). Aggregator request — the subscriber pressed 1

sessionId=ATUid_3f9c1e2a7b4d85f0c1a2b3d4&serviceCode=*384*1%23&phoneNumber=%2B254700123456&text=1

Your response — END shows a final message and terminates the session

END Salio lako ni TZS 4,200.

An unmatched keypress also ends the session — END Invalid selection. Session ended. — which is deliberate: USSD has no “back”, and re-prompting would loop because the aggregator replays the bad token on every callback. Idle sessions are closed by the operator (commonly 30–90 seconds), and because the engine is stateless a subscriber who re-dials and re-keys lands on the same screens — design every path to terminate within a few keypresses.

3. Read the session back

The engine is pure and stateless, so nothing is stored per session and there is no session-history API — “reading a session back” means fetching the flow definition and replaying the aggregator’s accumulated input through the simulator, which runs the same resolution the live callback runs.

GET /api/v1/ussd/menu

{
  "data": {
    "menu": {
      "serviceCode": "*384*1#",
      "root": "main",
      "nodes": [
        { "id": "balance", "prompt": "Salio lako ni TZS 4,200." }
      ]
    }
  },
  "meta": {
    "request_id": "req_menu_get",
    "timestamp": "2026-09-01T12:01:00.000Z"
  }
}

Then replay one step — the aggregator’s exact *-joined string — and inspect the node-visit outcome:

POST /api/v1/ussd/simulate

Request

{
  "text": "1"
}

{
  "data": {
    "action": "END",
    "message": "Salio lako ni TZS 4,200.",
    "node_id": "balance",
    "end_reason": null,
    "raw": "END Salio lako ni TZS 4,200."
  },
  "meta": {
    "request_id": "req_sim",
    "timestamp": "2026-09-01T12:02:00.000Z"
  }
}

data.raw is the exact text/plain body the live callback would return for that input, and node_id names the node the walk landed on — the per-step node-visit trail. Walk every path this way before pointing the aggregator at the callback: initial dial, one key per branch, each terminal screen, and one deliberately bad key to confirm the invalid-selection end.

4. Errors

422 — the flow graph is invalid. Any structural violation in the tree returns VALIDATION_ERROR and names the offending spot (issue paths point into nodes, options, or root — an option key may only contain digits, #, or *, because a handset can only send the 12-key DTMF set):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "option "2" points to unknown node "withdraw"",
    "status": 422,
    "details": {
      "issues": [
        {
          "field": "nodes.0.options.1.next",
          "message": "option "2" points to unknown node "withdraw""
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_menu_422",
    "timestamp": "2026-09-01T12:03:00.000Z"
  }
}

Re-send the tree with every next resolving to a node in nodes. Callback timeouts. The callback endpoint answers in milliseconds — there is no slow internal hop, so a hang on the subscriber’s side is almost always the operator’s idle-session timeout rather than a 504-class delay here. Two defensive cases still matter:

You publish no menu. A callback for a tenant with no configured menu gets END Service is not available. (HTTP 200) — the session closes gracefully instead of hanging the subscriber at a frozen prompt.
GET/PUT /menu times out. Retry with your meta.request_id — reads and writes are idempotent, and a replaced menu takes effect on the next callback.

Keep screens under roughly 160 characters and every path terminating; a menu that waits on input forever is the one shape an idle carrier will punish.

API Reference

All Endpoints

Worked USSD session samples