Wherever Your Customers Are,
Reach Them With
Our USSD API
Start building for free

USSD API

Processing USSD requests using our API is very easy once your account is set up. In particular, you will need to:

  • Register a service code with us.
  • Register a URL that we can call whenever we get a request from a client coming into our system.

Once you register your callback URL, any requests that we receive belonging to you will trigger a callback that sends the request data to that URL using HTTP POST.

All you have to do at this point is print the string response that you would like us to send back to the user.

A few things to note about USSD:

  • USSD is session driven. Every request we send you will contain a sessionId, and this will be maintained until that session is completed
  • You will need to let the Mobile Service Provider know whether the session is complete or not. If the session is ongoing, please begin your response with CON. If this is the last response for that session, begin your response with END.
  • If we get a HTTP error response (Code 40X) from your script, or a malformed response (does not begin with CON or END), we will terminate the USSD session gracefully.

API URL V1:

https://api.helliomessaging.com/v1/ussd/request


Request Method: POST


Content-Type: application/json

Request Parameters

The API makes a HTTP POST request to your server with parameters shown below. This request is made when the user dials a USSD code and every time they respond to a menu.

Parameter Type Description Required
sessionId String A unique value generated when the session starts and sent every time a mobile subscriber response has been received Required
phoneNumber String The number of the mobile subscriber interacting with your ussd application Required
networkCode String The telco of the phoneNumber interacting with your ussd application Required
serviceCode String This is the USSD code assigned to your application Required
text String This shows the user input. It is an empty string in the first notification of a session. After that, it concatenates all the user input within the session with a until the session ends. Required

Overview


        // Reads the variables sent via POST from our gateway
        $sessionId   = $_POST["sessionId"];
        $serviceCode = $_POST["serviceCode"];
        $phoneNumber = $_POST["phoneNumber"];
        $text        = $_POST["text"];

        if ($text == "") {
            // This is the first request. Note how we start the response with CON
            $response  = "CON What would you want to check \n";
            $response .= "1. My Account \n";
            $response .= "2. My phone number";

        } else if ($text == "1") {
            // Business logic for first level response
            $response = "CON Choose account information you want to view \n";
            $response .= "1. Account number \n";
            $response .= "2. Account balance";

        } else if ($text == "2") {
            // Business logic for first level response
            // This is a terminal request. Note how we start the response with END
            $response = "END Your phone number is ".$phoneNumber;

        } else if($text == "1*1") { 
            // This is a second level response where the user selected 1 in the first instance
            $accountNumber  = "ACC1001";

            // This is a terminal request. Note how we start the response with END
            $response = "END Your account number is ".$accountNumber;

        } else if ( $text == "1*2" ) {
            // This is a second level response where the user selected 1 in the first instance
            $balance  = "GHC 1000";

            // This is a terminal request. Note how we start the response with END
            $response = "END Your balance is ".$balance;
        }

        // Echo the response back to the API
        header('Content-type: text/plain');
        echo $response;