On Demand Api
Content
Overview
The OnDemand API acts as a middleware, handling inbound SMS and USSD requests from Dialog customers to send their location to third-party service providers.
Response
Following is a sample response from the OnDemand API once the user's location is retrieved.
{
"msisdn":"tel:+94771234567",
"port":"7752",
"keyword":"149",
"latitude":"0",
"longitude":"0",
"accessorMethod":"ussd",
"accuracy":"10"
}
Following are the Response parameters of the OnDemand service.
Parameter name |
Description |
Type |
Mandatory/Optional |
msisdn |
MSISDN of the mobile terminal to locate. in this case the recipients MSISDN including the ‘tel:’ protocol identifier and the country code preceded by ‘+’. i.e. tel:+ 94771234567. |
string |
Mandatory |
port |
The port assigned to an application. End users dialling this short code should be routed to the corresponding application. NOTE: The short code can be unique to an application or can be shared my multiple applications |
string |
Mandatory |
keyword |
When a short code is shared among multiple applications, the keyword should be used to uniquely identify the application. NOTE: This parameter can be empty if the short code is unique for an application |
string |
Mandatory |
latitude |
Decimal Degrees, ISO 6709. |
string |
Mandatory |
longitude |
Decimal Degrees, ISO 6709. |
string |
Mandatory |
accessorMethod |
The method through which the API was accessed.(Either USSD or SMS) |
string |
Mandatory |
accuracy |
Result accuracy in metres. |
string |
Mandatory |
Request (Optional)
Once the OnDemand API has notified the service provider, a notification can be sent back to the API to either send a SMS to the user or continue the USSD session(Diverting it to the service provider's end).
A sample request is given below:
{
"ussd": {
"message" :"Received the location",
"callbackURL": "https://apps.ideabiz.lk/ussd/"
},
"sms":{
"message" : "Nearby restaurants: KFC, McDonald's",
"callbackURL": "https://apps.ideabiz.lk/sms/",
"port": "87756"
}
}
If the service provider intends to send an USSD along with a SMS it is possible if the request above is sent. However if the request is not sent, a pre-defined message will be sent by the API. If the service provider decides to continue the USSD session, the response will be similar to that of the USSD API.(http://docs.ideabiz.lk/APIs/USSD)
States of Parameters
States of the Request parameters of send service.
Parameter Name |
Description |
Type |
Mandatory /Optional |
---|---|---|---|
ussd: message |
The message to be displayed on the end user's device. |
string |
Mandatory |
ussd: callbackURL |
If the user responds to the USSD menu, the response should be forwarded to this URL. |
string |
Optional.Keep empty or null if you don't want delivery notifications. |
sms: message |
Must be provided within the message element. Messages over 160 characters may end up being sent as two or more messages by the operator. |
string |
Mandatory |
sms: callbackURL |
The URL to which you would like to receive a notification of delivery of SMS.The format of this notification is shown below. |
string |
Optional.Keep empty or null if you don't want delivery notifications. |
sms: port |
This is the Port number configured for the API.If a valid port is not sent, the OnDemand API will not dispatch the message to the recipient. |
string |
Mandatory |