Source: Beeline

How to Build a USSD Application

building a USSD application…

Just in case you are pondering what is USSD and probably thinking if you can develop yours you are on the right article in building that so let’s get started.

According to Wikipedia:

Unstructured, Supplementary Service Data (USSD) sometimes referred to as “Quick Codes” or “Feature Codes” is a communications protocol used by GSM cellular telephones to communicate with the mobile network operator’s computers.

It can be used for WAP browsing, prepaid callback service, mobile-money services, location-based content services, menu-based information services, and as part of configuring the phone on the network.

Someone typing

So in a nutshell when you buy airtime and what to recharge it on your mobile phone you need to enter some codes the same also when you are trying to make a bank transfer to another account you still need to enter a designated code in other to complete the transaction. So those shortcodes you enter are known as USSD.

So let’s see some of the requirement’s we need to achieve this:

1. Basic understanding of PHP language
2. A text editor (Preferably Visual studio code)
3. Create an account on Africastalking
4. Create an account on Heroku
5. Download and install Git based on your OS

Why do we need those requirements, PHP will be the language we will use to give our commands while Africastalking will help us to create a two-way USSD functionality across mobile providers in Africa, Heroku is a cloud platform that we will deploy our code to manage. For further readings about them, you can check the link below

First, create an account on Africastalking to signup then follow the steps given and you will be brought to your dashboard.

Next, create an account on Heroku to signup then follow the steps given and you will be brought to your dashboard.

Also, download any text editor of your choice and open to it

<?php
// Reads the variables sent via POST
$sessionId   = $_POST["sessionId"];  
$serviceCode = $_POST["serviceCode"];  
$text = $_POST["text"];
//This is the first menu screen
if ( $text == "" ) {
$response  = "CON Hi welcome, I can help you with Event Reservation \n";
$response .= "1. Enter 1 to continue";
}
// Menu for a user who selects '1' from the first menu
// Will be brought to this second menu screen
else if ($text == "1") {
$response  = "CON  Pick a table for reservation below \n";
$response .= "1. Table for 2 \n";
$response .= "2. Table for 4 \n";
$response .= "3. Table for 6 \n";
$response .= "4. Table for 8 \n";
}
//Menu for a user who selects '1' from the second menu above
// Will be brought to this third menu screen
else if ($text == "1*1") {
$response = "CON You are about to book a table for 2 \n";
$response .= "Please Enter 1 to confirm \n";
}
else if ($text == "1*1*1") {
$response = "CON Table for 2 cost -N- 50,000.00 \n";
$response .= "Enter 1 to continue \n";
$response .= "Enter 0 to cancel";
}
else if ($text == "1*1*1*1") {
$response = "END Your Table reservation for 2 has been booked";
}
else if ($text == "1*1*1*0") {
$response = "END Your Table reservation for 2 has been canceled";
}
// Menu for a user who selects "2" from the second menu above
// Will be brought to this fourth menu screen
else if ($text == "1*2") {
$response = "CON You are about to book a table for 4 \n";
$response .= "Please Enter 1 to confirm \n";
}
// Menu for a user who selects "1" from the fourth menu screen
else if ($text == "1*2*1") {
$response = "CON Table for 4 cost -N- 150,000.00 \n";
$response .= "Enter 1 to continue \n";
$response .= "Enter 0 to cancel";
}
else if ($text == "1*2*1*1") {
$response = "END Your Table reservation for 4 has been booked";
}
else if ($text == "1*2*1*0") {
$response = "END Your Table reservation for 4 has been canceled";
}
// Menu for a user who enters "3" from the second menu above
// Will be brought to this fifth menu screen
else if ($text == "1*3") {
$response = "CON You are about to book a table for 6 \n";
$response .= "Please Enter 1 to confirm \n";
}
// Menu for a user who enters "1" from the fifth menu
else if ($text == "1*3*1") {
$response = "CON Table for 6 cost -N- 250,000.00 \n";
$response .= "Enter 1 to continue \n";
$response .= "Enter 0 to cancel";
}
else if ($text == "1*3*1*1") {
$response = "END Your Table reservation for 6 has been booked";
}
else if ($text == "1*3*1*0") {
$response = "END Your Table reservation for 6 has been canceled";
}
// Menu for a user who enters "4" from the second menu above
// Will be brought to this sixth menu screen
else if ($text == "1*4") {
$response = "CON You are about to book a table for 8 \n";
$response .= "Please Enter 1 to confirm \n";
}
// Menu for a user who enters "1" from the sixth menu
else if ($text == "1*4*1") {
$response = "CON Table for 8 cost -N- 250,000.00 \n";
$response .= "Enter 1 to continue \n";
$response .= "Enter 0 to cancel";
}
else if ($text == "1*4*1*1") {
$response = "END Your Table reservation for 8 has been booked";
}
else if ($text == "1*4*1*0") {
$response = "END Your Table reservation for 8 has been canceled";
}
//echo response
header('Content-type: text/plain');
echo $response
?>

From the above code snippet, we have some variables and keywords:

$sessionId: This generates a unique value when the session starts and sent every time a mobile subscriber response has been received.
$serviceCode: This refer to your USSD code
$text: This shows the user input. which is an empty string in the first notification of a session which after that concatenates all the user input within the session until the session ends.
$response: This hold the answer to the user input.
echo: Prints out the response for the user to read.
CON: It means an intermediate menu Or that the session is CONtinuing
END: Means the final menu and will trigger session termination i.e session is ENDing.

If that is done we need to deploy and host our application on Heroku to use.

On your dashboard on Heroku click on the new button and choose the create a new app option.

Enter the app name you want if the name is available. I am using africas-talking-api and click on the create app button.

scroll down a bit to where you see the link to download the Heroku CLI click the link and download base on your OS.

At this point, I assume you have Git installed already because we will be using commands

So open up the terminal or Git bash to the root folder of where you have the project for the USSD application

$ heroku login

login using your credentials to the Heroku CLI:

$ git init

Initialized the project as a Git repository:

$ heroku git:remote -a <Your app name here you created on heroku>

Adding the Heroku remote to have access to push to it:

$ git add .

Adding the file to Git for staging:

$ git commit -am "initial commit for ussd application"

Saving our work with a snapshot:

$ git push heroku master

Pushing to the Heroku master branch for deployment. If success, head over to Heroku, reload and click on the open app button at the top right then copy the URL.

The URL will look something like below:

Yeah, we are almost there. head back to Africa’s talking website.

Click on the Go To Sandbox app.

Click on the USSD section tab at the left-hand side and click on Create Channel.

Then add your channel number and enter the Heroku app url then click on create a channel.

Now, it’s time to test our application, click on the launch simulator.

Then choose your country from the dropdown option and enter your mobile number and click on launch.

Click on USSD from the simulator option

Then enter your service code in the input box provided and click on call, to simulate how it will work like when been use by the public.

So we just work on how to build/develop a USSD application that can be used for “table reservation”, which after getting/understanding the concepts you can come up with a project idea you can build on. You can also download the mobile app from Play store “Africa stalking” which will still do the same with the web simulator.

Note: Building the USSD and testing with the simulator is free but when you want the public to use your USSD code without using the simulator then you need to pay for the service, you might want to check the pricing out.

You can also check out the code on my Github repository.