CODE YOUR APPS
SMS – API
Overview
The SMS Interface allows applications to send and receive SMS messages using a HTTP-based API. Supported services are as follows:
- Send Service – An application wishing to initiate an MT (Mobile Terminated) SMS message should use this operation type.
- Receive Service – This retrieves the SMS sent to the application.
- Status Report Service – If an application when performing a Send service Operation had requested for a status report from TAP, then the TAP will initiate the status report service to hand over the status report to the application.
HTTP Rest
In this context, both requests/responses used to exchange information are with content type “application/json”.
JSON Objects
JSON objects are used as content type to communicate between application and TAP. JSON is an open, text-based data exchange format; it is human-readable, platform independent, and supports a wide availability of implementations.
SMS
The SMS REST Service provides operations for sending SMS to TAP and to receive the SMS.
E.g., A user sending a text message to a mobile phone from an application and receiving SMS from a mobile phone to an application.
Send Service
This service lets the user send SMS to one or more terminals (phones or any SMS-enabled device) from their application.
Send service supports only POST HTTP requests. This is used when sending SMS to a mobile phone from an application.
An application wishing to initiate an MT SMS message should use this operation type.
Request
Following is a sample request of send service.
{
"message":"Hello"
"destinationAddresses":["tel:94232323232"],
"password":"password",
"applicationId":"APP_999999"
}| 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, 2.0 etc | String | Optional If not specified shall be validated against the latest version |
| destinationAddresses | List of destination addresses should be telephone numbers tel – for MSISDN tel: 94232323232, tel:94232323232 Address can also have the value – tel: all which will in turn be a message to the subscribed base of the application Note : tel might be a masked number depending on the type of application | String | at least one need to be specified |
| message | The message that need to be sent, Messages over the limit shall be broken up by the platform and messaged | String | Mandatory |
| sourceAddress | The sender address to be shown – can be one of the provisioned values in alias list | String | Optional |
| deliveryStatusRequest | To indicate the need of Delivery Status Report for the message. | Enumerator 0 – Delivery Report not required 1 – Delivery Report Required | Optional If not specified shall be assumed to be a request without the need for Delivery Report |
| encoding | Encoding scheme used in the message. | Enumerated 0 – Text 240 – Flash SMS 245 – Binary SMS | Optional If not specified taken as Text If the encoding type is “Binary” then the message content will be represented as hex encoded. |
| chargingAmount | Charging amount specified for variable charging applications | Number to 2 decimal places – shall be considered only in system currency E.g., 78.05 | Optional |
| binaryHeader | For advanced type messages where the binary header shall be sent from the application | Hexadecimal String | Optional |
Comprehensive sample request:
{
"message":"Hello",
"password":"password",
"sourceAddress":"77000",
"deliveryStatusRequest":"1",
"chargingAmount":":15.75",
"destinationAddresses":["tel:94232323232"],
"applicationId":"APP_999999",
"encoding":"245",
"version":"1.0"
"binaryHeader":"526574697265206170706c69636174696f6e20616e642072656
c6561736520524b7320696620666f756e642065787069726564",
} Response
Following is a sample response of send service.
{
"statusCode":"S1000",
"statusDetail":"Success"
"requestId":"MSG_000111"
"version":"1.0"
}Following are the Response parameters of Send service.
| Parameter Name | Description | Type | Mandatory / Optional |
|---|---|---|---|
| version | API version shall be numbered as 1.0, 2.0 etc If version was specified in request, same version must be sent in response. If version was not specified in request, then latest version will be specified in response. | String | Mandatory |
| requestId | requestId to uniquely Identify the request within the TAP | String | Mandatory |
| statusCode | The status code for the entire request | String | Mandatory |
| statusDetail | The status detail for the entire request | String | Mandatory |
| destinationResponses | The list of responses for the full list of addresses It will be a collection with individual entry for each element in the address list of the request. Address – timeStamp – Processed Time stamp – messageId – Message Identifier – statusCode – Status Code – statusDetail – Status detail E.g., given below | String | Mandatory |
Sample Destination Response:
{
"DesinationResponses":{
"DestinationResponse":[
{
"address":"tel:94232323232",
"timeStamp":"20120515093023",
"messageId":"dfsfs1213",
"statusCode":"S1000",
"statusDetail":"Success"
},
{
"address":"tel:94232323232",
"timeStamp":"20120515093023",
"messageId":"dfsfs12232",
"statusCode":"S1000",
"statusDetail":"Success"
}
]
}
}Comprehensive sample response:
{
"statusCode":"S1000",
"statusDetail":"Success"
"messageId":"MSG_000111"
"version":"1.0"
} Receive Service
This retrieves the SMS sent to the web application. Receive service returns only a list of SMS messages received since the previous invocation of the method to receive SMSs
Request
Following is a sample request of receive service.
{
"message":"my testing message",
"address":"tel:94232323232",
"requestId":"APP_000001",
"encoding":"0",
"version":"1.0"
}Following are the Request parameters of receive service.
| Parameter Name | Description | Type | Mandatory / Optional |
|---|---|---|---|
| version | API version shall be numbered as 1.0, 2.0 etc | String | Mandatory |
| applicationId | Application ID as given when provisioned | String | Mandatory |
| sourceAddress | source address sourceAddress: tel:94232323232 | String | at least one will be specified |
| message | Message as sent from the user | String | Mandatory |
| requestId | Request Identifier in the TAP | String | Mandatory |
| encoding | Encoding scheme used in the message If the encoding type is “Binary” then the message content will be represented as hex encoded. | Enumerated 0 – Text 240 – Flash SMS 245 – Binary SMS | Mandatory |
Comprehensive sample request:
{
"message":"my testing message from app1",
"sourceAddress":"tel:94232323232",
"requestId":"APP_000001",
"encoding":"0",
"version":"1.0"
}Response
Following is a sample response of receive service.
{
"statusCode":"E1308",
"statusDetail":"Error during the charging operation"
}Following are the Response parameters of receive service.
| Parameter Name | Description | Type | Mandatory / Optional |
|---|---|---|---|
| statusCode | The error code for the entire request | String | Mandatory |
| statusDetail | The error detail for the entire request | String | Mandatory |
Comprehensive sample response:
{
"statusCode":"E1308",
"statusDetail":"Error during the charging operation"
} Delivery Status Report Service
When performing a SendSms Operation if an application had requested for a Delivery Response message from the Message Centre, then the TAP will initiate the Delivery Report service to hand over the Delivery Response message to the application. The messageId should be used to match the MT response with the Delivery Report.
Request
Following is a sample request of delivery status report service.
{
"destinationAddress":"tel:94232323232",
"timeStamp":"20120113082110",
"requestId":"MSG_000111",
"deliveryStatus":"DELIVERED"
}Following are the request parameters of status report service.
| Parameter Name | Description | Type | Mandatory / Optional |
|---|---|---|---|
| destinationAddress | Address of the subscriber E.g., tel:94232323232 | String | Mandatory |
| timeStamp | The timestamp sent from the SMS “yyMMddHHmm” yy – last two digits of the year (00-99) MM – month (01-12) dd – day (01-31) HH – hour (00-23) mm – minute (00-59) | String | Mandatory |
| requestId | requestId to uniquely Identify the request within the TAP | String | Mandatory |
| deliveryStatus | Enum From SMPP Gateway : DELIVRD, EXPIRED, DELETED, UNDELIV, ACCEPTD, UNKNOWN, REJECTD Enum from TAP to Application: DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ACCEPTED, UNKNOWN, REJECTED | Mandatory |
Response
Following is a sample request of delivery status report service.
{
"statusCode":"S1000",
"statusDetail":"Success"
}
Following are the response parameters of status report service.
| Parameter Name | Description | Type | Mandatory / Optional |
|---|---|---|---|
| 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",
"statusDetail":"Success"
} Status Codes and Error Codes
Status Codes (Non Retry able)
| CODE | DESCRIPTION |
|---|---|
| S1000 | Process completed successfully for all the available destination numbers. |
Error Codes (Non Retry able)
| Code | Description |
|---|---|
| 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. |
| E1303 | IP address from which this request originated is not provisioned to send request to application application-id. Please use a provisioned system to send request or contact system admin to provision the new IP. |
| E1312 | Request is Invalid. specify_the_reason Refer the TAP NBL API Developer Guide for the mandatory fields and correct format of the request. |
| E1309 | Requested SMS service is not allowed for this Application. Please check the issue with TAP system administrator. |
| E1311 | Mobile terminated SMS messages have not enabled. Check your NCS configuration in provisioning. |
| E1315 | Cannot find the requested service SMS or it is not active. |
| E1317 | MSISDN in request is invalid or not allowed. |
| E1341 | Request failed. Errors occurred while sending the request for all the destinations. |
| 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 |
| E1335 | SMS sent to application name application could not be processed as the advertisement message length is too long. Maximum message length allowed for advertisements is specify_max_adv_limit |
| E1601 | System experienced an unexpected error. |
| 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. |
| E1325 | Format of the address is invalid. Expected format is “tel:94232323232” |
| E1331 | sourceAddress is not allowed. Please use one of the values configured in alias configuration in the SLAs or send the request without sourceAddress, so TAP will use the default source address to send the message to subscriber. |
| E1308 | Permanent charging error due specify_reason E.g., Insufficient Balance>. |
Error Codes (Retry able)
| Code | Description |
|---|---|
| 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 is exceeded. Please try again tomorrow or contact TAP admin to increase the transaction per day limit |
| E1603 | Temporary System Error occurred while delivering your request. |
What follows is a list of definitions of all terms, acronyms and abbreviations required to properly interpret this document.
- NCS – Network Capability Service
- SMS – Simple Message Service
- HTTP – Hyper Text Transfer Protocol
- MO – Mobile Originated
- MT – Mobile Terminated
- MSISDN – Mobile Station Integrated Services Digital Network
- SLA – Service Level Agreement