SMS API


This is used to send and receive SMS using a HTTP based API. It sends SMS on behalf of the user, check the delivery status of a sent SMS, receive SMSs with a short code etc.

Basically SMS API can be used by a user to send a text message to a mobile phone from an application or to receive SMS from a mobile phone to an application.

Method

POST

 

Send Service

This is used when sending SMS to a mobile phone from an application. Send service supports only POST HTTP requests. An application wishing to initiate an MT (Mobile Terminated - Delivery of messages from a mobile business application to a mobile subscriber’s handset) SMS message should use this. URL for Send SMS Service is as follows:

Simulator:
http://localhost:7000/sms/send
Active production:
https://api.dialog.lk/sms/send

 

Request

Following is a sample request of send service.


{
  "message": "Hello",
  "destinationAddresses": ["tel:94777123456"],
  "password": "password",
  "applicationId": "APP_999999"
}

 

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.
destinationAddress 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 maskednumber depending on the typeof 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. 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 – DeliveryReport notRequired
1 – DeliveryReport 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 only. 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:94774747447"],
  "applicationId": "APP_999999",
  "encoding": "245",
  "version": "1.0",
  "binaryHeader": "526574697265206170706c69636174696f6e20616e642072656c6561736520524b7320696620666f756e642065787069726564"
}

 

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 Ideamart 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:94775454545",
        "timeStamp": "20120515093023",
        "messageId": "dfsfs1213",
        "statusCode": "S1000",
        "statusDetail": "Success"
      },
      {
        "address": "tel:94771234567",
        "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 SMS.

 

Request

Following is a sample request of receive service.


{
  "message": "my testing message",
  "address": "tel:94771234567",
  "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 is a masked number. String At least one will be specified
message Message as sent from the user String Mandatory
requestId Request Identifier in the Ideamart 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:94777123456",
  "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

 

Delivery Status Report Service

If an application when performing a Send service Operation had requested for a status report from Ideamart, then the Ideamart will initiate the status report service to hand over the status report to the application.

 

Request

Following is a sample request of delivery status report service.


{
  "destinationAddress": "tel:94774747447",
  "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 Ideamart String Mandatory
deliveryStatus Enum From SMPP Gateway : DELIVRD,EXPIRED, DELETED, UNDELIV, ACCEPTD,UNKNOWN, REJECTD
Enum from Ideamart 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.

 

ParameterName Description Type Mandatory /Optional
statusCode The status code for the entire request String Mandatory
statusDetail The status detail for the entire request String Mandatory

 

 

Using the Simulator

 

SMS MT

Figure 1.1

Figure 1.1

 

“Customers Phone” displays the messages received to the customer’s phone.

When a message is received to the customer’s phone, the phone screen displays the message as shown in the figure above.

Similarly, the “Messages sent to Customer” section shows the messages with the details (message sent time, destination phone number and message content) as shown in the figure below.

Figure 1.2

Figure 1.2

 

User can still test the MT part alone (without MO) with any application provided that it can send MT messages.

For that, send the MT message to the following URL (which accepts SMS MT) and the MT message will be displayed in the simulator.

http://localhost:7000/sms/send

 

SMS MO

To send a message to the application, the CP can use the provided interface in the simulator. Refer the figure below.

Figure 1.3

Figure 1.3

Above interface is to simulate message sending to the application.

 

If Delivery Report is required, the option under “Additional Requests” should be selected. Then the “Delivery Report URL” has to be specified, as in the figure below.

Figure 1.4

Figure 1.4

 

Enter the details as follows.

 

Field name Description Sample value
URL The URL where the application is hosted http://localhost:5555/mo-receiver
Application ID Unique ID of the Application APP_00001
Password Password of the application. The application password will be auto generated when the application is created. password
Customer Number The phone number from which the message is sent 94771234567
To Number The phone number which receives the message 77000
Encoding Message encoding type Text, Binary
(If the encoding type is set to “Binary” the Binary header should be specified.This is applicable only for SMS service.Refer figure 1.6)
Message Message content Test Message
Delivery Report Required Select the check box to generate Delivery Report request from the application side
Delivery Report URL URL which sends delivery reportsto the application. http://localhost:5555/deliveryReportsms
Status/Error Code Select the response status/error code to generate, when MT (Mobile Termination) message received from application. S1000:Success

 

Following figure shows sample Status/Error codes.

Figure 1.5

Figure 1.5

 

If the “Encoding” type selected as “Binary”, a Binary Header has to be specified. Refer the figure below.

Figure 1.6

Figure 1.6

Once the values are entered correctly, click on the “Send” button.

 

The messages sent to the application will be displayed with its sent time, phone number, message content and status under “Messages sent to Application” section.

Figure 1.7

Figure 1.7