Page Comparison

Introduction

Helium and the Helium DSL provides built-in functionality for USSD integration. The DSL provides an interface for these integrations through a USSD function annotation, and MezUssdMenu and  and MezUssdMenuOption built built-in objects.

Functions that are annotated with @USSD serve  serve as integration endpoints that are available to be executed for inbound requests from USSD gateways. These functions then return an instance of MezUssdMenu that  that describes the next menu structure that is to be presented to the end user during his USSD session.

Overview

The basis of integrating with a USSD gateway is through calls from the USSD gateway to Helium.

When a user initiates a USSD session on the mobile device an API call is made to Helium's API. The calls are then routed to a specific @USSD annotated  annotated DSL function within an app. The app then response responds with the menu structure that is to be presented to the end user . and Helium then translates this response as is required by the specific gateway.

@USSD

One of the following signatures is expected for USSD annotated functions:

@USSD("description")
MezUssdMenu processUssd(int menu, int selection)

The "description" values in the example above and below represents a unique string literal identifier for the specific USSD function. More than one USSD method can be included as long as the descriptions are unique. Further more the descriptions are used as path parameter values in Helium's internal API and can thus be used to route inbound calls to the correct DSL USSD functions.

@USSD("description")
MezUssdMenu processUssd(int menu, int selection, json gatewayArgs)

menu:

An integer that indicates the menu from which the USSD request originated. For an initial call a value of 0 is sent.

selection:

An integer that indicates the menu option that was selected for the current request. For an initial call a value of 0 is sent.

gatewayArgs:

A json parameter that is populated with all additional query parameters sent by the gateway to Helium. At present the only gateway that is supported is Vodacom USSD gateway. The following shows an example of values that are sent for this gateway:

{
    "msisdn":"27763303624",
    "request":"*120*247253#",
    "provider":"Vodacom",
    "ussdSessionId":"2496158596"
}

The json attributes listed in the above example represent to following :and can be used in the DSL logic for more context or can be ignored.

MezUssdMenu and MezUssdMenuOption