USSD Simulator

UI options

• Caller phone: using international format ( + )

• Short code: USSD code user contacts with

• Developer options: turn on to enable

  • URL: backend endpoint

  • Session ID: readonly field, generated on each “call”

  • Request logger: displays JSON response for each request

• Input: user’s answer for each interaction

• Send: performs a new request with provided input (can be triggered by pressing ‘Enter’ while input typing on input field)

• Message box: displays backend message response (breaklines are replaced for <br> tags)

• Call: (green) performs the initial request to the USSD backend endpoint. It creates a new session ID.

• Hang up: (red) ends current session and clears Message and Logger boxes.

USSD Request payloads: (USING bLive Format)

Each call to the backend performs a GET request with the following parameters:

• ms: caller phone (msisdn) in format 257xxxxxxxx

• op: operator friendly name (Fixed value for demo)

• inp: user input (empty string for first request)

• kw: A parameter used in bridge system to differentiate services (Fixed value for demo)

• tx: transaction number or session identifier

The expected response to each request will be a JSON object with the next parameters:

• session: transaction number or session identifier

• msisdn: phone number (msisdn) in format 257xxxxxxxx

• code: (optional) short code (Null for demo)

• message: text to be displayed to the user

• type: 

  • REQUEST: continue session

  • END: end session

PARSING bLive format request payload

In order to be aligned with previous code, an aux function can be:

const parseInputBLIVE = (data) => {
    let sessionId = data.tx
    let phoneNumber = data.ms[0]!=='+'?`+${data.ms}`:data.ms
    let shortCode = null
    let userInput = data.inp
    return {
        sessionId,
        phoneNumber,
        shortCode,
        userInput
    }
}
data: req.query (url parameters from GET request)

NOTES

• CORS issues: since the requests are performed from/to, for local development a header can be added to the response from the backend: Access-Control-Allow-Origin : *

• DHIS2 Requests: since the phone number (msisdn) coming from the provider input misses the + character for international format, this should be added and encoded when requesting phone number fields in DHIS2, e.g. if phone number at provider input is 12345678, requests to DHIS2 needs to be %2B12345678 (URL Encoded)

• Input fields can have hardcoded values for quick demo but can be edited except SessionID field.

USSD SIMULATOR Repository

USSD Simulator demo can be found at: https://github.com/fernandogmz/USSD_Simulator

1. Clone repository

2. Install dependencies

3. Run project with “npm start”