Skip to content

ussd-v1/v3

Content

Method

The following REST methods are available
* Intiate mobile terminated USSD. * Receive mobile originated USSD. * Stop subscription to notifications of MO USSD.

Authorization API calls

All API call request to ideabiz.lk required Authorization headers. Please refer (http://docs.ideabiz.lk/Getting_Started/Token_Manegment) for Authorization

Request Header
Content-Type: application/json
Authorization: Bearer [access token]
Accept: application/json

Initiating Mobile Terminated USSD (NI USSD/MT)

Initiates a USSD session with the intended end user. This request would pop up a USSD menu on the end user's device.

Request

Following is a sample request of initiating mobile terminated USSD.

URL
https://ideabiz.lk/apicall/ussd/{version}/outbound/{Subscriber Number}
Method
POST
Body

{
    "outboundUSSDMessageRequest": {
    "address": "tel:+94777123456",
    "shortCode": "tel:1234",
    "keyword": "123",
    "outboundUSSDMessage": "Login to service?\n1. Ok\n2. Cancel",
    "clientCorrelator": "123456",
    "responseRequest": {
      "notifyURL": "http://ussd.response.receive.url ",
      "callbackData": "some-data-useful-to-the-requester"
    },
    "ussdAction": "mtinit"
  }
}
Following are the request parameters of initiating mobile terminated USSD.

Parameter name Description Usage
address The recipients MSISDN including the ‘tel:’ protocol identifier and the country code preceded by ‘+’. i.e., tel:+94770000000. Mandatory
shortCode The short 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 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 Optional
outboundUSSDMessage (string) The message to be displayed on the end user device. Mandatory
clientCorrelator (string) uniquely identifies this request. If there is a communication failure during the request, using the same clientCorrelator when retrying the request allows the operator to avoid sending duplicate messages to the end user. Mandatory
ussdAction The desired USSD action, valid actions are; mtinit: Initiate MT USSD session mtcont: Continue a MT USSD session moinit: An USSD session initiated by an end user. mocont: Continue a MO USSD session mtfin: End a USSD Session Mandatory
notifyURL (string) If the user responds to the USSD menu, the response should be forwarded to this URL. NOTE: If this parameter is not set, a subscription to receive MO USSD should be created. If either notifyURL or subscription to receive MO is created, the application has no way of receiving end user input. Optional
callbackData (string) will be passed back in this notification. It’s used to identify the message the receipt relates to (or any other useful data, such as a function name). This is only valid if notifications are required – sent with the notifyURL parameter within the responseRequest element. Optional


Response

Following is a sample response of initiating mobile terminated USSD. 

{
    "outboundUSSDMessageRequest": {
    "address": " tel:+94777123456",
    "keyword": "123",
    "shortCode": "tel:1721",
    "outboundUSSDMessage": " Login to service?\n1. Ok\n2. Cancel ",
    "clientCorrelator": "123456",
    "responseRequest": {
      "notifyURL": "http://ussd.response.receive.url ",
      "callbackData": "some-data-useful-to-the-requester"
    },
    "ussdAction": "mtinit",
    "deliveryStatus": "SENT"
  }
}

Response Parameters

All the parameters of the original request should be relayed back with the addition of the deliveryStatus parameter.

Parameter Name Description Usage
deliveryStatus The status of the NI USSD command should be sent back in this field. If the request was accepted by the underlying USSD platform, then the value of the parameter will be set to “SENT”. Mandatory


Receive Response

If the notification URL was set in the responseRequest object in outboundUSSDMessageRequest (Refer Initiating Mobile Terminated USSD (NI USSD/MT)) or a subscription to receive MO USSD was created, then the end users response should be posted to the notification URL. 

 {

    "inboundUSSDMessageRequest": {
    "address": " tel:+94777123456",
    "shortCode": "tel:1721",
    "keyword": "123",
    "inboundUSSDMessage": "2",
    "clientCorrelator": "123456",
    "sessionID": "XXXXXX",
    "responseRequest": {
      "notifyURL": "http://ussd.response.receive.url ",
      "callbackData": "some-data-useful-to-the-requester"
    },
    "ussdAction": "mtcont"
  }
}

Receive Response Parameters

Parameter name ** Description ** ** Usage **
address The recipients MSISDN including the ‘tel:’ protocol identifier and the country code preceded by ‘+’. i.e., tel:+94770000000. Mandatory
sessionID A unique identifier for the session should be returned. Any subsequent communication between MIFE and the application, should contain this session ID. Mandatory
shortCode The short 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 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 Optional
inboundUSSDMessage (string) The response message provided by the end user. Mandatory
clientCorrelator (string) The clientCorrelator of the original request should be set here. Mandatory
ussdAction The desired USSD action, valid actions are; mtinit: Initiate MT USSD session mtcont: Continue a MT USSD session moinit: An USSD session initiated by an end user mocont: Continue a MO USSD session mtfin: End a USSD Session Mandatory
responseRequest
notifyURL (string) If the user responds to the USSD menu, the response should be forwarded to this URL. Optional
callbackData (string) Will be passed back in this notification. It’s used to identify the message the receipt relates to (or any other useful data, such as a function name). This is only valid if notifications are required – sent with the notifyURL parameter within the responseRequest element. Optional

 


Continue USSD Session

Continue an USSD session with the intended end user.

Method
POST
Request
{
    "outboundUSSDMessageRequest": {
    "address": "tel:+123456789",
    "shortCode": "tel:1234",
    "keyword": "123",
    "outboundUSSDMessage": "Login to service?\n1. Ok\n2. Cancel",
    "clientCorrelator": "123456",
    "responseRequest": {
      "notifyURL": "http://ussd.response.receive.url ",
      "callbackData": "some-data-useful-to-the-requester"
    },
    "ussdAction": "mtcont"
  }
}
Parameter name ** Description ** ** Usage **
address The recipients MSISDN including the ‘tel:’ protocol identifier and the country code preceded by ‘+’. i.e., tel:+94770000000. Mandatory
shortCode The short 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 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 Optional
outboundUSSDMessage (string) The message to be displayed on the end user device. Mandatory
clientCorrelator (string) uniquely identifies this request. If there is a communication failure during the request, using the same clientCorrelator when retrying the request allows the operator to avoid sending duplicate messages to the end user. Mandatory
ussdAction The desired USSD action, valid actions are; mtinit: Initiate MT USSD session mtcont: Continue a MT USSD session moinit: An USSD session initiated by an end user mocont: Continue a MO USSD session mtfin: End a USSD Session Mandatory
responseRequest
notifyURL (string) If the user responds to the USSD menu, the response should be forwarded to this URL. NOTE: If this parameter is not set, a subscription to receive MO USSD should be created. If either notifyURL or subscription to receive MO is created, the application has no way of receiving end user input. Optional
callbackData (string) will be passed back in this notification. It’s used to identify the message the receipt relates to (or any other useful data, such as a function name). This is only valid if notifications are required – sent with the notifyURL parameter within the responseRequest element. Optional

 

Response

Refer the Receive Response Message for the response body and description.

Receive Mobile Originated USSD

When an end user dials USSD code, if a subscription to receive MO USSD was created for that code, then the request will be posted to the notification URL.

{
    "inboundUSSDMessageRequest": {
    "address": " tel:+94777123456",
    "shortCode": "tel:1721",
    "keyword": "123",
    "inboundUSSDMessage": "2",
    "clientCorrelator": "123456",
    "responseRequest": {
      "notifyURL": "http://ussd.response.receive.url ",
      "callbackData": "some-data-useful-to-the-requester"
    },
    "ussdAction": "mtcont"
  }
}
#### Receive Response Parameters

Parameter name ** Description ** ** Usage **
address The recipients MSISDN including the ‘tel:’ protocol identifier and the country code preceded by ‘+’. i.e., tel:+94770000000. Mandatory
sessionID A unique identifier for the session should be returned. Any subsequent communication between MIFE and the application, should contain this session ID. Mandatory
shortCode The short 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 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 Optional
inboundUSSDMessage (string) The response message provided by the end user. Mandatory
clientCorrelator (string) The clientCorrelator of the original request should be set here. Mandatory
ussdAction The desired USSD action, valid actions are; mtinit: Initiate MT USSD session mtcont: Continue a MT USSD session moinit: An USSD session initiated by an end user mocont: Continue a MO USSD session mtfin: End a USSD Session Mandatory
responseRequest
notifyURL (string) If the user responds to the USSD menu, the response should be forwarded to this URL. Optional
callbackData (string) Will be passed back in this notification. It’s used to identify the message the receipt relates to (or any other useful data, such as a function name). This is only valid if notifications are required – sent with the notifyURL parameter within the responseRequest element. Optional

 

Response Codes & Exceptions

Response Codes

HTTP response codes should be used to indicate:

200 – Success!
400 – Bad request; check the error message for details
401 – Authentication failure, check your authentication details
403 – Forbidden; please provide authentication credentials
404 – Not found: mistake in the host or path of the service URI
405 – Method not supported: for example you mistakenly used a HTTP GET instead of a POST
500 – The server encountered an unexpected condition. This could be wrong authentication details or limited user permission
503 – Server busy and service unavailable. Please retry the request. Exceptions

If the transaction is immediately confirmed, the response is displayed as follows:

This section lists the available error codes, the possible reasons why the exception may have occured, and possible solutions.

Service Exceptions

If the transaction is immediately confirmed, the response is displayed as follows, 

HTTP/1.1404BadRequestAccept: application/json{
  "requestError": {
    "serviceException": {
      "messageId": "SVC0002",
      "text": " Invalid input value for message part %1",
      "variables": " clientCorrelator Value 12345"
    }
  }
}

Common Service Exceptions
Exception Variables
SVC0001: A service error occurred. Error code is %1 %1 – explanation of the error
SVC0002: Invalid input value for message part %1 %1 – the part of the request that is invalid
SVC0003: Invalid input value for message part %1, valid values are %2 %1 – message part %2 – list of valid values
SVC0004: No valid addresses provided in message part %1 %1 – message part
SVC0005: Correlator %1 specified in message part %2 is a duplicate %1 – Correlator %2 – message part
SVC0006: Group %1 in message part %2 is not a valid group %1 – identifier for the invalid group %2 – message part
SVC0007: Invalid charging information none
SVC0008: Overlapped criteria %1 %1 Message Part with the overlapped criteria
SVC1000: No resources none

Following service exceptions may be thrown for SMS specifically:

Exception Variables
SVC0280: Message too long. Maximum length is %1 characters %1 – number of characters allowed in a message
SCV0283: Delivery receipt notification not supported none
SVC0284: Address format is invalid. Expected format is %1 %1 - "tel:+94771211212"
SVC0285: Message Not Delivered %1 %1 – Errors occurred while sending the request for all the destinations.

 

Following service exceptions may be thrown for Payment specifically:

Exception Variables
SVC0270: Charging operation failed, the charge was not applied none
SVC0271: endUserId format invalid. Expected format is %1 %1 - "tel:+94771211212"

 

 

 

 

Policy Exceptions

If a request is invalid, a policy exception is thrown.

POL0001 - Policy error occured.

The above exception may be thrown to indicate a fault relating to a policy associated with the service.

HTTP 403Forbidden{
  "requestError": {
    "policyException": {
      "messageId": "POL0001",
      "text": "A policy error occurred. Error code is maxBatchSize exceeded. The maximum allowed maxBatchSize is %1.",
      "variables": "20"
    }
  }
}
Following exceptions may be thrown:

Exception Variables
POL0001: A policy error occurred. Error code is %1 %1 – explanation of the error
POL0002: Privacy verification failed for address %1, request is refused %1 – address privacy verification failed for
POL0003: Too many addresses specified in message part %1 %1 – message part
POL0004: Unlimited notification request not supported none
POL0005: Too many notifications requested none
POL0006: Group specified in message part %1 not allowed %1 – message part. Note: group means an address which refers to more than one end user
POL0007: Nested groups specified in message part %1 not allowed %1 – message part. Note: group means an address which refers to more than one end user. Groups cannot contain addresses which are themselves groups.
POL0008: Charging is not supported none
POL0009: Invalid frequency requested none
POL0010: Requested information unavailable as the retention time interval has expired none
POL0011: Media type not supported none
POL0012: Too many description entries specified in message part %1 %1 – message part
POL0013: Duplicated addresses %1 %1 – duplicated addresses
POL0253: Payment operation refused by user none
POL0254: The amount exceeds the operator limit for a single charge none
POL0255: Address format invalid. Expected format is %1 %1 - "tel:+94771211212"
POL0256: Invalid currency specified. %1 %1-Check your SLA for valid currency types
POL0257: Message not delivered %1 %1- Request failed. Errors occurred while sending the request for all the destinations
POL0299: Unexpected Errors none
POL1000: User has insufficient credit for transaction none
POL1001: The %1 operator charging limit for this user has been exceeded %1 – the time period for which the charging limit has been reached
POL1007: Refunds not supported none
POL1009: User has not been provisioned for %1 %1 – name of the service
POL1010: User has been suspended from %1 %1 – the name of the service