Easily compose USSD menus in Node.js, compatible with Africastalking API, Hubtel API, Emergent API, South Pawsl API, Nalo API, Arkesel API and Beem API.
- For Sponsorship Kindly send me a contact me on Linkedin.
$ npm install ussd-builder
or
$ yarn add ussd-builder
- Use intuitive states to compose USSD menus
- Makes it easier to build complex nested menus
- Use simple input matching or regular expressions, custom asynchronous functions to resolve routes from one state to another
- The state-based approach allows you to easily modularize complex menus in different files
const UssdMenu = require('ussd-builder');
let menu = new UssdMenu();
// Define menu states
menu.startState({
run: () => {
// use menu.con() to send response without terminating session
menu.con('Welcome. Choose option:' +
'\n1. Show Balance' +
'\n2. Buy Airtime');
},
// next object links to next state based on user input
next: {
'1': 'showBalance',
'2': 'buyAirtime'
}
});
menu.state('showBalance', {
run: () => {
// fetch balance
fetchBalance(menu.args.phoneNumber).then((bal)=>{
// use menu.end() to send response and terminate session
menu.end('Your balance is GHC ' + bal);
});
}
});
menu.state('buyAirtime', {
run: () => {
menu.con('Enter amount:');
},
next: {
// using regex to match user input to next state
'*\\d+': 'buyAirtime.amount'
}
});
// nesting states
menu.state('buyAirtime.amount', {
run: () => {
// use menu.val to access user input value
var amount = Number(menu.val);
buyAirtime(menu.args.phoneNumber, amount).then((res)=>{
menu.end('Airtime bought successfully.');
});
}
});
// Registering USSD handler with Express
app.post('/ussd', (req, res)=>{
menu.run(req.body, ussdResult => {
res.send(ussdResult);
});
});The USSD Menu Builder uses a state machine to create a USSD menu. A state is created for each menu. Each state has a unique name and a set of rules used to link to other states based on the user input.
Before you can create any states, you first need to create an instance of the menu.
const UssdMenu = require('ussd-builder');
const menu = new UssdMenu();The menu.run(args, resultCallback) goes through the menu and finds
the appropriate state to run based on the user input.
The args object should contain the following keys coming from
the Africastalking API:
sessionId: unique session ID that persists through the entire USSD session, can be used to store temporary that may be retrieved from different states during the sessionserviceCode: the USSD code registered with your serviceCodeoperator: the end user's phone NumberphoneNumber: the end user's phone Numbertext: The raw USSD input. It has the following format1*2*4*1: a string containing the input at each hop, separated by the asterisk symbol (*). This is parsed by theUssdMenuto find the appropriate state to run at each hop.
After the matched state runs, the resultCallback is called with the response from the state.
Note: The menu also returns a promise that can be resolved if you need to do anything with the final response.
for example:
let resp = await menu.run(args) // resultCallback is not necessarry if you intend to run the menu in an async functionHere's an example registering a handler with the express framework:
app.post('/ussd', (req, res) => {
let args = {
phoneNumber: req.body.phoneNumber,
sessionId: req.body.sessionId,
serviceCode: req.body.serviceCode,
Operator: req.body.networkCode || req.body.Operator,
text: req.body.text
};
menu.run(args, resMsg => {
res.send(resMsg);
});
})Handling menu.run response:
app.post('/ussd', async (req, res) => {
let args = {
phoneNumber: req.body.phoneNumber,
sessionId: req.body.sessionId,
serviceCode: req.body.serviceCode,
Operator: req.body.networkCode || req.body.Operator,
text: req.body.text
};
let resMsg = await menu.run(args);
res.send(resMsg);
})The menu.state(name, options) method is used to define states. I takes the name of the state
and an object with the following properites:
run: a function that's called when the state is resolvednext(optional): an object that contains rules of how to match the input of this state to other states. This is not required for final states.defaultNext(optional): the name of the state to default to if the user input could not be matched by the rules defined in thenextobject. If not provided, the same state will be used as a fallback i.e. the same menu will be displayed to the user.
Here's an example:
menu.state('stateName', {
run: function(){
menu.con('Choose Option' +
'\n1. Load Account' +
'\n2. View Catalogue' +
'\n3. Check Balance'
);
},
next: {
'1': 'loadAccount',
'2': 'catalogue',
'3': 'balance'
},
defaultNext: 'invalidOption'
});Each state defines it's own run method which is called when that
state is matched. This is where you should place the logic for a given
state.
Use menu.val property to access the current user input.
You can access the ussd parameters through the menu.args object.
This parameters should come from the API Gateway and are passed to the
menu.run method.
You must use either (not both) of the two methods to send a response to be displayed to the user:
menu.con(msg): Sends the result to be displayed to the user without terminating the session i.e. the user can reply with further input.menu.end(msg): Sends the response to be displayed to the user and requests the session to be terminated i.e. the user cannot provide further input. Note: This consequently makes the state a final state and therefore thenextobject does not need to be defined
Example:
menu.state('thisState', {
run: function(){
let value = menu.val;
let session = getSession(menu.args.sessionId);
let phone = menu.args.phoneNumber;
let network = menu.args.network;
session.set('phone', phone);
session.set('phone', network);
session.set('value', value);
menu.end('You entered: ' + value);
}
});This is the first state or first menu to be displayed by the user.
It is created using the menu.startState(options). It uses
the reserved name '__start__'.
menu.startState({
run: function(){
...
}
next: {
...
}
});Note: the menu.state() and menu.startState() methods return
the same menu object instance for convenience.
menu.startState({
...
})
.state('state1', {
...
})
.state('state2', {
...
})To link states you use the next object to map user input to a state name.
You can match input directly by value or with a regular expression.
Simply add the expected string value as a key in the next object.
Begin the key with an asterisk (*) to indicate that the key should
be treated like a regular expression e.g. '*\\[a-zA-Z]+' would match
any input containing only lowercase or uppercase letters.
Remember you can use menu.val in the matched state to retrieve the actual user input.
Example:
menu.state('registration', {
run: function(){
menu.con('Enter your name');
},
next: {
'*[a-zA-Z]+': 'registration.name'
}
});
menu.state('registration.name', {
run: function(){
let name = menu.val;
let session = getSession(menu.args.sessionId);
session.set('name', name);
menu.con('Enter your email');
},
next: {
'*\\w+@\\w+\\.\\w+': 'registration.email'
}
});If the start state does not define a run method, you provide
an empty string as key in next to redirect to another state.
menu.startState({
next: {
'': function(){
if(user){
return 'userMenu';
}
else {
return 'registerMenu';
}
}
}
});Beside mapping user input directly to a state name, you can map it to a function with returns a state name, synchronously with a simple return statement or asynchronously with a callback or a promise.
menu.state('thisState', {
...
next: {
'input': 'nextState'
}
})menu.state('thisState', {
...
next: {
'input': function(){
if(test){
return 'nextState';
} else {
return 'otherState';
}
}
}
});menu.state('thisState', {
...
next: {
'input': function(callback){
runAsyncCode(function(err, res){
if(res){
callback('nextState');
} else {
callback('otherState');
}
})
}
}
});menu.state('thisState', {
...
next: {
'input': function(){
return new Promise((resolve, reject) => {
resolve('nextState');
});
}
}
});You can jump to a different state from the run function of one
state using the menu.go(stateName) method. This effectively
breaks the state chain (subsequent states will not be reachable)
and is therefore only useful if jumping to a final state.
menu.state('thisState', {
run: function(){
menu.go('otherState');
}
});
menu.state('otherState', {
run: function(){
menu.end('Thank you!');
}
});The menu.goStart() method can be used to jump to the start state
from within another state.
The library treats a USSD menu like a chain of interlinked states and therefore has not internal concept of nesting. However you can achieve complex menus with nested submenus by linking states appropriately. In addition you could use a naming convention of your choice to make it clearer to see how states are related. In these examples I used the following convention of separating menu levels with a dot.
You can store temporary user data that persists through an entire session. The library provides a way for you to define your own custom session handler so you're free to use whatever storage backend or driver you want. The menu provides an easy interface to set and retrieve session data within states based on the implementation you provide.
The menu.sessionConfig(config) method is used to define your session
handler. It accepts an object with the implementations of the following
methods:
start[function(sessionId, callback)]: used to initialize a new session, invoked internally by themenu.run()method before any state is called.end[function(sessionId, callback)]: used to delete current session, invoked internally by themenu.end()method.set[function(sessionId, key, value, callback)]: used to store a key-value pair in the current session, invoked internally bymenu.session.set().get[function(sessionId, key, callback)]: used to retrieve a value from the current session by key, invoked internally bymenu.session.get().
let sessions = {};
let menu = new UssdMenu();
menu.sessionConfig({
start: (sessionId, callback){
// initialize current session if it doesn't exist
// this is called by menu.run()
if(!(sessionId in sessions)) sessions[sessionId] = {};
callback();
},
end: (sessionId, callback){
// clear current session
// this is called by menu.end()
delete sessions[sessionId];
callback();
},
set: (sessionId, key, value, callback) => {
// store key-value pair in current session
sessions[sessionId][key] = value;
callback();
},
get: (sessionId, key, callback){
// retrieve value by key in current session
let value = sessions[sessionId][key];
callback(null, value);
}
});Note: Instead of callbacks, you may also return promises from those methods:
menu.sessionConfig({
...
get: function(sessionId, key){
return new Promise((resolve, reject) => {
let value = sessions[sessionId][key];
resolve(value);
});
}
})And then to add and retrieve data inside states, use the
menu.session object:
menu.state('someState', {
run: () => {
let firstName = menu.val;
menu.session.set('firstName', firstName)
.then( () => {
menu.con('Enter your last name');
})
}
...
})
...
menu.state('otherState', {
run: () => {
menu.session.get('firstName')
.then( firstName => {
// do something with the value
console.log(firstName);
...
menu.con('Next');
})
}
})
...Note: The menu.session's methods also work with callbacks:
menu.session.set('key', 'value', (err) => {
menu.con('...');
});
menu.session.get('key', (err, value) => {
console.log(value);
...
});Note: It's not required to configure a session handler. You can access your storage driver directly if you prefer. However if you do configure a handler using the above method then you should provide implementations for all the 4 methods as shown above..
UssdMenu instances emit an error event when an error occurs during the
state resolution process (e.g: "state not found" or "run function not defined").
menu.startState({
...
next: {
'1': 'nonExistentState'
}
});
menu.on('error', (err) => {
// handle errors
console.log('Error', err);
});
args.text = '1';
menu.run(args);In addition, errors passed to the callback of the session handler's methods or
rejected by their promises will also trigger the error event for convenience
so that you can handle your handle errors in one place.
menu.sessionConfig({
...
get: (sessionId, key, callback){
callback(new Error('error'));
}
});
menu.on('error', err => {
// handle errors
console.log(err);
});
...
menu.state('someState', {
run: () => {
menu.session.get('key').then(val => {
...
});
// you don't have to catch the error here
}
});As of version 1.0.0, ussd-builder has added support for Hubtel's USSD API by providing the provider option when creating the UssdMenu object. There are no changes to the way states are defined, and the HTTP request parameters sent by Hubtel are mapped as usual to menu.args, and the result of menu.run is mapped to the HTTP response object expected by Hubtel (menu.con returns a _Type: Respons & menu.end returns a Type: Release). The additional HTTP request parameters like ClientState, and Sequence are not used.
The key difference with Hubtel is that the service only sends the most recent response message, rather than the full route string. The library handles that using the Sessions feature, which requires that a SessionConfig is defined in order to store the session's full route. This is stored in the key route, so if you use that key in your application it could cause issues.
menu = new UssdMenu({ provider: 'hubtel' });
// Define Session Config & States normally
menu.sessionConfig({ ... });
menu.state('thisState', {
run: function(){
...
});
});
app.post('/ussdHubtel', (req, res) => {
menu.run(req.body, resMsg => {
// resMsg would return an object like:
// { "Type": "Response", "Message": "Some Response" }
res.json(resMsg);
});
})As of version 1.1.1, ussd-builder has added support for Emergent's USSD API by providing the provider option when creating the UssdMenu object. There are no changes to the way states are defined, and the HTTP request parameters sent by Emergent are mapped as usual to menu.args, and the result of menu.run is mapped to the HTTP response object expected by Emergent (menu.con returns a _Type: Respons & menu.end returns a Type: Release). The additional HTTP request parameters like ClientState, and Sequence are not used.
Emergent is same as Hubtel, the service only sends the most recent response message, rather than the full route string. The library handles that using the Sessions feature, which requires that a SessionConfig is defined in order to store the session's full route. This is stored in the key route, so if you use that key in your application it could cause issues.
menu = new UssdMenu({ provider: 'emergent' });
// Define Session Config & States normally
menu.sessionConfig({ ... });
menu.state('thisState', {
run: function(){
...
});
});
app.post('/ussdEmergent', (req, res) => {
menu.run(req.body, resMsg => {
// resMsg would return an object like:
// { "Type": "Response", "Message": "Some Response", }
res.json(resMsg);
});
})As of version 1.2.0, ussd-builder has added support for SouthPawsl's USSD API by providing the provider option when creating the UssdMenu object. There are no changes to the way states are defined, and the HTTP request parameters sent by SouthPawsl are mapped as usual to menu.args, and the result of menu.run is mapped to the HTTP response object expected by SouthPawsl (menu.con returns a State: CONTINUE & menu.end returns a State: END). The additional HTTP request parameters like ClientState, and Sequence are not used.
The key difference with SouthPawsl is that the service only sends the most recent response message, rather than the full route string. The library handles that using the Sessions feature, which requires that a SessionConfig is defined in order to store the session's full route. This is stored in the key route, so if you use that key in your application it could cause issues.
menu = new UssdMenu({ provider: 'southpawsl' });
// Define Session Config & States normally
menu.sessionConfig({ ... });
menu.state('thisState', {
run: function(){
...
});
});
app.post('/ussdSouthpawsl', (req, res) => {
menu.run(req.body, resMsg => {
// resMsg would return an object like:
// { "state": "CONTINUE", "message": "Some Response" }
res.json(resMsg);
});
})As of version 1.1.2, ussd-builder has added support for Nalo Solutions USSD API by providing the provider option when creating the UssdMenu object. There are no changes to the way states are defined, and the HTTP request parameters sent by Nalo are mapped as usual to menu.args, and the result of menu.run is mapped to the HTTP response object expected by Nalo (menu.con returns a MSGTYPE: true & menu.end returns a MSGTYPE: false). The additional HTTP request parameters like ClientState, and Sequence are not used.
Nalo USSD API only sends the most recent response message, rather than the full route string. The library handles that using the Sessions feature, which requires that a SessionConfig is defined in order to store the session's full route. This is stored in the key route, so if you use that key in your application it could cause issues.
For more detail visit documentation at https://documenter.getpostman.com/view/3709759/SzYaVxgQ?version=latest
menu = new UssdMenu({ provider: 'nalo' });
// Define Session Config & States normally
menu.sessionConfig({ ... });
menu.state('thisState', {
run: function(){
...
});
});
app.post('/ussdNalo', (req, res) => {
menu.run(req.body, resMsg => {
// resMsg would return an object like:
// { "MSGTYPE": "true", "MSG": "Some Response", }
res.json(resMsg);
});
})As of version 1.1.7, ussd-builder has added support for Arkesel USSD API by providing the provider option when creating the UssdMenu object. There are no changes to the way states are defined, and the HTTP request parameters sent by Arkesel are mapped as usual to menu.args, and the result of menu.run is mapped to the HTTP response object expected by Arkesel (menu.con returns a continueSession: true & menu.end returns a continueSession: false). The additional HTTP request parameters like ClientState, and Sequence are not used.
Arkesel USSD API only sends the most recent response message, rather than the full route string. The library handles that using the Sessions feature, which requires that a SessionConfig is defined in order to store the session's full route. This is stored in the key route, so if you use that key in your application it could cause issues.
For more detail visit documentation at https://developers.arkesel.com/#tag/Overview
menu = new UssdMenu({ provider: 'arkesel' });
// Define Session Config & States normally
menu.sessionConfig({ ... });
menu.state('thisState', {
run: function(){
...
});
});
app.post('/ussdArkesel', (req, res) => {
menu.run(req.body, resMsg => {
// resMsg would return an object like:
// { "continueSession": "true", "message": "Some Response", }
res.json(resMsg);
});
})As of version 1.1.7, ussd-builder has added support for Beem USSD API by providing the provider option when creating the UssdMenu object. There are no changes to the way states are defined, and the HTTP request parameters sent by Beem are mapped as usual to menu.args, and the result of menu.run is mapped to the HTTP response object expected by Beem (menu.con returns a command: continue & menu.end returns a command: terminate). The additional HTTP request parameters like request_id, and Sequence are not used.
Beem USSD API only sends the most recent response message, rather than the full route string. The library handles that using the Sessions feature, which requires that a SessionConfig is defined in order to store the session's full route. This is stored in the key route, so if you use that key in your application it could cause issues.
For more detail visit documentation at https://docs.beem.africa/ussd/index.html
menu = new UssdMenu({ provider: 'beem' });
// Define Session Config & States normally
menu.sessionConfig({ ... });
menu.state('thisState', {
run: function(){
...
});
});
app.post('/ussdBeemAfrica', (req, res) => {
menu.run(req.body, resMsg => {
// resMsg would return an object like:
// {
// "msisdn": "+233546467407",
// "operator": "vodacom",
// "command": "continue",
// "payload": {
// "request_id": 84939983,
// "request": "Some Response"
// }
// }
res.json(resMsg);
});
})