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.

Following are the Request parameters of Send service.

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:

Response

Following is a sample response of send service.

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:

Comprehensive sample response:

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.

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:

Response

Following is a sample response of receive service.

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:

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.

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.

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:

Note: sample status and error codes are listed in the Appendix a

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