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. You can also set some parameters to be remembered in session by using various HTTP Headers.
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.
This mode allows saving some header values from session and adding them to when callback is made.
To close a sync MO/MT USSD session from network side you need to send HTTP header “operation” in response with value “pssr”/”ussn”. Use pssr for MO USSD sessions and ussn for MT (Network initiated).
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:
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.
Below is a more complex flow that includes various types of errors / positive callback / callback when user pressed Cancel instead of engaging the sent menu.
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.