API reference

USSD API

Launch menu-driven USSD sessions over HTTP. Build interactive flows that work on any handset, keep session state across steps, and monetize each menu request.

Base URL: https://api.applink.com.bd
Content type: application/json;charset=utf-8
Endpoints: 2

POST

USSD Send Services

https://api.applink.com.bd/ussd/send

This service is used when sending USSD messages to a mobile phone from an application.USSD send service supports only POST HTTP requests.

Request body

application/json;charset=utf-8

version stringRequired: API version shall be numbered as 1.0, 2.0 etc. If version is specified in the request, same version must be sent in the response. If version is not specified in the request, the latest version will be specified in the response.
Example1.0
applicationId stringRequired: Used to identify the application. This is a unique identifier generated while provisioning an application. Only a single value can be sent per request.
ExampleAPP_000001
message stringRequired: Content of the message sent by the application
Example1. Press One 2. Press two 3. Press three 4. Exit
password stringRequired: This API key will be sent to your registered email address on the platform upon application approval.
Examplepassword
sessionId stringRequired: Unique number that USSD Gateway assigns to the application for the duration of the session. This number will be maintained in all the messages throughout a single session.
Example1330929317043
ussdOperation string enumRequired: USSD operation mo-cont:TAP to assign for and 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 Data type will be string where the operation name itself will be used in the parameter value.
Allowedmo-initmo-contmt-initmt-contmt-fin
Examplemt-cont
destinationAddress stringRequired: Destination address should be a telephone number (tel - for MSISDN) Note : tel might be a masked number depending on the type of application
Exampletel: +8801959979376
encoding string enumOptional: Encoding scheme used in the message 440 - Plain ASCII characters
Allowed440
Example440

curl -X POST https://api.applink.com.bd/ussd/send \
  -H "Content-Type: application/json;charset=utf-8" \
  -d '{
    "version": "1.0",
    "applicationId": "APP_000001",
    "message": "1. Press One\n 2. Press two\n 3. Press three\n 4. Exit\n",
    "password": "password",
    "sessionId": "1330929317043",
    "ussdOperation": "mt-cont",
    "destinationAddress": "tel: +8801959979376 ",
    "encoding": "440"
  }'

Response

version stringRequired: API version shall be numbered as 1.0, 2.0 etc. If version is specified in the request, same version must be sent in the response. If version is not specified in the request, the latest version will be specified in the response.
Example1.0
requestId stringRequired: Uniquely identifies a request within TAP
Example101901031657410007
timeStamp stringRequired: Processed timestamp
Example20190103165801
statusCode string enumRequired: Status code for the request. S = success, E = error, P = partial. See the status code table.
AllowedS1000E1303E1308E1309E1312E1313E1315E1317E1318E1319E1325E1334E1341E1342E1343E1601E1603
ExampleS1000
statusDetail stringRequired: Human-readable description of the status. See the status code table.
ExampleSuccess.

JSON

{
  "version": "1.0",
  "requestId": "101901031657410007",
  "timeStamp": "20190103165801",
  "statusCode": "S1000",
  "statusDetail": "Success."
}

Status codes this endpoint returns17

Status codes for /ussd/send
`S1000`	Process completed successfully for all the available destination numbers.
`E1303`	IP address from which this request originated is not provisioned to send requests to application <application-id>. Please use a provisioned system to send requests or contact system admin to provision the new IP.
`E1308`	Permanent charging error due to <specify_reason E.g., Insufficient Balance>.
`E1309`	Requested SMS service is not allowed for this Application. Please check the issue with mSpace system administrator.
`E1312`	Request is invalid. <specify_the_reason> Refer the TAP NBL API Developer Guide for the mandatory fields and correct format of the request.
`E1313`	Authentication failed. No such active application with applicationId <application-id>, or no active service provider or the given password in the request is invalid.
`E1315`	Cannot find the requested service SMS or it is not active.
`E1317`	<MSISDN> in request is invalid or not allowed.
`E1318`	Transaction limit per second has exceeded. Please throttle requests not to exceed the transaction limit. Contact TAP admin to increase the traffic limit.
`E1319`	Transaction limit for today has exceeded. Please try again tomorrow or contact TAP admin to increase the transaction per day limit.
`E1325`	Format of the address is invalid. Expected format is tel:8801959979376.
`E1334`	SMS sent to <application name> application could not be processed as the message length is too long. Maximum message length allowed is <specify_max_limit>.
`E1341`	Request failed. An error occurred while sending the request for all the destinations.
`E1342`	MSISDN is black listed. Not authorized to use the application <application_name>.
`E1343`	MSISDN is not white listed. Only white list numbers are allowed to send messages at this state.
`E1601`	System experienced an unexpected error.
`E1603`	Temporary system error occurred while delivering your request.

POSTAppLink calls you

USSD Receive Services

your endpoint · /ussd/receive

This service allows TAP to deliver MO (Mobile Originate) messages to the application using an HTTP-based API. The flow of messages is initiated by an MO request sent to an application, and TAP will deliver the message to the application as an acknowledgement. Hence it could be either a request-response exchange or a request-exception exchange. A Receive USSD request is an MO message which will be sent to the application through AppLink as a delivery request.

Body AppLink sends you

application/json;charset=utf-8

version stringRequired: API version shall be numbered as 1.0, 2.0 etc. If version is specified in the request, same version must be sent in the response. If version is not specified in the request, the latest version will be specified in the response.
Example1.0
applicationId stringRequired: Used to identify the application. This is a unique identifier generated while provisioning an application. Only a single value can be sent per request.
ExampleAPP_000029
message stringRequired: Content of the message sent by the user
Example*141#
requestId stringRequired: Uniquely identifies a request within TAP
Example1330933229901
sessionId stringRequired: Unique number that USSD Gateway assigns to the application for the duration of the session. This number will be maintained in all the messages throughout a single session.
Example1330929317043
ussdOperation string enumRequired: USSD operation mo-cont:TAP to assign for and 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
Allowedmo-initmo-contmt-initmt-contmt-fin
Examplemt-cont
sourceAddress stringRequired: Address of the source. sourceAddress: tel:+8801959979376 at least one will be specified
Exampletel:+8801959979376
vlrAddress stringOptional: VLR(Visitor Location Register) address of the sender
Exampletel:+8801959979376
encoding string enumRequired: Encoding scheme used in the message 440 - Plain ASCII characters
Allowed440
Example440

{
  "version": "1.0",
  "applicationId": "APP_000029",
  "message": "*141#",
  "requestId": "1330933229901",
  "sessionId": "1330929317043",
  "ussdOperation": "mt-cont",
  "sourceAddress": "tel:+8801959979376",
  "vlrAddress": "tel:+8801959979376",
  "encoding": "440"
}

Body you return

statusCode string enumRequired: Status code for the request. S = success, E = error, P = partial. See the status code table.
AllowedS1000E1303E1308E1309E1312E1313E1315E1317E1318E1319E1325E1334E1341E1342E1343E1601E1603
ExampleS1000
statusDetail stringRequired: Human-readable description of the status. See the status code table.
ExampleSuccess

JSON

{
  "statusCode": "S1000",
  "statusDetail": "Success"
}

Status codes this endpoint returns17

Status codes for /ussd/receive
`S1000`	Process completed successfully for all the available destination numbers.
`E1303`	IP address from which this request originated is not provisioned to send requests to application <application-id>. Please use a provisioned system to send requests or contact system admin to provision the new IP.
`E1308`	Permanent charging error due to <specify_reason E.g., Insufficient Balance>.
`E1309`	Requested SMS service is not allowed for this Application. Please check the issue with mSpace system administrator.
`E1312`	Request is invalid. <specify_the_reason> Refer the TAP NBL API Developer Guide for the mandatory fields and correct format of the request.
`E1313`	Authentication failed. No such active application with applicationId <application-id>, or no active service provider or the given password in the request is invalid.
`E1315`	Cannot find the requested service SMS or it is not active.
`E1317`	<MSISDN> in request is invalid or not allowed.
`E1318`	Transaction limit per second has exceeded. Please throttle requests not to exceed the transaction limit. Contact TAP admin to increase the traffic limit.
`E1319`	Transaction limit for today has exceeded. Please try again tomorrow or contact TAP admin to increase the transaction per day limit.
`E1325`	Format of the address is invalid. Expected format is tel:8801959979376.
`E1334`	SMS sent to <application name> application could not be processed as the message length is too long. Maximum message length allowed is <specify_max_limit>.
`E1341`	Request failed. An error occurred while sending the request for all the destinations.
`E1342`	MSISDN is black listed. Not authorized to use the application <application_name>.
`E1343`	MSISDN is not white listed. Only white list numbers are allowed to send messages at this state.
`E1601`	System experienced an unexpected error.
`E1603`	Temporary system error occurred while delivering your request.