USSD API Guide

Kemru Shared USSD API – Dev Guide

The client will be required to provide a callback URL in the format shown below. The callback URL should accept the following parameters:

MSISDN: Mobile number of the end user accessing the USSD code
SESSIONID: A unique session number that is maintained till the end of a USSD session
USSDCODE: A USSD code such as *415#. Kemru shall configure this shortcut code or the full code on application by the client.
INPUT: What the end user entered after accessing the USSD service.

New input values keep appending to the initial input. Details below.

http://<IP>/<PATH>/<SCRIPT>?SESSIONID=$SESSIONID&USSDCODE=$USSDCODE&MSISDN=$MSISDN&INPUT=$INPUT

e.g
http://10.1.11.12/ussdScripts/saccoA.php?SESSIONID=233443&USSDCODE=*415#&MSISDN=254726770792&INPUT=33

Sample client script response:

CON Welcome to XXX services. Please select an option
1. Register
2. Support

If a user selects option 1: sample response can be:

CON Please enter your name below

If a user selects option 2: sample response can be:

END Contact our support on the following numbers 2547xxxxxxx, 25402xxxxx.

Note the CON and END keywords before any response.

CON will let the Mobile Operators maintain the session. A session will be cancelled if a response message doesn’t start with CON.

END instructs the Mobile Operators to end a session. A user will be presented with a flash message (the message after the END keyword) without an option to input any text.

Sample Code In PHP

<?php
//Get the variables from the USSD gateway
$SESSIONID = $_GET["SESSIONID"];
$USSDCODE = rawurldecode($_GET["USSDCODE"]);
$MSISDN = $_GET["MSISDN"];
$INPUT = rawurldecode($_GET["INPUT"]);

//INPUT can be 33 or 33*2*Dan etc depending on level where the user is in the session
//Note that this can be used together with the session id to know which level the user is so that you can display a different menu

$inputArray = explode("*", $INPUT); //the last value after * is what the user entered last
$lastInput = $inputArray [sizeof($inputArray) - 1]; //if on a shared ussd, the initial input will be the identifier of the shared code. e.g *415*33# .. this input will be 33

//this is the entry point
if ($lastInput == "33") { 
$response = "CON Welcome to XXX services. Please select an option\n1.Register\n2.Support"; //note the NEW LINE \n
} else if ($lastInput == "1") {
//Register option
//Input validation and business logic can go here
$response = "CON Please enter your name below";
} else if ($lastInput == "2") {
//Support contact request
$response = "END Contact our support on the following numbers 2547xxxxxxx, 25402xxxxx.";
} else {
$response = "END This option has not been implemented yet. Please try again later.";
}
//print out the response
header('Content-type: text/plain');
echo $response;
?>