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.