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.
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.stream.ru.com/sms/send |
Request
Following is a sample request of send service.
|
{
"message": "Hello",
"destinationAddresses": [ "tel:+79161234567"],
"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: +79161234567, tel: +79161234567 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:+79161234567" ],
"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 Stream | 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:+79161234567",
"timeStamp": "20120515093023",
"messageId": "dfsfs1213",
"statusCode": "S1000",
"statusDetail": "Success",
},
{
"address": "tel:+79161234567",
"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:+79161234567",
"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 Stream | 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:+79161234567",
"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 Stream, then the Stream 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:+79161234567",
"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:+79161234567 |
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 Stream | String | Mandatory |
| deliveryStatus | Enum From SMPP Gateway : DELIVRD,EXPIRED, DELETED, UNDELIV, ACCEPTD,UNKNOWN, REJECTD Enum from Stream 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
“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.
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.
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.
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 | +79161234567 |
| 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.
If the “Encoding” type selected as “Binary”, a Binary Header has to be specified. Refer the figure below.
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.
