SMSmessaging (v2,v3)
Content
- Overview
- Method
- Requirements
- Sending SMS
- Recieving SMS
- Delivery Notifications
- Delivery Report
- Response Codes
- Exceptions
- Faults
- Libraries and Samples
Overview
The Dialog SMS API allows an application to send and receive SMS messages. These services are accessible via RESTful web services.Standard SMS messages (English, Alpha Numeric) are limited to 160 characters per message. If a message exceeds this limit, it is broken up into multiple segments of 160 characters each, and transmitted through the network, If SMS is sent/received as a Unicode string(Special characters & non-English text), such SMS are limited to approx.70 characters, If a message exceeds this limit, it is broken up into multiple segments of 70 characters each, and transmitted through the network,Note that the Operator or the API platform does not block any characters that exceed this length. It is advised to adhere to these limits within your application. (operator charges are applied per SMS transmitted and not per API call)
Method
The following REST methods are available:
- Send an SMS from your Web Application
- Query the Delivery Status of an SMS
- Retrieve SMS Sent to your Web Application (which is identified by the registrationId)
Requirements
Authorization API Calls All API call requests to ideabiz.lk require Authorization headers. Please refer the Token Management (http://docs.ideabiz.lk/Getting_Started/Token_Manegment) document for Authorization.
Request Header
Content-Type: application/json
Authorization: Bearer [access token]
Accept: application/json
Sample Request Header
Content-Type: application/json
Authorization: Bearer a92ba8hjgjhgjh3fa1609cabcd79
Accept: application/json
If sending a unicode string with the message, please set Content-Type
charset to UTF-8
Content-Type: application/json;charset=UTF-8
Note: If sending Unicode string, such string is broken up into multiple segments of approx.70 characters each, and transmitted through the network as multiple SMS.
Encrypted MSISDN
SMS API is compatible with Encrypted MSISDN Please refer the Secure Header (http://docs.ideabiz.lk/APIs/Header_Enrichment) document for encrypted MSISDNs.
Sending SMS
This allows you to send an SMS from your Web application to one or more addresses (MSISDNs). Even though several MSISDNs can be included in one API call, they will be transmitted through the network as separate SMS.
Request
Given below is a sample request of the send service.
URL
https://ideabiz.lk/apicall/smsmessaging/{version}/outbound/{port}/requests
Sample
https://ideabiz.lk/apicall/smsmessaging/v3/outbound/87798/requests
Method
POST
Body
{"outboundSMSMessageRequest": {
"address": [
"tel:+ 94766691500"
],
"senderAddress": "tel:87711",
"outboundSMSTextMessage": {
"message": " Test SMS "
},
"clientCorrelator": "123456",
"receiptRequest": {
"notifyURL": "http://138.189.164.230:1080/sms/report",
"callbackData": "some-data-useful-to-the-requester"
},
"senderName": "ABCCo"
}
}
States of Parameters
States of the Request parameters of send service.
Parameter Name |
Description |
Type |
Mandatory /Optional |
---|---|---|---|
address |
At least one address must be provided.In this case it is the recipients MSISDN including the "tel:" protocol identifier and the country code preceded by "+".i.e., tel:+94766691500.OneAPI also supports the Anonymous Customer Reference (ACR) if provided by the operator. (However ACR is not supported in either versions of the SMSmessaging API) . |
string |
Mandatory |
senderAddress |
This is the Port number configured for you, by the ideabiz Support team.This is also the address to which, the SMS recipient may send a reply SMS. (Unless the senderAddress is hidden by the use of senderName.(See below)) |
string |
Mandatory |
message |
Must be provided within the outboundSMSTextMessage element. Messages over 160 characters may end up being sent as two or more messages by the operator. |
string |
Mandatory |
clientCorrelator |
Uniquely identifies this SMS request. If there is a communication failure during the request, using the same clientCorrelator, when retrying, the request allows the operator to avoid sending the same SMS twice. |
string |
Optional |
notifyURL |
The URL to which you would like to receive a notification of delivery of SMS.The format of this notification is shown below.(See Delivery Notifications) |
string |
Optional.Keep empty or null if you don't want delivery notifications. |
callbackData |
If Delivery Notifications were requested, this string will be passed back, so you can use it to identify the message, the receipt notification relates to (or any other useful data, such as a function name).This is only valid if notifications were requested. (See the notifyURL above) |
|
Optional |
senderName |
Use this only if you want to show a number other than the senderAddress for the recipient to respond to, or if you want to show an Alphanumeric port (Mask) in the SMS recipients phone.If this is kept blank, senderAddress will be used in its place.A Mask (Maximum 11 Char) has to be approved & configured by the ideabiz Support team before it can be used.Mask cannot contain special characters such as ~!@#$%^&*_=+-()`;:'"/?.,<> |
string |
Optional |
Response
Given below is a sample response of the send service.
Body
{
"outboundSMSMessageRequest": {
"deliveryInfoList": {
"deliveryInfo": [
{
"address": "tel:+94766691500 ",
"deliveryStatus": "MessageWaiting",
"messageReferenceCode": "D-O-42-12f93c0e5b1f470cb03947096f01fef9-1455613873"
}
],
"resourceURL": "https://ideabiz.lk/apicall/smsmessaging/v2/outbound/94766691500 /requests/D-O-42-12f93c0e5b1f470cb03947096f01fef9"
},
"serverReferenceCode": "D-O-42-12f93c0e5b1f470cb03947096f01fef9",
"address": [
"tel:+94766691500"
],
"senderAddress": "tel:87711",
"clientCorrelator": "123456",
"senderName": "ABCCo",
"outboundSMSTextMessage": {
"message": " Test SMS "
},
"receiptRequest": {
"notifyURL": "http://138.189.164.230:1080/sms/report",
"callbackData": "some-data-useful-to-the-requester"
}
}
}
Receiving SMS
This allows you to retrieve any SMS that have been sent to the port assigned to your Web application. Once your port or port:keyword receives an SMS, it will be pushed to your application as a JSON request.
{ "inboundSMSMessageNotification": { "callbackData": "callbackdata", "inboundSMSMessage": { "dateTime": "2016-01-01 03:00:00", "destinationAddress": "tel:+87711", "messageId": "D-I-42-12f93c0e5b1f0cb03947096f01fef", "message": "Test SMS", "senderAddress": "94766691500" } } }
Delivery Notifications
When you send the SMS API Call, you can mention a callback/notify URL. Delivery notifications will be pushed to the mentioned URL once the SMS is delivered.
{ "deliveryInfoNotification": { "callbackData": "some-data-useful-to-the-requester", "serverReferenceCode": "D-O-46-39524b230e3c4da9b95eb0053f7f", "messageReferenceCode": "D-O-46-39524b230e3c4da9b95eb0053f7f-40692", "senderAddress": "tel:+87711", "deliveryInfo": { "operatorCode": "DIALOG", "filterCriteria": "", "address": "tel:+ 94766691500 ", "deliveryStatus": "DeliveredToNetwork" } } }
Response Codes
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
Types
Policy Exception_
Message Id starts with PL
Server Exception_
Message Id starts with SV
Exception Body
{
"requestError": {
"serviceException": {
"messageId": "SVC0002",
"text": " Invalid input value for message part %1",
"variables": " clientCorrelator Value 12345"
}
}
}
Faults
For common platform related error responses (API Inactive/TPS Related, etc.), please refer (http://docs.ideabiz.lk/Tips/API%20Errors#platform-errors)
HTTP Respose code 400
Fault Response Body
{ Invalid input value for message part %1 }
HTTP Respose code 400
Fault Response Body
{ "requestError": { "serviceException": { "messageId": "POL7101", "text": "Mask not allowed to current application. Mask is %1", "variables": "%1 - Test" } } }
HTTP Respose code 500
Fault Response Body
{ "requestError": { "serviceException": { "messageId": "SVC7109", "text": "URL param port and sender address in request body is not match. %1 - URL param port, %2 - sender address in request body ", "variables": "%1 - 87798, %2 - tel:87711" } } }
HTTP Respose code 500
Fault Response Body
{ "deliveryInfoNotification":{ "callbackData":"CB1525108371514-560212557", "deliveryInfo":{ "address":"tel:+94778395180", "deliveryStatus":"DeliveredToNetwork", "operatorCode":"DIALOG", "filterCriteria":"?" } } }
HTTP Respose code 503
Fault Response Body
{ "fault": { "code": "900800", "message": "Message Throttled Out", "description": "You have exceeded your quota" } }
Libraries and Samples
- Java sample sms app (https://github.com/ideabizlk/Sample-JAVA-SMS-API)
- Java SMS handler that can use to send and read sms (https://github.com/ideabizlk/IdeaBiz-SMS-API-Handler-JAVA)
- Java Request handler that handle oAuth authentication (https://github.com/ideabizlk/IdeaBiz-Request-Handler-JAVA)
- PHP Request handler that handle oAuth authentication (https://github.com/ideabizlk/IdeaBiz-Request-Handler---PHP)
- C Sharp Request handler that handle oAuth authentication (https://github.com/ideabizlk/IdeaBiz-Request-Handler-CSharp)
- NodeJS Request handler that handle oAuth authentication (https://github.com/ideabizlk/IdeaBiz-Request-Handler---NodeJS)
- Java Class that inclue SMS classes (https://github.com/ideabizlk/Classes-JAVA)