USSD API


This allows applications to initiate USSD sessions using a HTTP-based API. You can build USSD menu driven applications, monetize based on menu request, maintain an active session with customers etc.

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.

Method

POST

 

Send Service

This is used when sending USSD messages to a mobile phone from an application. This service lets the user send USSD to one or more terminals from the application. Send service supports only POST HTTP requests. URL for USSD Send Service is as follows:

Simulator:
http://localhost:7000/ussd/send
Active production:
https://api.dialog.lk/ussd/send

 

Request

Following is a sample request for send service.


{
  "applicationId": "APP_000001",
  "password": "password",
  "message": "1. Press One 
              2. Press two
              3. Press three
              4. Exit",
  "sessionId": "1330929317043",
  "ussdOperation": "mt-cont",
  "destinationAddress": "tel:94771234567"
}

 

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.  Optional
 message  Message sent from the application.  String  Mandatory
 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: Ideamart to assign when a USSD session is initiated by subscriber
 mo-cont: Ideamart to assign for any USSD message originated from subscriber, that comes after a init.
 mt-init: App to assign when a USSDsession 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: 94771234567
 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

 

Comprehensive sample request:


{
  "applicationId": "APP_000001",
  "password": "password",
  "version": "1.0",
  "message": "1. Press One             
              2. Press two 	    
              3. Press three 	    
              4. Exit",

  "sessionId": "1330929317043",
  "ussdOperation": "mt-cont",
  "destinationAddress": "tel:94771234567",
  "encoding": "440"
}

 

Response

USSD-Send-Response is a response from the Ideamart 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
version API version
(shall be numbered as 1.0 etc)
String Mandatory
requestId MessageID to uniquely identify the request within the Ideamart String Mandatory
timeStamp Processed timestamp Mandatory
statusCode The status code for the entire request String Mandatory
statusDetail The status detail for the entire request String Mandatory

Comprehensive sample response:


{
  "statusCode": "S1000",
  "timeStamp": "1203051205",
  "statusDetail": "Success",
  "requestId": "1330929317059",
  "version": "1.0"
}

 

 

Receive Service

The Receive USSD service allows Ideamart 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 Ideamart 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 Ideamart as a delivery request.

 

Request

Following is a sample request for receive service.


{
  "message": "*141#",
  "ussdOperation": "mt-cont",
  "requestId": "1330933229901",
  "sessionId": "1330929317043",
  "encoding": "440",
  "sourceAddress": "tel:94771234567",
  "applicationId": "APP_000001",
  "version": "1.0"
}

 

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 Gateway assigns to the application for the duration of the session. String Mandatory
ussdOperation USSD operation
mo-init: IdeaMart to assign when a USSD session is initiated by subscriber
mo-cont: IdeaMart 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
sourceAddress sender address
sourceAddress: tel:94771234567
String Mandatory
vlrAddress 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 Ideamart String Mandatory

 

Comprehensive sample request:


{
  "message": "*141#",
  "ussdOperation": "mo-init",
  "requestId": "1330933229901",
  "vlrAddress": "some vlr address",
  "sessionId": "1330929317043",
  "encoding": "440",
  "sourceAddress": "tel:94771234567",
  "applicationId": "APP_000001",
  "version": "1.0"
}

 

Response

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

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:


{
  "statusCode": "S1000",
  "statusDetail": "Success"
}

 

 

Using the simulator

 

USSD MT

Figure 1.1

Figure 1.1

 

 

Once connected to the application, the USSD prompt will be shown with the options.

 

The “Messages sent to Customer” section shows the messages with the details (message sent time, destination phone number and message content) as shown in the figure below.

Figure 1.2

Figure 1.2

 

User can still test the MT part alone (without MO) with any application provided that it can send MT messages.

For that, send the MT message to the following URL (which accepts USSD MT) and the MT message will be displayed in the simulator.

http://localhost:7000/ussd/send

 

 

USSD MO

To send a message to the application, the CP can use the provided interface in the simulator. Refer the figure below.

Figure 1.3

Figure 1.3

 

Enter the details as follows.

 

Field name Description Sample value
URL The URL where the application is hosted. http://localhost:5555/mo-ussd
Application ID Unique ID of the Application APP_00001
Password Password of the application. The application password will be auto generated when the application is created. password
Customer Number The phone number from which the message is sent 94771234567
Service Code USSD Service Code *141#
Status/Error Code Select the response status/error code to generate, when MT (Mobile Termination) message received from application. S1000:Success

Once the values are entered correctly, click on the “Send” button.

The messages sent to the application will be displayed with its sent time, phone number, message content and status under “Message sent to Application” section.

Figure 1.4

Figure 1.4