SMS#

Acceptable data types when sending a request:

  • text data are transmitted as a text SMS message;

  • binary data are transmitted in the body of SMS message.

Lifetime of SMS messages: from 1 to 2880 minutes (no more than 48 hours).
The message lifetime is configured on the Service Provider’s side in agreement with the Partner.

Sending Request#

POST and GET requests are allowed in the HTTP API.

Request Examples#

POST request with a message in Latin “test“ in a simple text format.

{
    POST /login HTTP/1.1
    Host: 10.10.10.10:9080
    Content-Type: application/x-www-form-urlencoded;charset=utf-8
    Content-Length: 58
    serviceId=login&pass=123&clientId=79161234567&message=test
}

Request Parameters#

The parameters are applicable for POST and GET requests.

The mandatory parameters are highlighted in bold.

Parameter

Type

Description

clientId

string
Subscriber’s phone number, no more than 25 characters.
Examples: 79036550550, +79036550550, 8-903-655-05-50, 89036550550.

message

string
A message to send to the subscriber.
To send in this parameter:

  • for the GET method, the text must be encoded in UTF-8 while sending a text message;

  • for the POST method, the text must be encoded in UTF-8, which is specified in the request header.

Maximum allowed message length for SMS: 2000 characters.

Важно

When sending SMS messages with the flash attribute set the message length should not be more than 70 characters (for Cyrillic text) or 140 characters (for Unicode text).

serviceId

string

An ID of the Partner’s service (login), which is used to send a message. The Service Provider establishes serviceId while enabling the Partner’s service and reports it to the Partner.

pass

string

A password for authorization in the service. The Service Provider establishes the password while enabling the service and reports it to the Partner.

ptag

string

Message identifier in the Partner’s system. It may contain from 1 to 50 characters. Valid characters: 0…9a…zA…Z-

It may be any identifier in the Partner’s system.

Примечание

For example, it may be the unique identifier of message or the identifier of subdivision, which initiates the request for sending. In contrast to partnerMsgId parameter, which is needed to control resending and duplication, the Service Provider does not control values sent in ptag parameter (only format compliance is checked).

The Service Provider optionally returns this identifier to the Partner as part of a request for receiving of the message delivery status (this functionality is described in the section «Service of message delivery status receiving»).

sending_time

string
Local time to send a message to a subscriber.
Specified in the hh_hh format, where two hour values specify the time period in which the message should be sent.

Предупреждение

If the parameter is specified, then its value cannot be empty.

Примечание

For example, if the parameter value is sending_time=10_20, the message will be sent within the period from 10:00 to 20:00 local time in the time zone of the subscriber.

The time zone of the subscriber is determined not by actual location of the subscriber.
If the Partner doesn’t send the time_zone parameter, the time zone of the subscriber will be determined by the phone number.
If the Partner sends the time zone in the time_zone parameter, the message will be sent to the subscriber according to local time of this time zone.

time_zone

string

The time zone of the subscriber. Specified in the ±hh:mm format. For details see ISO 8601.

If the Partner sends the value time zone in this parameter, the message will be sent to the subscriber according to local time of this time zone, otherwise the time zone of the subscriber will be determined by the subscriber’s phone number.

Примечание

The subscriber with the number from Khabarovsk is in Moscow. The following sending options are available:

  1. The values are received: sending_time=10_20, time_zone=+04:00 (Moscow time).

    The message will be sent within the period from 10:00 to 20:00 Moscow time.

  2. The value sending_time=10_20 was received and time_zone parameter wasn’t passed.

    The message will be sent within the period from 10:00 to 20:00 Khabarovsk time.

For the zero zone it is necessary to specify a sign «+» or «–«.
The «+» sign will be transformed into «%2B» when encoded in URL.
For example, the +04:00 time zone will be sent as time_zone= %2B04:00.

flash

string
An attribute of sending Flash-SMS.
If flash=1, Flash-SMS will be sent to the subscriber.
If the parameter is missing or not equal to «1», a common SMS message will be sent.
The maximum length of SMS messages with the flash attribute set:

  • 70 characters (for Cyrillic text);

  • 140 characters (for unicode text).

source

string

Name of the sender. The message will be sent to the subscriber from the service name specified in this parameter.

This parameter is optional. If the parameter is missing in the request, the message will be sent to the subscriber from the default service name (setting on the Service Provider’s side).

Важно

This parameter is not available for the Partner by default. This feature can be activated only after approval by the Service Provider. In this case, the list of allowed sender names is set for the Partner’s service or the dynamic signature feature is activated.

output

string

Request response format.

If output=xml, the response to request will be formed as XML (see Response in XML format).

If the parameter is not defined or is different, the default format is used: text/plain (see Response to the request).

partnerMsgId

string

The message unique identifier in the Partner’s system. Allowable length: from 1 to 50 characters.

This parameter is required for resending and duplicate control. The Partner can send a request to send a message several times with the same partnerMsgId.

At that:

  • the message will be sent to the subscriber only once (when the first request is received);

  • in responses to requests the Service Provider will return to the Partner the same message identifier in the Service Provider system (the same that was sent for the first request).

The Service Provider as an option returns this identifier to the Partner as a part of the request for receiving the message delivery status (see section «Service of delivery status receiving»).

This parameter is not available by default. The connection of this functionality should be agreed with your manager.

smsPriority

integer

The parameter indicates the priority of the message.

Messages with a higher priority are sent to the operator first.

Possible values:

  • 0 is the lowest priority;

  • 1 is a normal priority;

  • 2 is a high priority.

Важно

This parameter is not available by default. The connection of this functionality should be agreed with your supervising manager.

shortenLinks

boolean

The parameter controls the automatic shortening of long links in the message.

Важно

It is used for single messages only.

If cascade resending, you need to use the shorten_list parameter (see Cascading Message Sending).

Важно

This option is not available by default. The connection of this functionality should be agreed with your supervising manager.

For more details: Link Shortening Service.

Requests with Binary Data#

When transmitting binary data, a sequence of bytes in the hexadecimal number system is transmitted in the message text.

To send binary data in a POST or GET request, you need to indicate additional parameters specified in the table below.

Request Examples#

{
    POST /login HTTP/1.1
    Host: 10.241.0.194:9080
    Content-Type: application/x-www-form-urlencoded;charset=utf-8
    Content-Length: 208
    serviceId=login&pass=123&clientId=79161234567&message=0605040b8423f0dc0601ae02056a0045c60b03687474703a2f2f7761702e7A616772757A6B612e636F6D0001035A616772757A6B6155524C000101&smpp_encoding=245&smpp_esm_class=64
}

Parameters for Binary Data#

Parameters for binary data sending in a request.

The mandatory parameters are highlighted in bold.

Parameter

Type

Description

message

string
When sending binary data, the parameter contains a sequence of bytes in hexadecimal representation (standard HEX Decimal).
Other characters in the text is unacceptable.
To send a binary SMS message (GET or POST), the text must be in UTF-8 encoding.
Maximum allowed message length for SMS: 2000 characters.

smpp_encoding

integer
For the correct delivery of a binary SMS message additional parameters in the request must be transmitted that ensure the correct interpretation of the data after sending using the SMPP protocol version 3.4.
For certain types of messages, one of the parameters (or both at the same time) is specified.
Many of the values for these parameters are specified by SMPP version 3.4 in sections for smpp_encoding and smpp_esm_class parameters.
When sending a binary message to a subscriber, the specified values of smpp_encoding and smpp_esm_class parameters are put in all its parts.
If none of the smpp_encoding and smpp_esm_class parameters are specified, the message will be processed as the text message.

smpp_esm_class

integer

Response#

After receiving and processing the request, the Service Provider synchronously returns the response to the Partner.
By default, the response from the Service Provider comes in the text/plain format.
In agreement with the Partner, the response can be generated in XML format.

Примечание

The Service Provider sends messages to subscribers only if the request is successfully processed.

Response in the Text Format#

Successful Sending#

In case of successful processing of the request Service Provider returns to the Partner:

  • HTTP code «200 OK»;

  • the ID of the message in the Service Provider’s system.

{
     OK
     4095284974
}

Sending Errors#

When sending an incorrect request a short text error message may be transmitted in the response body.

An example of an error response – invalid serviceId/pass combination:

{
    Invalid password
}

Response in the XML Format#

To receive the response in XML format the Partner need to send the output=xml parameter in the body of the request.
In this case, the Service Provider synchronously responds to the request with one of the following HTTP codes:

  • 200 – the request was successfully processed;

  • 500 – internal server error, technical problems on the Service Provider’s side.

Response Examples#

Response example in XML format in case of successful request sending (HTTP code 200).

{
    <?xml version="1.0" encoding="utf-8"?>
    <response>
        <code>200</code>
        <text>OK</text>
        <payload>
            <id>4095284976</id>
        </payload>
    </response>
}