USSD Integration Guide

EMnify supports communication between endpoints and applications over USSD.

USSD stands for “Unstructured Supplementary Service Data” and allows the transport of small data volumes over the signaling channel. It does not need an active data connection nor does it incur SMS costs.

EMnify's USSD Gateway serves subscriber originated and network initiated USSD requests. It supports:

• Mobile originated single USSD requests
• Mobile originated multiple USSD requests, including USSD menus
• Network initiated single USSD requests
• Network initiated multiple USSD requests, including USSD menus
• Network initiated single notification USSD notifications
• Network initiated multiple notification USSD notifications

An USSD dialog between the endpoint and your application may continue over multiple messages. It can be initiated and ended by both parties at any time.

An endpoint device originates an USSD dialog by dialing an USSD code in the form of *XXX#. For all existing EMnify customers the USSD codes 100-109 are already pre-configured and they are ready to be used.

A Business Application initiates an USSD dialog by using EMnify's RESTful API, please have a look at our API Specification.

USSD RESTful API

To integrate USSD with your Business Application an API Callback URL needs to be configured in the corresponding service profile, USSD requests will be delivered as RESTful API Calls towards this URL.

You can find the details in our RESTful API Specification.

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.

MO USSD Flow

The format of the JSON body for initial MO message is:

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

The USSD string from/to core network and subscriber’s MS is embedded in the body of the message element. The body may contain multi-line text. In this case the new line symbol is escaped by \n, e.g. Line1\nLine2\nLine3.

The format of the response from the application server (and subsequent requests from USSD Gateway if any) in case the dialog continues is:

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

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

When the dialog is continued we forward the responses from the MS as ussd-continue towards the application server as:

{
	"ussd-continue": {
		"endpoint": {
			"id": 1,
			"name": "Your Endpoint"
		},
		"message": {
			"encoding": "default",
			"body": "Dialogue continued"
		},
		"session-id": "b5136456-d18d-4605-a79d-8464cc9fabc1"
	}
}

It is possible the USSD response from the MS to be absent. In that case the message element is not provided:

{
	"ussd-continue": {
		"endpoint": {
			"id": 1,
			"name": "Your Endpoint"
		},
		"session-id": "b5136456-d18d-4605-a79d-8464cc9fabc1"
	}
}

When the dialog is terminated abnormally from the MS side the USSD Gateway sends an ussd-endmessage to the application server:

{
	"ussd-end": {
		"endpoint": {
			"id": 1,
			"name": "Your Endpoint"
		},
		"session-id": "b5136456-d18d-4605-a79d-8464cc9fabc1"
	}
}

NI USSD Flow

To initiate NI USSD dialog your Business Application sends a HTTP message containing the endpoint-id, the ussd-string and the type of the dialog (request or notification) to the EMnify platform using the RESTful API. The platform chooses an appropriate USSD Gateway and forwards the request to it. The chosen USSD Gateway generates a session-id and forwards it to the EMnify platform which in turn sends a HTTP successful response containing the session-id to the Business Application. Simultaneously, the USSD Gateway initiates an USSD outgoing dialog with the core network. After that the dialog continues without EMnify's Platform involvement as in the MO case but with the difference of the ussd-end messages from the Business Application which in this case are empty. In fact, in order to close the dialog the Business Application needs to send only 200 OK without any message body.

###Request type messages The format of the JSON body for initial NI USSD dialog is:

{ 
  "ussd-begin" = {
    "endpoint" = {
      "id" = 1
    },
    "type" = "request",
    "message" = {
      "encoding" = "default",
      "body" = "Initial message"
    }
  }
}

The format of the HTTP response from EMnify platform to this initial request is:

{ 
    "session-id" = "b5136456-d18d-4605-a79d-8464cc9fabc1"
}

Then the subsequent request toward the application are as:

{ 
  "ussd-continue" = {
    "endpoint" = {
      "id" = 1,
      "name" = "Your endpoint"
    },
    "message" = {
      "encoding" = "default",
      "body" = "mo response"
    },
    "session-id" = "b5136456-d18d-4605-a79d-8464cc9fabc1"
  }
}

When there is an empty USSD response we will have:

{ 
  "ussd-continue" = {
    "endpoint" = {
      "id" = 1,
      "name" = "Your endpoint"
    },
    "session-id" = "b5136456-d18d-4605-a79d-8464cc9fabc1"
  }
}

If the Business Application wants to continue the dialog it sends an ussd-continue message:

{ 
  "ussd-continue" = {
    "message" = {
      "encoding" = "default",
      "body" = "sub menu"
    }
  }
}

In case the dialog ends, the Business Application sends:

{ 
  "ussd-end" = {}
}

or just a 200 OK without a body.

When the dialog is terminated abnormally from the MS side the USSD Gateway sends an ussd-endmessage to the Business Application:

{ 
  "ussd-end" = {
    "endpoint" = {
      "id" = 1,
      "name" = "Your Endpoint"
    },
    "session-id" = "b5136456-d18d-4605-a79d-8464cc9fabc1"
  }
}

###Notification type messages The format of the JSON body for initial NI USSD notification dialog is:

{ 
  "ussd-begin" = {
    "endpoint" = {
      "id" = 1
    },
    "type" = "notification",
    "message" = {
      "encoding" = "default",
      "body" = "Notification message"
    }
  }
}

The format of the HTTP response from EMnify platform to this initial request is:

{ 
    "session-id" = "b5136456-d18d-4605-a79d-8464cc9fabc1"
}

Then the subsequent responses from the endpoint are forwarded to the Business Application as HTTP requests with no message inside:

{ 
  "ussd-continue" = {
    "endpoint" = {
      "id" = 1,
      "name" = "Your endpoint"
    },
    "session-id" = "b5136456-d18d-4605-a79d-8464cc9fabc1"
  }
}

If the Business Application wants to continue the dialog it sends an ussd-continue message:

{ 
  "ussd-continue" = {
    "message" = {
      "encoding" = "default",
      "body" = "notification message 2"
    }
  }
}

In case the dialog ends, the Business Application sends:

{ 
  "ussd-end" = {}
}

or just a 200 OK without a body.

When the dialog is terminated abnormally from the endpoint side the USSD Gateway sends an ussd-end message to the Business Application:

{ 
  "ussd-end" = {
    "endpoint" = {
      "id" = 1,
      "name" = "Your Endpoint"
    },
    "session-id" = "b5136456-d18d-4605-a79d-8464cc9fabc1"
  }
}

AT Command

On your endpoint device the USSD request is initiated by sending an AT command to your GSM module, the general format is

AT+CUSD=[<n>[,<str>[,<dcs>]]]

Parameter n is used to disable/enable the presentation of an unsolicited result code and the second parameter str is the USSD string to be send, that should be enclosed in double quotes. dcs is optional and indicates the data coding scheme to be used.

AT+CUSD=1,"*100*123*567#"

This request would be send to USSD code 100 and carry the custom payload 123 and 567.

Please see 3GPP TS 27.007 for a complete documentation of this command, you can find it here.

Source at GitHub