| SMPP ProtocolConnectionThrough 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 listsThe 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 connectionsBy 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 messageSending an SMS message
To send an SMS message, use the SUBMIT_SM command according to the specification.
The following encodings are supported:
- 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 to send SMS messages within a minute to protect against errors and loops in the Client-side program in order to reduce the load and not waste the Client's funds, as well as to prevent multiple messages from being sent to one 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 (default) – male voice 3.
- m4 – male voice 4.
- w – a woman's voice.
- w2 – female voice 2.
- w3 – female voice 3.
- w4 – female voice 4.
When sending messages, it is also possible to specify the language of the text in the form: "m,en", "w,fr", "w,de", etc..
In the process of forming a message, at the end of the text, you can specify a special combination "\n~~~\n" (line feed, 3
tilde character and line feed again), after which you pass the param parameter, which determines some characteristics of the call
(more details can be found in the description).Sending a viber message
To send a viber message, use the SUBMIT_SM command with the text "__VIBER__: <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 messageTo 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>" (text " _ _ SOC__", colon, space, message text).
Sending a message to the Telegram chatbot
To send a message to the Telegram chatbot, use the SUBMIT_SM command with the text "__BOT__: <message>\nbot:@<bot_name>" (text "__BOT__", colon, space, message text, line feed, text "bot", colon, bot name).Sending an HLR request
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:
| Option | The value
|
|---|
| id | Message ID.
|
|---|
| status | Message status.
|
|---|
| err | Error code if the subscriber is unavailable (list).
|
|---|
| imsi | Unique IMSI code of the subscriber's SIM card.
|
|---|
| msc | The number of the service center of the operator in whose network the subscriber is located.
|
|---|
| mcc | Numeric code of the subscriber's country.
|
|---|
| mnc | Numeric code of the subscriber's operator.
|
|---|
| cn | Name of the country of registration of the subscriber.
|
|---|
| net | Name of the subscriber registration operator.
|
|---|
| rcn | The name of the roaming country of the subscriber when he is in a foreign network.
|
|---|
| rnet | The 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) | Size | Type | Description
|
|---|
| 8192 (0x2000) | Var. max 6 | COctet String | The cost of the message in the format " n.nnnn".
|
|---|
| 8193 (0x2001) | 2 | Integer | A 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) | 2 | Integer | Number of parts per message.
|
|---|
| 8195 (0x2003) | Var. max 5 | COctet String | mccmnc Subscriber's country/operator code.
|
|---|
| 8196 (0x2004) | 2 | Integer | Additional 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:
| Option | The value
|
|---|
| id | The message ID assigned by the server when sending the message.
|
|---|
| sub | The number of SMS parts in the sent message.
|
|---|
| dlvrd | Number of SMS delivered.
|
|---|
| submit date | Date sent.
|
|---|
| done date | Date of status change.
|
|---|
| status | The status of the message in the form of a string (DELIVRD, EXPIRED, UNDELIV).
|
|---|
| err | Error code if the message cannot be delivered (list).
|
|---|
Example of the result of the status bar (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 statusPossible error codes in the status of messages or HLR requests (values of <err>):
| Code | Name | Description
|
|---|
| 0 | No error | The subscriber exists and is available.
|
|---|
| 1 | The subscriber does not exist | The specified phone number does not exist.
|
|---|
| 6 | Subscriber is offline | The subscriber's phone is disconnected or out of range of the network.
|
|---|
| 11 | The service is not connected | Means 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.
|
|---|
| 12 | Error in the subscriber's phone | The message cannot be delivered to the subscriber due to an error in the phone or SIM card.
|
|---|
| 13 | Subscriber is blocked | Occurs, 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.
|
|---|
| 21 | No support for the service | The subscriber's device does not support this service (service).
|
|---|
| 200 | Virtual sending | This 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
)").
|
|---|
| 219 | SIM Card Replacement | Error 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..
|
|---|
| 220 | Queue overflowed from operator | This 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.
|
|---|
| 224 | Insufficient funds | The Client's account does not have enough money to send the message.
|
|---|
| 237 | The caller is not responding | Occurs if the caller did not pick up the phone during the dial attempt.
|
|---|
| 238 | No template | Occurs if sending a message is possible only according to a certain template, and
the message being sent does not satisfy it.
|
|---|
| 239 | Forbidden ip address | Occurs 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.
|
|---|
| 240 | Subscriber is busy | Occurs when sending a voice message to a subscriber if the line is busy or the subscriber
has canceled the call.
|
|---|
| 241 | Conversion error | An 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.
|
|---|
| 242 | Recorded answering machine | Means that an answering machine was fixed on the subscriber's side when the voice message was sent
.
|
|---|
| 243 | No contract | Occurs when you try to send mailings of an advertising or mass nature without
a signed contract.
|
|---|
| 244 | Mailing is prohibited | It means that the sending of mass and advertising mailings is prohibited for this Client,
or a prohibited link is found in the message text.
|
|---|
| 245 | Status is not received | During 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.
|
|---|
| 246 | Time limit | If the "Sending time" is set in the "Settings" section of the "Limits and Restrictions" tab in your personal account
and the "prohibit sending at another time" checkmark is checked, then when you try to send SMS messages in
a time period other than that specified in the "Sending Time" field, sending messages will be prohibited with this error.
|
|---|
| 247 | Limit exceeded messages | Exceeded the total daily message limit specified by the Client in the personal account
in the "Settings" section".
|
|---|
| 248 | No route | This 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.
|
|---|
| 249 | Invalid number format | Occurs when the mobile code of the specified number and
the number length corresponding to this code are incorrect.
|
|---|
| 250 | Telephone number is forbidden settings | The number fell under the restrictions set by the Client for mobile numbers in
the personal account in the "Settings" section".
|
|---|
| 251 | Limit is exceeded on a single number | Exceeded 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.
|
|---|
| 252 | Number not permitted | Occurs, for example, when a Client tries to specify one of our federal numbers
as the recipient of an SMS message.
|
|---|
| 253 | Prohibited spam filter | If 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.
|
|---|
| 254 | Unregistered sender id | This error occurs when you try to send a message from an unregistered
sender name.
|
|---|
| 255 | Rejected by operator | The 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>):
| Code | Name | Description
|
|---|
| 0 | No error | The recipient exists and is available.
|
|---|
| 1 | Recipient does not exist | The specified e-mail address does not exist.
|
|---|
| 2 | Crowded Inbox | The recipient's mail server rejected the message with the specified error code.
|
|---|
| 3 | Recipient server was not found | The domain specified as the mail server was not found.
|
|---|
| 4 | Mailbox is locked | An error returned from the recipient's mail server stating
that the message could not be delivered due to the mailbox being blocked.
|
|---|
| 239 | Forbidden ip address | Occurs 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.
|
|---|
| 245 | Status is not received | During 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.
|
|---|
| 248 | No route | It means 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.
|
|---|
| 249 | Invalid format' | Occurs when the recipient's e-mail address is entered incorrectly in the format.
|
|---|
| 252 | E-mail address is prohibited | Occurs, for example, when the specified e-mail address is found in the blacklist.
|
|---|
| 253 | Prohibited spam filter | If 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 specify 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.
|
|---|
| 254 | Unregistered sender | This error occurs when trying to send a message from an unregistered
e-mail address of the sender.
|
|---|
| 255 | Rejected by the recipient server | The 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.
|
|---|
|
