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 |
OptionalIf not specified shall be validated against the latest version. |
destination Address |
List of destination addresses should be Hash Codes.tel: for MSISDNtel: 5C74B588F97,tel: 5C74B588F97Address 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. |
Enumerator0 – DeliveryReport notRequired1 – DeliveryReport Required |
OptionalIf not specified shall be assumed to be a request without the need for Delivery Report. |
encoding |
Encoding scheme used in the message. |
Enumerated0 – Text240 – Flash SMS245 – Binary SMS |
OptionalIf 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.AddresstimeStamp – Processed Time stampmessageId – Message IdentifierstatusCode – Status CodestatusDetail – Status detailE.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. |
Enumerated0 – Text240 – Flash SMS245 – 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 subscriberE.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, REJECTDEnum 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”} |