Pricing plans  Services  API  Partners  About the service  Contacts 
8 (800) 700 7672
Free in Russia
 

Integration with the service (API)

The API allows you to send messages through your projects and services over the HTTP/HTTPS, SMTP, and SMPP protocols. Ready-made libraries in different programming languages connect to your project and help you send messages from anywhere with a single command.


HTTP/HTTPS SMTP SMPP SOAP OMS SMS Commands Libraries and code examples

SMPP Protocol

Connection

Through our SMS gateway, it is possible to send messages using the SMPP protocol versions 3.4 and 5.0.
To get access via the SMPP protocol, you must enable it in the settings in the group "API Settingsselect the appropriate option and add the IP addresses from which you will connect on this page.

SMPP server address: smpp.smscentre.com, port: 3700.
For an encrypted SSL connection, port 3443 is used.

Address of the backup SMPP server: smpp2.smscentre.com.

Example of connection settings (kannel format): group = smsc
smsc = smpp
smsc-id = smsc
host = smpp.smscentre.com
port = 3700
smsc-username = <login>
smsc-password = <password>
system-type = ""
interface-version = 34
source-addr-autodetect = yes
source-addr-ton = 5
source-addr-npi = 1
dest-addr-ton = 1
dest-addr-npi = 1
validityperiod = 1440
transceiver-mode = true
receive-port = 0
enquire-link-interval = 60
wait-ack-expire = 0
max-pending-submits = 300
throughput = 30

The maximum possible inactivity interval is 2 minutes. During this time, the Client needs to send a message or execute an empty ENQUIRE_LINK command, otherwise the connection will be terminated due to inactivity..


Example of additional settings for SSL connection (kannel versions 1.4.4 and higher): ...
port = 3443
ssl-client-certkey-file = "/etc/kannel.pem"
use-ssl = 1
...

The certificate can be generated by the command (Linux CentOS): /etc/ssl/certs/make-dummy-cert kannel.pem

The login is used from the personal account, the password must be created on the pagePasswords for access. The username and password must not be in Russian.
This section contains only a brief description of the SMPP protocol. For more information, see the specification.

Download the SMPP Protocol Specification v3.4 smpp34.zip (500 Kb) smpp34rus.zip (1,1 Mb).

The speed of mailing lists

The connection bandwidth or the number of SMS messages sent every second depends on the size of the transmission window (smpp window size). In the example settings, this parameter is called max-pending-submits. For mass mailings, it is better to set large values (1000-2000). Also in the example, the throughput parameter sets a limit on the maximum number of SMS messages per second..

Along with mass mailings, you can also send urgent single SMS notifications via a single connection. The system will set the maximum priority for such messages and send them before any mass mailings without waiting in the queue.

When sending mass messages, do not forget about the system for monitoring the speed of sending messages per second, when exceeding which an error of exceeding the speed is generated (throttling). If this error is received, the SMPP-standard Client must repeat the sending, reducing the overall speed on its side. By default, the speed is set to 30 SMS / sec for each account. To change the maximum allowed speed, you need to send a request to the service support service.

Multiple connections

By default, the server processes only one connection from one login at a time for a more correct return of statuses, so when you reconnect, the previously connected connection with the same username will automatically terminate. If you need to have multiple simultaneous connections to increase the speed of sending, you can set the following parameter in the settings of all connections (multi connection):
system-type = "MCON2"
or
system-type = "MCON9"
The value after MCON can be from 1 to 9 and specifies the number of simultaneous connections.

Simultaneous connections with different usernames linked to the same personal account and account are also possible. To do this, you need to create additional accounts with the required subaccount type in your personal account in the "Reseller" section.

Sending a message

Sending an SMS message

To send an SMS message, use the SUBMIT_SM command according to the specification.

ѕоддерживаютс€ следующие кодировки:
  • 7-bit GSM for Latin text with support for European characters − (coding = 0);
  • 8-bit ISO-8859-1 (ASCII) for Latin text or binary data − (coding = 1);
  • UCS2 (UCS-2BE or UTF-16BE) for national alphabets (for example, Russian) − (coding = 2).
The coding field is encoded by two bits in the composite data_coding field, so data_coding = coding * 4.

To use the ISO-8859-1 (ASCII) encoding instead of GSM when connecting, you need to specify:
system-type = "ISO"
You can add comments to the text of the SMS message , which are intended for the sender to view the message history in the personal account.

The SUBMIT_MULTI command for multiple mailing is not yet implemented.

The server does not accept more than one identical request for sending SMS messages within a minute to protect against errors and loops in the Client-side program in order to reduce the load and not spend the Client's funds, as well as to prevent multiple messages from being sent to the same subscriber.

The server also blocks sending more than 50 messages to one subscriber, which were sent with a break between messages of less than 30 seconds, to protect against flooding and unnecessary debiting of funds from the Client's account, since many operators do not pass a large number of messages to one subscriber in a short period of time.

When sending a composite message, all SMS parts must be transmitted to the server within a minute. Otherwise , the operator may reject the message, since to check for filters and templates, all SMS parts must first be glued together, and most operators wait no more than a minute.

Comments in SMS messages

When sending SMS messages, you can add any comment to the end of the text that clarifies or supplements the SMS message for the sender. This text will not be sent to subscribers and will not affect the cost of SMS and is available for viewing and filtering in the list of sent messages in your personal account.

To add a comment, you must specify a special combination "\n~~~\n " at the end of the text of the SMS message intended for sending (line feed, 3 of the tilde character, and again line feed), and after that, any text that will be considered a comment will not be sent to the subscriber, but will be displayed in the history.

Sending an MMS message

To send an MMS message, use the SUBMIT_SM command with the text " __MMS__: <message><message>\nsubj:<subject>" (text "__MMS__", colon, space, message text, line feed, text "subj", colon, subject of the MMS message).

Sending an e-mail message

To send an e-mail message, use the SUBMIT_SM command with the text " _ _ MAIL__: <message><message>\nsubj:<subject>" (text "_ _ MAIL__", colon, space, message text, line feed, word "subj", colon, subject of the e-mail message).

Sending a voice message (call)

To send a voice message, use the SUBMIT_SM command with the text " __CALL__: <message><message>\nvoice:<voice><voice>" (text "__CALL__", colon, space, message text, line feed, word "voice", colon, voice used to voice the text).

Possible values for the voice used:
  • m Ц male voice.
  • m2 Ц male voice 2.
  • m3 Ц male voice 3.
  • m4 (default) Ц male voice 4.
  • w Ц female voice.
  • w2 Ц female voice 2.
  • w3 Ц female voice 3.
  • w4 Ц female voice 4.
When sending a voice message, you can specify a special combination "\n~~~\n" at the end of the text (line feed, 3 of the tilde character, and again line feed), after which you can pass the param parameterthat defines some characteristics of the call (for more information, see the description).

Sending a viber message

To send a viber message, use the SUBMIT_SM command with the text " __VIBER__: <message><message>" (text "__VIBER__", colon, space, message text).

When forming the message text, you can use special macros to create a button that will open the browser and click on the link specified in the macro, as well as attach files. More details additional features for sending viber messages are described in the documentation for the http protocol.

Sending a soc message

To send a soc message sent to users of the Odnoklassniki, VKontakte, or Mail.Ru Agent social networks, use the SUBMIT_SM command with the text " _ _ SOC__: <message><message>" (text " _ _ SOC__", colon, space, message text).

Sending HLR-query

To send an HLR request, use the SUBMIT_SM command with the text __HLR__. The result of the request comes in the usual status (Delivery Report), which can be received both via the SMPP connection and via HTTP to your handler.

Status format with the result of an HLR request returned by SMPP: id:<id> stat:<status> err:<err> imsi:<imsi> msc:<msc> mcc:<mcc> mnc:<mnc> cn:<cn> net:<net> rcn:<rcn> rnet:<rnet>
Description of parameters:

OptionThe value
idMessage ID.
statusMessage status.
err од ошибки, если абонент недоступен (list).
imsiUnique IMSI code of the subscriber's SIM card.
mscThe number of the service center of the operator in whose network the subscriber is located.
mccNumeric code of the subscriber's country.
mncNumeric code of the subscriber's operator.
cnName of the country of registration of the subscriber.
netName of the subscriber registration operator.
rcnThe name of the roaming country of the subscriber when he is in a foreign network.
rnetThe name of the roaming operator of the subscriber when he is in someone else's network.

String data, such as country and operator, is encoded via the urlencode function.

Example of the result of an HLR request: id:855469 stat:DELIVRD err:000 imsi:250023012345678 msc:79232510066 mcc:250 mnc:02 cn:Russian+Federation net:MegaFON+open+Joint+Stock+Company rcn: rnet:
Sample PHP code for parsing a string with the result of an HLR request:
$dlr = strtr($dlr, ": ", "=&"); // $dlr - строка статуса
parse_str($dlr, $m); // $m - массив параметров, $m["id"], $m["err"], $m["imsi"] и тд.

Example of parsing through regular expressions:
preg_match("/^id:(\d+) stat:(\w+) err:(\d+) imsi:(\d*) msc:(\d*) mcc:(\d*) mnc:(\d*) cn:([^ ]*) net:([^ ]*) rcn:([^ ]*) rnet:([^ ]*)/", $dlr, $m); // $dlr - строка статуса
for ($i = 6; $i <= 9; $i++)
   
$m[$i] = urldecode($m[$i]);
// $m - массив параметров, $m[1] = id, $m[2] = status, $m[3] = err и тд.

To send a Ping-SMS, use the SUBMIT_SM command with the text _ _ PING__.

Checking the status

You can get the delivery status of a sent SMS message via the SMPP protocol either automatically by receiving the DELIVER_SM response PDU command from the server immediately after the status change, or by using a separate QUERY_SM command on request. To automatically get the status via the SMPP protocol, you need to connect in the following mode: transceiver or receiver and when sending SMS, specify the status request flag (registered_delivery). If you do not specify this flag when sending, the message statuses will be passed to the HTTP handler.

When the status is automatically returned, the DELIVER_SM command passes the standard TLV parameters recipted_message_id (<id>), message_state (numeric <status>) and network_error_code (<err>), as well as additional TLV fields described below:

Field name (code)SizeTypeDescription
8192 (0x2000)Var. max 6COctet StringThe cost of the message in the format " n.nnnn".
8193 (0x2001)2IntegerA flag in the form of a 2-byte number containing various information about the message. Combinations of bit values of different characteristics are possible.

0-3 bits (message type):
0 (by default) Ц SMS.
1 Ц Flash-SMS.
2 Ц Binary SMS.
3 Ц Wap-push.
4 Ц HLR-query.
5 Ц Ping-SMS.
6 Ц MMS.
7 Ц Call.
8 Ц E-mail.
10 Ц Viber.
12 Ц Social network.

Bit 5 Ц payment of the message from the second balance.
Bit 8 - indicates a template message.
8194 (0x2002)2IntegerNumber of parts per message.
8195 (0x2003)Var. max 5COctet Stringmccmnc Subscriber's country/operator code.
8196 (0x2004)2IntegerAdditional message status (2 Ц read, 4 Ц link clicked).

The DELIVER_SM command also passes the status text in the following format:
id:<id> sub:<sub> dlvrd:<dlvrd> submit date:<submit date> done date:<done date> stat:<status> err:<err>
Description of parameters:

OptionThe value
idThe message ID assigned by the server when sending the message.
subThe number of SMS parts in the sent message.
dlvrdNumber of SMS messages delivered.
submit dateDate sent.
done dateDate of status change.
statusMessage status as a string (DELIVRD, EXPIRED, UNDELIV).
errError code if the message cannot be delivered (list).

Example of the status line result (Delivery Report): id:854019 sub:001 dlvrd:001 submit date:1108202241 done date:1108202241 stat:DELIVRD err:000

By default, for long messages that are split into multiple SMS messages, the server returns only one status (DELIVER_SM) for the entire glued message and the same ID in the SUBMIT_SM_RESP response for all SMS parts of this message. To enable the processing mode and return statuses for each SMS part, set the following parameter separately in the connection settings (or in the settings of your personal account): system-type = "SINGLE"
If you need to specify several parameters in the system-type field, then specify them separated by commas: system-type = "ISO,SINGLE"

Receiving incoming messages

To enable the forwarding of incoming SMS messages via SMPP connection, you need to check the box "Send incoming SMS via SMPP connection" in the settings of your personal account (the drop-down tab "API Settings") or contact the support service. In this case, the transmission of incoming messages to the Client handler must be disabled.

Incoming messages are received in the DELIVER_SM PDU command. To receive it, you need to connect to the SMPP server in the transceiver or receiver mode.

Error codes in the status

Possible error codes in the status of messages or HLR requests (values of <err>):

CodeNameDescription
0No errorThe subscriber exists and is available.
1The subscriber does not existThe specified phone number does not exist.
6Subscriber is offlineThe subscriber's phone is disconnected or out of range of the network.
11The service is not connectedMeans that the subscriber cannot accept the SMS message. For example, the service is not connected, or the subscriber is roaming, where message reception is not activated, or the subscriber's operator does not exchange SMS messages with the current roaming operator. It can also be a landline number without receiving messages.
12Error in the subscriber's phoneThe message cannot be delivered to the subscriber due to an error in the phone or SIM card.
13Subscriber is blockedOccurs, for example, if the subscriber's account has a zero or negative balance, and it is roaming, or blocked by the operator for prolonged non-payment, or voluntarily by the subscriber himself. This error can also be returned if the SIM card is damaged or if the PIN and PUK codes of the SIM card are entered incorrectly.
21No support for the serviceThe subscriber's device does not support this service (service).
200Virtual sendingThis notification appears under the message status if the message is sent in test mode (if the "Test mode (virtual sending without payment)" checkbox is set in the settings )").
219Replacing the SIM cardError sending a message due to the subscriber replacing the SIM card. After the physical replacement of the SIM card, the subscriber is blocked from receiving messages from the letter names of the senders for 24 hours. The block can be lifted by adding 100 rubles to the balance..
220Queue overflowed from operatorThis error may occur when the subscriber is not available to receive SMS messages, but messages continue to arrive to the operator and the internal message queue for this subscriber is overflowing. In rare cases, an error may occur as a result of a failure in the network of the operator itself or an overflow of the general message queue. In all such situations, the system tries to resend the specified messages several times at certain intervals.
224Insufficient fundsThe Client's account does not have enough money to send the message.
237The caller is not respondingOccurs if the caller did not pick up the phone during the dial attempt.
238No templateOccurs if sending a message is possible only according to a certain template, and the message being sent does not satisfy it.
239Forbidden ip addressOccurs when trying to send a message from an ip address that is not included in the list of ip addresses allowed by the Client to send. It can also occur when you try to send a message from an ip address that was not previously used for sending messages and logging in to your personal account.
240Subscriber is busyOccurs when sending a voice message to a subscriber if the line is busy or the subscriber has canceled the call.
241Conversion errorAn audio conversion error occurred when converting a text or audio file to the destination format for sending a voice message to the subscriber. This error may also occur during transmission SMS messages in separate parts, when not all parts are transmitted to the operator.
242Recorded answering machineMeans that an answering machine was fixed on the subscriber's side when the voice message was sent .
243No contractOccurs when you try to send mailings of an advertising or mass nature without a signed contract.
244Mailing list is prohibitedIt means that the sending of mass and advertising mailings is prohibited for this Client, or a prohibited link is found in the message text.
245Status is not receivedDuring the day, the delivery status was not received from the operator, in this case, it is impossible to say for sure whether the message was delivered or not.
246Time limitIf in myalpari in the "Settings" in the tab "Limits and restrictions" it is set to "sending" and check "prohibit send at another time" when trying to send SMS messages in the period time specified in the field "sending", sending messages will be prohibited from showing this error.
247Limit exceeded messagesExceeded the total daily message limit specified by the Client in the personal account in the "Settings" section".
248No routeThis means that sending messages to this number is not available in our service. For example, you entered a non-existent mobile code, or there is no working SMS gateway for the specified number and text.
249Invalid number formatOccurs when the mobile code of the specified number and the number length corresponding to this code are incorrect.
250Telephone number is forbidden settingsThe number fell under the restrictions set by the Client for mobile numbers in the personal account in the "Settings" section".
251Limit is exceeded on a single numberExceeded the daily message limit per number. The limit is set By the Client in the personal account in the "Settings"section. Also, this error is possible when sending more than 50 messages to one subscriber, which were sent with a break between messages of less than 30 seconds.
252Number not permittedOccurs, for example, when a Client tries to specify one of our federal numbers as the recipient of an SMS message.
253Prohibited spam filterIf the text of the message contains obscene expressions and insults, calls to send sms and some other prohibited texts, then sending the message will be blocked. It is also forbidden to specify as the sender short paid numbers, the number of the recipient of messages, the names of operators, other people's Internet resources, companies and government organizations.
254Unregistered sender idThis error occurs when you try to send a message from an unregistered sender name.
255Rejected by operatorThe operator rejected the message without specifying the exact error code.
This happens, for example, when the number does not belong to any mobile operator, i.e. with a non-existent code, or for some other reason, the operator cannot deliver the message.

Possible error codes in the status of e-mail messages (values of <err>):

CodeNameDescription
0No errorThe recipient exists and is available.
1Recipient does not existThe specified e-mail address does not exist.
2Crowded InboxThe recipient's mail server rejected the message with the specified error code.
3Recipient server was not foundThe domain specified as the mail server was not found.
4Mailbox is lockedAn error returned from the recipient's mail server stating that the message could not be delivered due to the mailbox being blocked.
239Forbidden ip addressOccurs when trying to send a message from an ip address that is not included in the list of ip addresses allowed by the Client to send. It can also occur when you try to send a message from an ip address that was not previously used for sending messages and logging in to your personal account.
245Status is not receivedDuring the day, the delivery status was not received from the recipient's mail server, in this case it is impossible to say for sure whether the message was delivered or not.
248No routeMeans that sending messages to this e-mail address is not available in our service. For example, there is no working e-mail gateway for the specified address and text.
249Invalid format'Occurs when the recipient's e-mail address is entered incorrectly in the format.
252E-mail address is prohibitedOccurs, for example, when the specified e-mail address is found in the blacklist.
253Prohibited spam filterIf the text of the message contains obscene expressions and insults, calls to send sms or e-mail and some other prohibited texts, then sending the message will be blocked. It is also prohibited to indicate as the sender the e-mail address of the recipient of the message, the addresses of other people's Internet resources, companies and government organizations.
254Unregistered senderThis error occurs when trying to send a message from an unregistered e-mail address of the sender.
255Rejected by the recipient serverThe recipient's mail server rejected the message without specifying the exact error code.
This happens, for example, when an internal server error occurs when it cannot process a message.



© 2003Ц2023 SMS Center LLC
License no. 166255
support@smscentre.com
Contacts
Design Ч Artemy Lebedev Studio
Site Information
SMS Center for Android Yandex. Metrica