USSD API

If you dial #345# on your mobile number pad you will be using an USSD. (Unstructured Supplementary Service Data) application. The Ideamart platform enables you 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.

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: 5C74B588F97”

}

 

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 Has Code.

tel – for MSISDN

tel: 5C74B588F97

 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: 5C74B588F97”,

“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: 5C74B588F97”,

“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: 5C74B588F97

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: 5C74B588F97”,

“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”

}