SMSmessaging (v2,v3)

Content

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

Last updated on 29th Oct 2019