REST API for USSD GW

From YateBTS
Jump to: navigation, search

Common information

Request

These are HTTP requests made from the USSD application to the USSD Gateway.

These requests are used to start a network initiated USSD or to continue or finalize an interactive session.

URL to use: http://ip_or_hostname/usgw/ussd.php
HTTP Method: GET or POST

Callback

These are HTTP requests made from the USSD Gateway to the USSD application.

These requests indicate the start of a mobile initiated USSD or to notify continuation or termination of an interactive session.

URL used: Generated by replacing parameters in the configured URL template.
HTTP Method: GET

In asynchronous mode (default) the callback expects no response.
In synchronous mode (see below) the callback expects a text response.

Synchronous

This is a simplified operation mode in which the USSD application only responds to callbacks.
Synchronous mode is activated from configuration.

The USSD application server must respond with a text/plain content using UTF-8 encoding.
The gateway will decide on the proper operation (ussr or pssd) to use depending on session type
Returning an empty text causes the USSD session to end.

Requests

ussn

The ussn operation triggers a network initiated notification without establishing a session.
The message is displayed once on the device screen and it can only be dismissed.

pssr

This operation finalizes a mobile initiated session started by a pssr
The text parameter message is displayed once on the device screen and it can only be dismissed.

ussr

This operation can be used in two ways:

  • Continue an USSD session in response to a pssr or ussr
  • Create a network initiated session

The text parameter message is displayed on the device screen and it's possible to answer to it.

stop

This operation terminates an existing session.
It may contain a text to display on the device screen and it can only be dismissed.

pssd

This is an USSD v1 operation and it can only be used in response to a pssd callback.
The message is displayed once on the device screen and it can only be dismissed.

Callbacks

pssr

This operation indicates a mobile originated USSD v2 session.
Both text and code parameters contain the dialed USSD string, starting with * and ending with #
The code parameter is preseved and provided in further callbacks.

Possible further requests: pssr, ussr or stop

ussr

This operation indicates an user response to a previous ussr request.
The text parameter contains the user entered text.

Possible further requests: ussr or stop

stop

This request indicates the USSD session has been terminated. The text parameter, if not empty, provides a hint about the reason or error.

Possible further requests: none

pssd

This operation indicates a mobile originated USSD v1 request.
Both text and code parameters contain the dialed USSD string, starting with * and ending with #

Possible further requests: pssd or stop

Call flows

MO USSD

Device       USSD App
   |  ==pssr==> |     Dialed *100#
   | <==ussr==  |     Press 1 for details, 2 to pay, ...
   |  ==ussr==> |     1
   |     ..     |
   | <==pssr==  |     Thank you, Goodbye!
         or
   | <==ussr==  |     Some menu text
   |  ==stop==> |     Pressed CANCEL or network error

The session can contain any number of ussr exchanges, even zero.
Normal session termination by network should use pssr or to abort send stop

MT USSD

Device       USSD App
   | <==ussr==  |     You are out of credit. Press 1 for details, 2 to pay, ...
   |  ==ussr==> |     1
   |     ..     |
   | <==ussn==  |     Thank you, Goodbye!
         or
   | <==ussr==  |     Some menu text
   |  ==stop==> |     Pressed CANCEL or network error

Similar to the MO USSD but the interactive session is initiated by network.
Network must terminate the session by ussn or stop.

Notification

Device       USSD App
   | <==ussn==  |     Your call was charged $0.05


USSD v1

   |  ==pssd==> |     Dialed *100#
   | <==pssd==  |     Your credit is $42.75

This scenario is exceedingly rare since all devices and networks are expected to support USSD v2 since long ago.