Smart USSD

Introduction

This Document gives detailed information on how to integrate with the Smart USSD via the API services. It also serves USSD content providers who wish to serve USSD menus for end-users connected to the networks configured on this system.

NB: The Smart USSD service is available on all the Telecommunication Networks in Ghana.

SMART USSD HTTP API

Instructions

The Smart USSD HTTP API requires content providers (Developers) to provide a URL that accepts the following parameters using the GET method:

NB: All parameters are strings.

Parameters For USSD Api

Parameters	Type	Position	Required	Description
network	STRING	1	YES	The network from which the traffic originated. This will always be provided by WIGAL and must be returned as it is, in the response string.
sessionid	STRING	4	YES	The unique string that identifies each session the end-user starts. This will always be provided by WIGAL and must be returned as it is, in the response string
mode	STRING	2	YES	This is used to determine if you require an input from the end-user or not. The below are the specific mode needed in CAPITAL LETTERS. START (New session) MORE (Require input) END (Close session).
msisdn	STRING	3	YES	Phone number of the end-user. This will always be provided. by WIGAL and must be returned as it is, in the response string.
userdata	STRING	5	YES	Data from the end-user or Data from Content Providers. This must be provided by the Content Provider.
username	STRING	6	YES	Your username registered with WIGAL. This will always be provided by WIGAL and must be returned as it is, in the response string.
trafficid	STRING	7	YES	Uniquely identifies every traffic even if from the same session. This will always be provided by WIGAL and must be returned as it is, in the response string.
other	STRING	8	NO	Optional reference data by Third-Party. Parameter will be returned in the next request same as provided by third-party.

EXPECTED RESPONSE FROM CONTENT PROVIDERS

Wigal USSD API expects response from content provider as a string delimited by the pipe character "|". The fields expected are detailed below followed by an example string in the required format: The "^" Character is used as a newline indicator.

Parameters in their correct positions:

							
    NETWORK|MODE|MSISDN|SESSIONID|USERDATA|USERNAME|TRAFFICID|OTHER

Sample HTTP String Request:

							
    WIGAL_MTN_GH|MORE|233276128036|10981013|Welcome:^1.Ringtones^2.Lifestyle^3.News|wigal|adc62161-05b2-4af5-98b1-a66c67f85c9d|first_menu

To display content on separate lines for a menu, the ^ character can be used as above. The above will achieve the menu displayed as below;

Welcome:
1.Ringtones
2.Lifestyle
3.News

Without the ^ character, the menu displayed will be as below:

Welcome: 1.Ringtones 2.Lifestyle 3.News

NB:The maximum number of characters that can be displayed on a page must not be more than 160 Characters including White Spaces. If this condition is not met the message will be truncated and will not display the whole message. Also note that special characters like "$<&" must not be part of the USERDATA passed, as this will not allow the USSD menus to be displayed.

EXAMPLE SERVICE REQUEST

The below is a sample callback URL provided by a content provider (Developer):

							
    https://192.168.10.12/service.php

WIGAL SMART USSD API invokes:

							
    https://192.168.10.12/service.php?network=wigal_mtn_gh&sessionid=12345&mode=start&msisdn=233276128036&userdata=&username=wigal
    &trafficid=adc62161-05b2-4af5-98b1-a66c67f85c9d&other=first_menu

Content Provider responds with string:

							
    "wigal_mtn_gh|MORE|233276128036|12345|Welcome:^1.Ringtones^2.Lifestyle^3.News|wigal|adc62161-05b2-4af5-98b1-a66c67f85c9d|1"

WIGAL SMART USSD API receives the response and parse the request, and depending on that particular network setups, it generates an appropriate network response in protocols such as SMPP, SOAP, SS7, etc. and send to the respective network operator.

End-User receives USSD Response on Phone as below:

Welcome:
1.Ringtones
2.Lifestyle
3.News

Developers Example in PHP

Get a complete sample PHP script with it’s Database structure on our Github page here:

Github Repository

Below is a sample PHP script:

							
                                
PHP

$MSISDN = $_GET['msisdn'];
$SESSION_ID =$_GET['sessionid'];
$NETWORKID = $_GET['network'];
$MODE = $_GET['mode'];
$DATA = $_GET['userdata'];
$USERNAME= $_GET[‘username’];
$TRAFFIC_ID= $_GET['trafficid'];
$OTHER= $_GET[‘other’];
$RESPONSE_DATA = "";

//STEP ONE CHECK IF ITS START OF SESSION
if ($MODE=="start"){
    $RESPONSE_DATA="$NETWORKID|MORE|$MSISDN|$SESSION_ID|Welcome to Bank Mobile^Select Service^1.Balance Enquiry^2.Pin Reset|$USERNAME |$TRAFFIC_ID|$OTHER";
}
else{
if ($DATA=="1" )
    $RESPONSE_DATA = "$NETWORKID|END|$MSISDN|$SESSION_ID|Your balance enquiry is being processed. You will receive a reply shortly|$USERNAME |$TRAFFIC_ID|$OTHER ";

if($DATA=="2")
    $RESPONSE_DATA = "$NETWORKID|END|$MSISDN|$SESSION_ID|A default pin will be sent to you shortly. |$USERNAME |$TRAFFIC_ID|$OTHER";
}
echo $RESPONSE_DATA;