USSD API Interfaces

Using Redis for session management

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.

Was this article helpful?

Related Articles

Fill the form and we’ll contact you shortly

    I agree with

    We uses cookies to make your experience on this website better. Learn more
    Accept cookies