Skip to main content
Every USSD session is a series of request-response interactions between the subscriber, Belio, and your application. Each time the subscriber enters a menu option, Belio sends a new POST request to your callback endpoint containing the complete input history for the current session. Your application processes the request and returns the next screen to display (CON) or ends the session (END). The diagram below illustrates a typical USSD session from the initial dial through multiple menu selections until the session is completed. Think of the integration as a loop:
  1. The subscriber dials *123#.
  2. Belio sends inputs=[] to your callback URL.
  3. Your application returns CON with the main menu.
  4. The subscriber presses 1, then Belio sends inputs=["1"].
  5. Your application returns CON with the next screen.
  6. The subscriber presses 2, then Belio sends inputs=["1", "2"].
  7. Your application returns either CON to continue or END to close the session.
Your USSD application receives a JSON POST request for every subscriber interaction and must respond with the next screen.

​
Action Meaning

​
Input Handling

The inputs array contains the subscriber’s cumulative selections for the session, so every request carries the full path already taken:
  • First dial -> inputs: []
  • After selecting 1 -> inputs: ["1"]
  • After then selecting 2 -> inputs: ["1", "2"]
  • After then selecting 3 -> inputs: ["1", "2", "3"]
Belio sends the full input history on every request, not just the latest keystroke. Your callback should either:
  • Re-process all inputs from scratch on each request, or use sessionId to load session state and determine which input is new.

​
Sample expected responses from your application

  • Continue the session and show the next menu screen. This response tells Belio to keep the session open and show the subscriber the next menu screen.
  • End the session and close the USSD dialog:

​
Callback Endpoint

Configure the callback URL on your USSD service channel in the Belio Cloud Portal. Belio sends a POST request to your callback URL with the session state for the current hop.

​
Request Payload

Belio forwards a UssdForwardRequest payload.

​
Response Format

Return HTTP 200 with a JSON body in the following shape:

​
Callback Requirements

Belio retries failed callbacks with exponential backoff, up to 5 attempts by default. Malformed JSON responses are not retried.

​
Invalid Responses

If your callback returns a non-200 status, times out, or returns JSON that does not match the expected schema, Belio treats that hop as failed and shows an unavailable message to the subscriber.

​
Next Step

Use sessionId as the key for any server-side session storage. Belio also records session hops internally for observability.