USSD Support

Unstructured Supplementary Service Data (USSD) is a communication technology used by GSM cellular telephones to send text messages between a mobile phone and an application program in the network.

USSD establishes a real-time session between the mobile phone and the application that handles the service.

MPF uses the HTTP/HTTPS protocol to communicate with the USSD gateway, which is a third-party entity. The USSD gateway routes USSD messages to the MobileFirst Server. Adapter procedures need to be defined to process these requests and send back a response. You need to define USSD event handler to route the requests to the adapter procedure that handles those requests.

See WL.Server.createUSSDEventHandler and WL.Server.createUSSDResponse APIs in WL.Server.

Here is a sample flow for USSD:

1. A mobile user enters a USSD short code, such as *123#.

2. The request is forwarded to a USSD gateway.

3. The gateway maps the short code to a known URL provided by MPF, creates the USSD session, and forwards the request to the URL.

4. A MobileFirst adapter with the matching filter receives the request and responds to the gateway request with the configurable USSD menu/simple text.

Configuration required at USSD Gateway

http://host:<port>/<contextroot>/ussd

This URL can be followed by parameters specific to the gateway. Refer to your USSD Gateway documentation for more details.

Server-side APIs required at MobileFirst adapter side

To create a filter to process the USSD request:

WL.Server.setEventHandlers([ WL.Server.createUSSDEventHandler({
 'shortcode' : '*123#'
}, handleUSSDRequest) ]);

To send back a response:

WL.Server.createUSSDResponse("This is my response", "text/plain", true))

Security

To prevent entities with malicious intent from sending requests to the MobileFirst Server via a USSD URL, the USSD feature is protected by default. TauthenticationConfig.xml.is configured to reject all requests to the USSD servlet with a rejecting login module. To allow restricted access to USSD, MobileFirst administrators must modify authenticationConfig.xml.with appropriate authenticator and login modules, or comment the URL pattern /ussd* to allow unrestricted access. For example, the following configuration in authenticationConfig.xml.ensures that only requests with a specific user name in the header of the HTTP request are allowed:

<staticResources>
    <resource id="subscribeServlet" securityTest="SubscribeServlet">
        <urlPatterns>/subscribeSMS*;/ussd*</urlPatterns>
    </resource>
    ...  
  </staticResources> 
  <securityTests>
    <customSecurityTest name="SubscribeServlet">
      <test realm="SubscribeServlet" isInternalUserID="true"/>
    </customSecurityTest>       
    ...
  </securityTests> 
  <realms>
    <realm name="SubscribeServlet" loginModule="headerLogin">
      <className>com.worklight.core.auth.ext.HeaderAuthenticator</className> 
    </realm>
    ...  
  </realms>
  <loginModules>
    <loginModule name="headerLogin">
      <className>com.worklight.core.auth.ext.HeaderLoginModule</className>
      <parameter name="user-name-header" value="username"/> 
    </loginModule>
    ...  
  </loginModules>

Parent topic: Develop the server side of a MobileFirst application