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.
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;
?>