USSD

Launch a Menu

To handle a USSD request(and hence serve your menus), you will need to set up a webhook or callback url on the sandbox dashboard that Africa's Talking USSD gateway can send POST requests to every time a user dials into your USSD code or respond to your menus.

This callback should be accessible via HTTP on the web. In case you are developing your application on localhost, you can use either Vagrant (Vagrant Share) or Ngrok to provide a publicly avalailable URL to Africa's Talking.

You also need a web server that serves your USSD application online. We use the Python Flask framework which is light, easy to use and provides a web server out of the box.

We are going to receive USSD requests from a callback(essentially a script) running from the folder projectName that we created when we did the Setup and Dependencies session.

In addition, you should install the Flask framework in your projectName folder via pip as follows.

(windows)

projectName> python -m pip install Flask

(linux)

projectName$ pip install Flask

You should have created a USSD code on your sandbox dashboard to interact with the simulator.

In the projectName folder, create a script USSD.py and copy-paste the code below. In the code we are receiving the USSD request as a HTTP POST and based on the string in the text string, menus are served.

1. Import Flask into the script
2. Create a route - in this case /api/ussd/callback
3. Run your application on the terminal: python USSD.py
4. Your callback is now http://your-applications-ip/api/ussd/callback
5. Copy the callback to your dashboard

#-> projectName/USSD.py

from flask import Flask
from flask import request
from flask import make_response

app = Flask(__name__)

@app.route('/api/ussd/callback', methods=['POST'])
def ussd_callback():
    session_id = request.values.get("sessionId", None)
    serviceCode = request.values.get("serviceCode", None)
    phoneNumber = request.values.get("phoneNumber", None)
    text = request.values.get("text", None)

    #serve menus based on text
    if text == "":
        menu_text = "CON What would you want to check \n"
        menu_text += "1. My Account \n"
        menu_text += "2. My phone number \n"
        menu_text += "3. My branch"

    elif text =="1":
                menu_text = "CON Choose the account information that you want to view \n"
                menu_text += "1. My Account balance\n"
                menu_text += "2. My Account number \n"

        elif text =="2":
                menu_text = "END Your phone number is "+phoneNumber

        elif text =="1*1":
                menu_text = "END Your account number is ACOO10SWO2101."

        elif text =="1*2":
                menu_text = "END Your BALANCE  is KES 120/-"

    resp = make_response(menu_text, 200)
    resp.headers['Content-Type'] = "text/plain"
    return resp


if __name__ == "__main__":
        app.run()

Fire up the simulator, register with your number.

Run your code to interact with the simulator:

python USSD.py

You can now dial the USSD code that you registered on your dashboard. You should see your menu served on the simulator.