Process Flow

(1) Channel Mobile’s Platform receives initial USSD menu request from the mobile subscriber
(2) and starts the USSD menu session with the application server using this API specification. It sends HTTP GET request message containing request data to predefined server address
(3) and waits for XML response
(4) HTTP response contains USSD menu information that is sent back to the mobile subscriber

HTTP GET Request Data

HTTP GET Request Data (sent from Channel Mobile to 3rd Party Application Server on USSD session initiation)

msisdn - the user’s cellphone number

provider - indicates which service provider the msisdn is contracted to.
The possible values are:

• Vodacom
• MTN
• CellC
• Telkom_8t

ussdSessionId - this is a 10-digit number, unique to every USSD session.

request - the value input by the user on their mobile telephone.

requestid - this represents at what stage the user is in the USSD session. When a user first initiates a USSD session, this parameter’s value is ‘0’. On subsequent steps, it is the value as specified by the 3rd party application in their XML response string.

XML Response String

XML Response String (Sent by 3rd party back to Channel Mobile)

request tag - This tag encapsulates the entire XML structure. It has no attributes. It has the following subtags: <displaytext> and <requestid>. Both subtags are mandatory, and each may only appear ONCE in the XML.

displaytext tag - This tag contains the message that will be displayed on the mobile user's handset. Please note that all text must be XML encoded. It has no attributes. It has no subtags.

requestid tag - This tag represents the requestid identifier that is returned back to the 3rd party, which allows you can determine at what stage the user is in the USSD session (step 1, 2, 3 etc.).

It makes sense to set this value to ‘1’ for the first menu item, and increment it by 1 for each menu option thereafter, but it is up to the 3rd party application what value they wish to store here.

When you wish to end the session, make the requestid 99

PHP Example

<?php

          header('content-type: application/xml'); //return XML document

          $theMsisdn          = $_GET["msisdn"]; //the user's cell number

          $theProvider        = $_GET["provider"]; //the provider (vodacom, cellc etc)

          $theUserResponse    = trim(urldecode($_GET["request"])); //the user’s response text

          $theRequestid       = (int)trim(urldecode($_GET["requestid"])); //the requestid

          $theSessionID       = $_GET["ussdSessionId"]; //the sessionid

          $returnMessage      = "";

          $returnID           = "";

          //STEP 1 - session being initiated by end-user

          if ($theRequestid == 0){

            $returnMessage = "Welcome, this is step1!\n1. Option A\n2. Option B\n3. Option C";

            $returnID = "1";

          } else if ($theRequestid == 1){

            $returnMessage = "Welcome back, this is step2!\n1. Option 1\n2. Option 2\n3. Option 3";

            $returnID = "2";

          } else if ($theRequestid == 2){

          $returnMessage = "Welcome back, this is step3!\nLorem ipsum dolor sit amet, consectetur adipiscing

          elit. Donec ut erat auctor odio dictum volutpat quis ut nibh.";

          $returnID = "3";

          } else if ($theRequestid == 3){

            $returnMessage = "This is the last step, thank you!";

            $returnID = "99";

          }

          $xml = "<?xml version='1.0' encoding='utf-8' ?<request><displaytext>".

          htmlentities($returnMessage) . "</displaytext><requestid>" .

          $returnID . "</requestid></request>";

          echo $xml; ?>

USSD Timeouts and Character Limitations