CODE YOUR APPS

USSD – API

Overview

The USSD Interface allows applications to initiate USSD sessions using a HTTP-based API. Supported services are as follows:

  • Send Service – An application wishing to send response to MO USSD session should call this method.
  • Deliver Service – Deliver Service can be either a user initiated session or a response to an existing USSD session.

HTTP Rest

In this context, both requests/responses used to exchange information are with content type “application/json”.

JSON Objects

JSON objects are used as content type to communicate between application and TAP. JSON is an open, text-based data exchange format; it is human-readable, platform independent, and supports a wide availability of implementations.

USSD

USSD (Unstructured Supplementary Service Data) is a capability built into SMS-based mobile devices. USSD information is directly sent from the sender’s device to an application which is with USSD platform. A USSD service can be invoked either by the mobile user or by a USSD platform.

Send Service

This service lets the user send USSD to one or more terminals from the application.

Send service supports only POST HTTP requests. This is used when sending USSD messages to a mobile phone from an application.

Request

Following is a sample request for send service.

Following are the Request parameters of send service.

Parameter Name Description Type Mandatory / Optional
applicationId Application ID as given when provisioned String Mandatory
password Password given when provisioned String Mandatory
version API version (shall be numbered as 1.0 etc)
If not specified shall be validated against the latest version
String Optional
sessionId Unique number that USSD Gateway assigns to the application for the duration of the session. This number will be maintained in all messages throughout a single session. String Mandatory
ussdOperation USSD operation

mo-init: TAP to assign when a USSD session is initiated by subscriber

mo-cont: TAP to assign for any USSD message originated from subscriber, that comes after a init

mt-init: App to assign when a USSD session is initiated by an application

mt-cont: App to assign for any USSD message originated from application, that comes after a init

mt-fin: App to assign when session ends in final message

Enumerator

Data type will be string where the operation name itself will be used in the parameter value.

Mandatory
destinationAddress Destination address

should be a telephone number

tel – for MSISDN

tel: 94232323232

Note : tel might be a masked number depending on the type of application

String Mandatory
encoding Encoding scheme used in the message

440 – Plain ASCII characters

Enumerated Optional
chargingAmount Charging amount specified for variable charging applications only

Shall be considered only in system currency

number to 2 decimal places

E.g., 78.05

Optional

Comprehensive sample request:

Response

USSD-Send-Response is a response from the TAP to the application, which will be sent as a response to the USSD-Send-Request message.

Following are the Response parameters of Send service.

Parameter Name Description Type Mandatory / Optional
requestId MessageID to uniquely Identify the request within the TAP String Mandatory
timeStamp Processed timestamp String Mandatory
version API version (shall be numbered as 1.0 etc) String Mandatory
statusCode The status code for the entire request String Mandatory
statusDetail The status detail for the entire request String Mandatory

Comprehensive sample response:

Receive Service

The ReceiveUssd service allows TAP to deliver MO messages to the application using HTTP – based API. The flow of messages is initiated by a MO request sent to an application, the TAP will deliver the message to the application as an acknowledgement. Hence it could be either request-response exchange or a request-exception exchange.

Receive USSD request is a MO message which will be sent to the application through the TAP as a delivery request.

Request

Following is a sample request for receive service.

Following are the request parameters of deliver service.

Parameter Name Description Type Mandatory / Optional
version API version (shall be numbered as 1.0 etc) String Mandatory
applicationId Application ID as given when provisioned String Mandatory
sessionId Unique number that USSD GW assigns to the application for the duration of the session String at least one will be specified
ussdOperation USSD operation

mo-init: TAP to assign when a USSD session is initiated by subscriber

mo-cont: TAP to assign for any USSD message originated from subscriber, that comes after a init

mt-init: App to assign when a USSD session is initiated by an application

mt-cont: App to assign for any USSD message originated from application, that comes after a init

mt-fin: App to assign when session ends in final message

Integer Mandatory
sourceAddress sender address

sourceAddress: tel:94232323232

String Mandatory
VLR address of the sender VLR address of the sender String Optional
message Message as sent from the user String Mandatory
encoding Encoding scheme used in the message 440 – Plain ASCII characters Enumerated Mandatory
requestId Request ID to uniquely Identify the request within the TAP String Mandatory

Comprehensive sample request:

Response

Deliver-USSD-Response should be the response given by the Application to the TAP as an acknowledgement on the receipt of a MO message submitted by TAP.

Following are the response parameters of deliver service.

Parameter Name Description Type Mandatory / Optional
statusCode The status code for the entire request String Mandatory
statusDetail The status detail for the entire request String Mandatory

Comprehensive sample response:

Status Codes and Error Codes

Status Codes (Non Retry able)

Code Description
S1000 Process completed successfully for all the available destination numbers

Error Codes (Non Retry able)

Code Description
E1313 Authentication failed. No such active application with applicationId application-id, or no active service provider or the given password in the request is invalid.
E1303 IP address from which this request originated is not provisioned to send request to application application-id. Please use a provisioned system to send request or contact system admin to provision the new IP.
E1312 Request is Invalid. specify_the_reason Refer the TAP NBL API Developer Guide for the mandatory fields and correct format of the request.
E1309 Requested USSD service is not allowed for this Application. Please check the issue with TAP system administrator.
E1315 Cannot find the requested service USSD or it is not active.
E1317 MSISDN in request is invalid or not allowed.
E1341 Request failed. Errors occurred while sending the request for all the destinations.
E1334 SMS sent to application name application could not be processed as the message length is too long. Maximum message length allowed is specify_max_limit
E1335 SMS sent to application name application could not be processed as the advertisement message length is too long. Maximum message length allowed for advertisements is specify_max_adv_limit
E1601 System experienced an unexpected error.
E1342 MSISDN is black listed. Not authorized to use the application application_name
E1343 MSISDN is not white listed. Only white list numbers are allowed to send messages at this state.
E1325 Format of the address is invalid. Expected format is “tel:94232323232”
E1308 Permanent charging error due specify_reason E.g., Insufficient Balance>.
E1318 Transaction limit per second has exceeded. Please throttle requests not to exceed the transaction limit. Contact TAP admin to increase the traffic limit.
E1319 Transaction limit for today is exceeded. Please try again tomorrow or contact TAP admin to increase the transaction per day limit
E1603 Temporary System Error occurred while delivering your request.

What follows is a list of definitions of all terms, acronyms and abbreviations required to properly interpret this document.

  • NCS – Network Capability Service
  • SMS – Simple Message Service
  • HTTP – Hyper Text Transfer Protocol
  • MO – Mobile Originated
  • MT – Mobile Terminated
  • MSISDN – Mobile Station Integrated Services Digital Network
  • SLA – Service Level Agreement