Creating a USSD application with NodeJS and Redis Part 1.

3 min readJun 11, 2021

Building USSD applications in NodeJS may seem straightforward and even a library away from getting everything up and running. After building several USSD applications with different libraries and not getting what I wanted, I came up with a custom solution. Hopefully, this can be helpful to you.

Several considerations need to be made when building an effective USSD solution. They include:

Menu Management — Manage how each screen is presented to the user and ensure dynamic menu builds.
Session Management — Manage how information is passed across different menus as the user traverses the application.
Dynamic Configuration — USSD applications should have multi-language support, support for different Mobile Network Operators(MNOs) requirements and should be highly customizable.

Lets build the solution

In this article we will build a USSD app with NodeJS and Redis. Redis is an open source in-memory data structure store, it will be used for session management.

Project Requirements:

Install NodeJS
Install typescript globally npm install -g typescript and npm install -g ts-node
Install a Redis server

Let’s set up the project:

mkdir ussd-project
cd ussd-project 
npm init -y
tsc --init

Update tsconfig.json file with the following

Install the following packages on the project:

npm i express nodemon redis
npm i @types/express @types/node @types/redis -D

Add nodemon.json file on the project base

Update scripts on your package.json folder as shown:

"scripts": {
"start": "ts-node src/app.ts",
"live": "nodemon --config nodemon.json src/app.ts"
}

Create this folder structure for the project:

ussd-project
└───scr
│   └───menu-builder
│   │    └───configs
│   │    └───core
│   │    └───lang
│   │    └───menus
│   │    └───states
│   │    │   └───controllers
│   │    └───typings
│   │    └───index.ts
│   └───app.ts
└───node_modules
└───nodemon.json
└───package.json
└───package-lock.json
└───tsconfig.json

Menu builder contains the following folders:

configs folder — Sets the base configurations for the project
core folder — Manage project input and session handling.
lang folder — Manage different menu languages.
menus folder — Manage creation of menus.
states folder — Manage menu states.
typings folder — Manage menu types (TypeScript)

Create the http server

Lets create a http server with express JS. Add a route to accept USSD requests and call the menu builder function. The menu builder function accepts the request body and a redis client as parameters.

src/app.ts

Create the menu builder configuration file

Project has a set of base configurations:

session_prefix — This unique identifier that is used to create sessions
default_lang — Default language used in the project
session_time — Lifetime of the session menu in seconds
start_state —The 1st state that runs
sequential_requests — Set whether the project should allow user to run sequential queries eg. *144*1*3*6#. It’s important since some MNOs do not allow sequential queries.

src/menu-builder/configs/index.ts

Create the language config

Create an English language file and add the following generic properties:

src/menu-builder/lang/en.ts

Create a file to manage all language options:

src/menu-builder/lang/index.ts

Create the menu builder types

Add TypeScript interface for the incoming request body.

src/menu-builder/typings/global.ts

Create the menu builder main file

With all base configurations set let us create the menu builder file. This is the entry point of our application.

src/menu-builder/index.ts

Run the Project

Run npm run start. Lets send a POST request to our server “http://localhost:4000/ussd”. You will get a response from the menu builder as shown below: