1. Check Connectivity

Your application needs to be running in order to use the simulator. Complete the host and port to point to where the application is currently running. The endpoint where your application will be running needs to be accessible to the GLU console to ensure the simulator will work. Test the connectivity to ensure that the simulator has access to the running application.

It may be necessary to open the correct port in your firewall or use some other network mechanism to ensure the GLU Console has access.

2. Select Configuration of Simulator

In the configuration of the simulator, the user must select the API and transaction which will be simulated. This will auto-populate values from the menu builder setup during configuration. In the payload, it is important to ensure that the ${input} parameter (whatever parameter is set as the input parameter) is set as such.

Step 1: The input parameter selected on the configuration. Parameter name = input

Step 2: The payload used for the simulator is setup here. For ease of use GLU suggest defining the input parameter with the device input set – ${input}.

Step 3: The request payload for the simulator will be pulled in when launching the simulator. If step 1 and 2 are completed above, there is no need to edit the payload in the simulator.

3. Simulating the user input and showing a result

The user can enter the shortcode into the device. The request payload represents what the gateway will send to the GLU.Engine. The appropriate menu will be displayed on the device. The user can submit the relevant values and commit the submit by using the Enter key and then can test by viewing the USSD string to confirm success.

The response payload represents the payload that will be returned to the USSD gateway.

Type 1: Acknowledge is ON, and respond back to separate URL

This design is used when the USSD gateway requires an ACK message to be returned when the request is received. The ACK is returned in response to the incoming request, and the final USSD response is sent back to a different endpoint.

Type 2: Acknowledge OFF and respond back to different endpoint

It is possible to specify the response endpoint as a different endpoint to the incoming request. This different endpoint can be defined by selecting the correct connector and defining the relevant path or context name (response back url).

Type 3: Acknowledge OFF and respond back to the same endpoint as incoming request

This is a straight request and response model. The response generated in the menu builder will be sent back to the same endpoint as the incoming request.

If a Redis connector is configured and assigned to this GLU.Engine, you will have the choice between using the GLU.Engine memory cache or Redis. Redis can effectively manage USSD sessions in a load-balanced environment, where each service can access the same Redis database to handle USSD menu sessions. Once this connector is selected, the GLU.Engine will automatically push session details to the database, eliminating the need for further configuration.

Defining the API

Here, you define the Inbound Connector responsible for receiving requests from the USSD Gateway. This connector must be pre-configured in the Connectors Tool, and once configured, it should be selected from the drop-down list.

Additionally, the following settings can be made (these would be provided to you by the USSD Gateway operator):

• ‘Timeout’: Set in seconds for the USSD Gateway can be set. (We have found this setting to be critical to the interaction and control of the session.)
• ‘Maximum Character Length’: This parameter determines the maximum number of characters supported by the USSD Gateway. Different gateways may support varying character lengths (e.g., some support up to 160 chars, while others may only support 120 chars). Note: ‘Maximum Character Length‘ can be configured per language. If your USSD menu supports multiple languages, ensure that you set the maximum characters for each language. A warning will be displayed if you fail to set it for alternate languages.
• ‘Format Line Break’

Transaction Sets

You can configure one or more Transaction Sets. Each Transaction Set defined should be assigned a ‘Transaction Code’. Within the Configuration Panels you define the Request Payload, the Response Payload and the Handlers to direct the USSD Server on what do do with the received Request.

Request Definition

A Transaction Set is essentially defined by an inbound Request Payload, different Request Payload structures would typically require different Transaction Sets to be configured. This request payload would often be defined by the USSD Gateway Service.

Request parameters

Parameter Types:

• Input Data: The parameter marked as input data will be used as the input to receive the customers action on the USSD String. e.g. 2, for the user selecting 2 etc
• Device: The parameter marked as device is used to indicate the unique customer (the customers device).
• Other: Can be used for any other data that is required to be pulled from the incoming request payload.
• Short Code: Used to indicate which parameter on the incoming request payload is marked as the short code.
• SessionID: If no specific sessionID parameter is added, USSD session is by default created using the parameter that is set as the ‘device’ on the request parameters. Otherwise the added parameter marked as ‘Session ID’ will be used.
• Customised Session ID: This allows you to concatenate parameters to create a customised session ID.

Response Definition

The Response Template should be used to define the response message structure that the USSD Gateway expects to receive. Within that Response Template, the variable ‘${result}‘ would be used to return the result or outcome from the USSD interaction to the USSD Gateway. So the output of the menu process, will be posted back through the ‘${result}‘ field in the response payload.

Transaction Handlers

To add a handler to the transaction, you must use the following syntax:

• Condition: ${paramName}==3
• Then include the menu set that should be routed to when that condition is met.

Short Code Sets

This is where you define the USSD Short code string that will invoke the session:

Long Codes and Jump Codes

In this example, to get to “Enquire about our Credit Service” you can do any of the following:

• Dial *811# then select option 10 for Airtime
• Dial *811*10# for “Airtime”
• Dial *811*567# to jump straight to “Airtime” – This is especially useful when going several layers deep in a USSD menu.

Phase 2 USSD

Phase 2 USSD (Unstructured Supplementary Service Data) is a mobile communication technology used for two-way interaction between a mobile phone user and a service provider. It is an upgrade from phase 1 USSD, which only supports one-way communication. In phase 2 USSD, the user can initiate a session with the service provider and receive a response, making it a more interactive and dynamic system.

Additionally, Phase 2 USSD also offers enhanced security features compared to Phase 1, such as the ability to encrypt data in transit. This makes it a suitable technology for sensitive applications, such as mobile banking.

Overall, Phase 2 USSD is a powerful tool for service providers looking to offer mobile-based services to their customers in areas with limited internet connectivity. It enables efficient and secure communication and can help drive customer engagement and satisfaction.

The interactive nature of USSD Phase 2 allows an application to present options to a subscriber in the form of menus. These menus and the logic within them are not stored on the phone.

The menus are formatted text lists of options separated by line feed characters. On a handset, the text renders as a menu. The user responds by entering a character that corresponds with their chosen selection.

USSD is not a menu on the handset, it is the channel or bearer that delivers the menu text and selections. Menus are independent of the handset as well as the SIM card. The server-side application being the GLU.Ware configured USSD Menu running on the GLU USSD Sever keeps track of where in the menu structure every subscriber is at all the time.

Menus served over USSD should not be confused with menus and applications served by STK (Sim Tool Kit). STK is a technology embedded on the SIM card where special applications can be accessed by subscribers. With STK, the handset receives instructions from the SIM card to perform functions.

USSD differs from the other short message bearer, SMS, in a number of significant ways. It is not a store-and-forward bearer like SMS, but a transparent session-based bearer ideal for transacting. Information is delivered and responses obtained in real-time. Simply put, USSD is similar to speaking to someone on a phone as SMS is sending a letter.

USSD is also not a point-to-point bearer such as SMS. One subscriber cannot send another text using USSD unless there is a special network application offering such an application.

GLU.USSD and GLU.Engine’s in Context

The context diagram below describes broadly the components involved in serving a USSD Menu user using GLU.Ware. The MNO side is standard typically across all MNO’s, once a USSD Session is invoked by a User, it is passed across the network until it reaches the MNO’s USSD Gateway. From there the Gateway will associated the USSD Shortcode that invoked the session with the IP address of the USSD Server API as configured in the GLU.Engine. The GLU.Engine package combines both the USSD Server component (which runs the USSD Menu as it has been configured in the GLU.Console) and the GLU Integration Engine. The GLU USSD Server is configured to expose an API to receive the inbound USSD Request from the USSD Gateway and once received and menu interactions are completed, the USSD Server is configured to pass the request payload down to the GLU Integration Engine to process the transaction.

GLU.USSD Config Elements

The Menu Builder is accessed via the ‘GLU.USSD’ tool on the main navigation as below.
The Menu Configuration Console comprises of two elements – ‘Configuration’ and ‘Menus’.

The Configuration elements are used to configure the Menu Builder to receive the USSD Payload an API interface that is pre-defined in the ‘Connectors’ tool; it is used to configure all the messages that should be returned via the USSD Channel depending on the outcome of the USSD menu interaction and it is used to configure the the standard screen settings such as Headers and codes for Main Menu, Next Menu and Previous Menu.

The Menus elements are used to configure one or more USSD Menu’s. In a scenario where for example you have Merchants and Customers using the same Shortcode, you may want to present a different USSD Menu to a Merchant vs. a Customer. GLU.Ware supports the provisioning of multiple different menu’s which can be rendered based on the Shortcode string submitted, a user selection or ‘behind the scenes’ mapping of the originating MSISDN against the user type (from a back-end call via the Integration Engine).