USSD API Interfaces

Defining the API

Here you define the Inbound Connector that will receive the Request from the USSD Gateway. This Connector must be pre-configured in the Connectors Tool and once configured there 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’ 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’: that the USSD Gateway supports should be set (some may support up to 160 chars, others as few as 120 chars). Note – the ‘Maximum Character Length’ can be set per Language. Should your USSD menu support multi languages, it is important to ensure that you have your max characters set for each language. A warning will display should you not set it for the alternate language/s.
  • ‘Format Line Break’:

Transaction Sets

One 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 shortcode.
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.
Customized 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

In order to add a handler to the transaction – the following syntax must be used:

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

Shortcode sets

This is where you define the USSD Shortcode 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

Leave a Reply

Your email address will not be published. Required fields are marked *

Fill the form and we’ll contact you shortly

    I agree with

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