Interacting with our USSD gateway

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 page 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. In the tutorials shown, we simply echo the response onto the browser for our gateway to pick up.

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 parameters

The API makes a POST request to your server with parameters shown below.

NB: The request is made when the user dials a USSD code and every time they respond to a menu

Parameter Method Description
sessionId POST This is a session unique value generated when the session starts and sent every time a mobile subscriber response has been received
phoneNumber POST This is the mobile subscriber number
serviceCode POST This is your USSD code. Please note that it doesn't show your channel for shared USSD codes.
text POST This shows the user input. It concatenates all the previous user input within the session with a *

You need a USSD callback URL where all your USSD requests will be forwarded.

To register your USSD notification callback url, please click here.

Processing USSD request via PHP

Now for some code :) The snippet below shows an example service that responds with the user's account number if the text received is "1", or the balance if the response is 2.

  • The system responds with a request to the user asking them to select whether they would want to view account details or phone number if text was blank (text received is "")
  • If the user selects 1 for My account(ie. text is "1"), the system will respond with account number if the user again selects 1 (ie. text received is "1*1"), or the balance if the response is 2 (ie text received is "1*2").
The user response gets attached to the previous responses every time they respond to the USSD menu.

<?php

// 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  = "KES 10,000";
	 // This is a terminal request. Note how we start the response with END
	 $response = "END Your balance is $balance";

}

// Print the response onto the page so that our gateway can read it
header('Content-type: text/plain');
echo $response;

// DONE!!!
?>