sms API

SMS API

You can send and receive a SMS using a HTTP based API. It can send a sms behalf of the user, check the delivery status of the sent SMS and can receive a SMS with a short code

How to send a SMS in IdeaPro (MT)

You can use this to send a SMS from an application to a mobile phone. Send service supports only POST HTTP requests. An application wishing to initiate an MT (Mobile Terminated – Delivery of messages from an Ideamart application to a mobile subscriber’s handset) SMS message should use this.

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:5C74B588F97”],

“password”: “password”,

“applicationId”: “APP_999999”

}

Following are the Request parameters of Send service.

Comprehensive sample request:

Parameter Name

Description

Type

Mandatory /Optional

application ID

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.

destination Address

List of destination addresses should be Hash Codes.

tel: for MSISDN

tel: 5C74B588F97,

tel: 5C74B588F97

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.

String

 Mandatory

sourceAddress

The sender address to be shown – can be one of the provisioned values in alias list.

String

Optional

delivery Status Request

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.

 charging Amount

 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

 binary Header

 For advanced type messages where the binary header shall be sent from the application.

 Hexadecimal String

 Optional

{

“message”: “Hello”,

“password”: “password”,

“sourceAddress”: “77000”,

“deliveryStatusRequest”: “1”,

“chargingAmount”: “15.75”,

“destinationAddresses”: [“tel: 5C74B588F97”],

“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: 5C74B588F97”,

“timeStamp”: “20120515093023”,

“messageId”: “dfsfs1213”,

“statusCode”: “S1000”,

“statusDetail”: “Success”

},

{

“address”: “tel: 5C74B588F97”,

“timeStamp”: “20120515093023”,

“messageId”: “dfsfs12232”,

“statusCode”: “S1000”,

“statusDetail”: “Success”

}

]

}

}

 

Comprehensive sample response:

{

“statusCode”: “S1000”,

“statusDetail”: “Success”,

“messageId”: “MSG_000111”,

“version”: “1.0”

}

 

How to receive a SMS in IdeaPro (MO)

 

This service allows you to retrieve SMSs sent to the Ideamart application. Receive service returns only a list of SMS messages received since the previous invocation of the method to receive SMS. Also referred to as MO (The message is originated at the mobile phone’s end)

Request

 

Following is a sample request of receive service.

{

“message”: “my testing message”,

“address”: “tel: 5C74B588F97”,

“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: 5C74B588F97”,

“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

 

How to Receive a Delivery Report in IdeaPro

 

If, when creating an IdeaPro application, you have requested for a status report from Ideamart, the Ideamart platform 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: 5C74B588F97”,

“timeStamp”: “20120113082110”,

“requestId”: “MSG_000111”,

“deliveryStatus”: “DELIVERED”

}

Following are the request parameters of status report service.

Parameter Name

Description

Type

Mandatory /Optional

destination Address

Address of the subscriber

E.g. tel: 5C74B588F97

String

Mandatory

time Stamp

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

delivery Status

Enum From SMPP Gateway : DELIVRD,EXPIRED, DELETED, UNDELIV, ACCEPTD,UNKNOWN, REJECTD

Enum from Ideamart to Application:DELIVERED, EXPIRED, DELETED,UNDELIVERABLE, ACCEPTED,UNKNOWN, REJECTED

String

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

status Code

The status code for the entire request

String

Mandatory

statusDetail

The status detail for the entire request

Request     

                         

Following is a sample request of send service.

{

“message”: “Hello”,

“destinationAddresses”: [“tel:5C74B588F97”],

“password”: “password”,

“applicationId”: “APP_999999”

}