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


Last updated on 15th Oct 2019