Starting a USSD Dialog

Endpoints can send and receive data to or from your application via USSD by dialing USSD codes in the format *xxx# (e.g. *101#).

The range 100-109 is preconfigured by default, so your endpoint can address different applications on your server. The system will dispatch MO-USSD requests from endpoints towards a configurable URL, in this case the EMnify System will act as an HTTP client and you will need to provide an HTTP server to accept the request.

Please see Service Profile Configuration on how to set up an API Callback. Your server needs to respond with HTTP Code 200 to accept the request.

USSD Payload

The maximum size of a USSD message is 160 bytes. For GSM 7 Bit encoded messages this gives a limit of 182 characters. If you choose UCS2 encoding you will have a maximum of 80 characters available. Regardless of the encoding used in the network, the payload will always be UTF-8 encoded when transmitted to or from your application along with an indication of the used encoding. The default encoding is GSM 7 Bit.

Continuing a USSD Dialog

After receiving the initial request from the endpoint your application may decide to continue the dialog (“ussd-continue”) by sending back some message and waiting for further input from the endpoint.

Ending a USSD Dialog

Your application may decide to close the dialog after the first request or after multiple messages (“ussd-end”), also in this case a message will be send back to the endpoint and then the dialog will be closed.

Receive USSD request example:

{
  "ussd-begin": {
    "endpoint": {
      "id": 1,
      "name": "Your Endpoint"
    },
    "message": {
      "encoding": "default",
      "body": "*101#"
    },
    "session-id": "b5136456-d18d-4605-a79d-8464cc9fabc1"
  }
}

Receive USSD response example:

{
  "ussd-continue": {
    "message": {
      "encoding": "default",
      "body": "SomeText"
    }
  }
}