| SMPP протоколПодключениеЧерез наш SMS-шлюз возможно отправлять сообщения по протоколу SMPP версий 3.4 и 5.0.
Для получения доступа по SMPP-протоколу необходимо включить в настройках в группе "Настройки API"
соответствующую опцию и добавить IP-адреса, с которых будете выполнять подключение, на этой странице.
Адрес SMPP-сервера: smpp.smsc.kz, порт: 3700.
Для шифрованного SSL-подключения используется порт 3443.
Адрес резервного SMPP-сервера: smpp2.smsc.kz.
Пример настроек для подключения (формат kannel):
group = smsc
smsc = smpp
smsc-id = smsc
host = smpp.smsc.kz
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
Максимально возможный интервал бездействия составляет 2 минуты. В течение этого времени Клиенту необходимо отправить сообщение или выполнить пустую команду ENQUIRE_LINK, иначе соединение будет разорвано из-за не активности.
Пример дополнительных настроек для подключения по SSL-протоколу (kannel версии 1.4.4 и выше):
...
port = 3443
ssl-client-certkey-file = "/etc/kannel.pem"
use-ssl = 1
...
Сертификат можно сгенерировать командой (Linux CentOS): /etc/ssl/certs/make-dummy-cert kannel.pem
Логин используется от личного кабинета, пароль должен быть создан на странице Пароли для доступа. Логин и пароль не должны быть на русском языке.
Данный раздел содержит только краткое описание SMPP-протокола. Подробности смотрите в спецификации.
Скачать спецификацию протокола SMPP v3.4 smpp34.zip (500 Кб)
smpp34rus.zip (1,1 Mб).Скорость рассылокПропускная способность подключения или количество отправляемых каждую секунду SMS-сообщений зависит от размера окна передачи (smpp window size).
В примере настроек данный параметр называется max-pending-submits. Для массовых рассылок лучше задавать большие значения (1000-2000).
Также в примере параметр throughput задает ограничение на максимальное количество SMS-сообщений в секунду.
Вместе с массовыми рассылками через одно подключение можно отправлять и срочные одиночные SMS-уведомления. Система установит максимальный приоритет
таким сообщениям и отправит их раньше любых массовых рассылок без ожидания в очереди.
При массовой отправке сообщений не стоит забывать о системе контроля скорости отправки сообщений в секунду, при превышении которой происходит генерация ошибки превышения скорости (throttling). В случае получения данной ошибки Клиенту по SMPP-стандарту необходимо повторить отправку, снизив общую скорость на своей стороне. По умолчанию скорость задана 30 SMS/cек для каждого аккаунта. Для изменения максимально разрешенной скорости необходимо отправить запрос в службу поддержки сервиса.Множественные подключенияПо умолчанию сервер обрабатывает одновременно с одного логина только одно подключение для более корректной отдачи статусов,
поэтому при повторном подключении ранее подключенное соединение с таким же логином будет автоматически завершаться.
Если же необходимо иметь несколько одновременных подключений для повышения скорости отправки, то можно в настройках
всех подключений задать следующий параметр (multi connection):
system-type = "MCON2"
или
system-type = "MCON9"
Значение после MCON может быть от 1 до 9 и задает количество одновременных подключений.
Также возможны одновременные подключения с разными логинами, привязанными к одному личному кабинету и счету.
Для этого необходимо создать в личном кабинете в разделе "Реселлер" дополнительные аккаунты с необходимым типом субаккаунта.Отправка сообщенияОтправка SMS-сообщения
Для отправки SMS-сообщения используйте команду SUBMIT_SM согласно спецификации.
Поддерживаются следующие кодировки:
- 7-битная GSM для латинского текста с поддержкой европейских символов − (coding = 0);
- 8-битная ISO-8859-1 (ASCII) для латинского текста или бинарных данных − (coding = 1);
- UCS2 (UCS-2BE или UTF-16BE) для национальных алфавитов (например, русского) − (coding = 2).
Поле coding кодируется двумя битами в составном поле data_coding, поэтому data_coding = coding * 4.
Для использования кодировки ISO-8859-1 (ASCII) вместо GSM при подключении нужно указать:
system-type = "ISO"
В текст SMS-сообщения можно добавлять комментарии, предназначенные для просмотра
отправителем истории сообщений в личном кабинете.
Команда SUBMIT_MULTI для множественной рассылки пока не реализована.
Сервер не принимает более одного одинакового запроса на отправку SMS-сообщений в течение минуты
для защиты от ошибок и зацикливаний в программе на стороне Клиента для того, чтобы снизить нагрузку и не
расходовать средства Клиента, а также не допустить многократной отправки сообщения одному абоненту.
Сервер также блокирует отправку более 50 сообщений одному абоненту, которые были отправлены с перерывом
между сообщениями менее 30-ти секунд, для защиты от флуда и лишнего списания средств со счета Клиента,
так как многие операторы не пропускают большое количество сообщений одному абоненту за короткий промежуток времени.
При отправке составного сообщения все SMS-части должны быть переданы на сервер в течение минуты. В противном случае
оператор может отклонить сообщение, так как для проверки на фильтры и шаблоны все SMS-части предварительно необходимо
склеить, и большинство операторов ожидает не более минуты.
Комментарии в SMS-сообщениях
При отправке SMS-сообщений можно добавлять в конец текста любой комментарий, уточняющий либо дополняющий SMS-сообщение для отправителя.
Данный текст не будет отправляться абонентам и влиять на стоимость SMS и доступен для просмотра и фильтрации в списке отправленных сообщений в личном кабинете.
Для добавления комментария необходимо в конце текста SMS-сообщения, предназначенного для отправки, указать специальную комбинацию "\n~~~\n"
(перевод строки, 3 символа тильды и снова перевод строки), и после этого любой текст, который будет считаться комментарием, не будет отправлен абоненту,
но отобразится в истории.Отправка e-mail сообщения
Для отправки e-mail сообщения используйте команду SUBMIT_SM с текстом "__MAIL__: <message>\nsubj:<subject>" (текст "__MAIL__", двоеточие, пробел, текст сообщения, перевод строки, слово "subj", двоеточие, тема e-mail сообщения).Отправка голосового сообщения (звонок)
Для отправки голосового сообщения используйте команду SUBMIT_SM с текстом "__CALL__: <message>\nvoice:<voice>" (текст "__CALL__", двоеточие, пробел, текст сообщения, перевод строки, слово "voice", двоеточие, голос, используемый для озвучивания текста).
Возможные значения для используемого голоса:
- m – мужской голос.
- m2 – мужской голос 2.
- m3 (по умолчанию) – мужской голос 3.
- m4 – мужской голос 4.
- w – женский голос.
- w2 – женский голос 2.
- w3 – женский голос 3.
- w4 – женский голос 4.
При отправке сообщений также возможно указание языка озвучивания текста в виде: "m,en", "w,fr", "w,de" и т.п.
В процессе формирования сообщения в конце текста можно указать специальную комбинацию "\n~~~\n" (перевод строки, 3 символа
тильды и снова перевод строки), после которой передать параметр param, определяющий некоторые характеристики звонка
(более подробно можно посмотреть в описании).Отправка viber-сообщения
Для отправки viber-сообщения используйте команду SUBMIT_SM с текстом "__VIBER__: <message>" (текст "__VIBER__", двоеточие, пробел, текст сообщения).
При формировании текста сообщения можно использовать специальные макросы для создания кнопки, при нажатии на которую будет происходить открытие браузера и переход по указанной в макросе ссылке, а также прикреплять файлы. Более подробно
дополнительные возможности при отправке viber-сообщений описаны в документации к http-протоколу.Отправка soc-сообщенияДля отправки soc-сообщения, отправляемого пользователям социальных сетей "Одноклассники", "ВКонтакте" или пользователям "Mail.Ru Агент", используйте команду SUBMIT_SM с текстом "__SOC__: <message>" (текст "__SOC__", двоеточие, пробел, текст сообщения).
Отправка сообщения в TelegramДля отправки кода подтверждения в Telegram используйте команду SUBMIT_SM с текстом "__TGM__: <code>" (текст "__TGM__", двоеточие, пробел, код подтверждения).
К отправке принимаются только числовые коды длиной от 4 до 8 цифр.Отправка сообщения в чат-бот Telegram
Для отправки сообщения в чат-бот Telegram используйте команду SUBMIT_SM с текстом "__BOT__: <message>\nbot:@<bot_name>" (текст "__BOT__", двоеточие, пробел, текст сообщения, перевод строки, текст "bot", двоеточие, имя бота).Отправка сообщения в Whatsapp
Для отправки сообщения в Whatsapp используйте команду SUBMIT_SM с текстом "__BOT__: <message>\nbot:<wa:botnumber>" (текст "__BOT__", двоеточие, пробел, текст сообщения, перевод строки, текст "bot", двоеточие, wa, двоеточие, номер бота).Отправка HLR-запроса
Для отправки HLR-запроса используйте команду SUBMIT_SM с текстом __HLR__.
Результат запроса приходит в обычном статусе (Delivery Report), который можно получить
как по SMPP-подключению, так и по HTTP на свой обработчик.
Формат статуса с результатом HLR-запроса, возвращаемого по SMPP:
id:<id> stat:<status> err:<err> imsi:<imsi> msc:<msc> mcc:<mcc> mnc:<mnc> cn:<cn> net:<net> rcn:<rcn> rnet:<rnet>
Описание параметров:
| Параметр | Значение
|
|---|
| id | Идентификатор сообщения.
|
|---|
| status | Статус сообщения.
|
|---|
| err | Код ошибки, если абонент недоступен (список).
|
|---|
| imsi | Уникальный код IMSI SIM-карты абонента.
|
|---|
| msc | Номер сервис-центра оператора, в сети которого находится абонент.
|
|---|
| mcc | Числовой код страны абонента.
|
|---|
| mnc | Числовой код оператора абонента.
|
|---|
| cn | Название страны регистрации абонента.
|
|---|
| net | Название оператора регистрации абонента.
|
|---|
| rcn | Название роуминговой страны абонента при нахождении в чужой сети.
|
|---|
| rnet | Название роумингового оператора абонента при нахождении в чужой сети.
|
|---|
Строковые данные, например, страна и оператор, закодированы через функцию urlencode.
Пример результата HLR-запроса:
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:
Пример кода на PHP для разбора строки с результатом HLR-запроса:
$dlr = strtr($dlr, ": ", "=&"); // $dlr - строка статуса
parse_str($dlr, $m); // $m - массив параметров, $m["id"], $m["err"], $m["imsi"] и тд.
Пример разбора через регулярные выражения:
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 и тд.
Для отправки Ping-SMS используйте команду SUBMIT_SM с текстом __PING__.Проверка статуса
Получать статус доставки отправленного SMS-сообщения по SMPP-протоколу можно как в автоматическом режиме,
получая от сервера ответную PDU-команду DELIVER_SM сразу после изменения статуса, так и по запросу
отдельной командой QUERY_SM. Для автоматического получения статуса по SMPP-протоколу необходимо подключаться в режиме
transceiver или receiver и при отправке SMS указывать флаг запроса статуса (registered_delivery).
Если при отправке не указывать данный флаг, то статусы сообщений будут передаваться на HTTP-обработчик.
При автоматическом возврате статуса в команде DELIVER_SM передаются стандартные TLV-параметры receipted_message_id (<id>), message_state (числовой <status>) и network_error_code (<err>), а также дополнительные TLV-поля, описанные ниже:
| Имя (код) поля | Размер | Тип | Описание
|
|---|
| 8192 (0x2000) | Var. max 6 | COctet String | Стоимость сообщения в формате "n.nnnn".
|
|---|
| 8193 (0x2001) | 2 | Integer | Флаг в виде 2-х байтового числа, содержащий различную информацию о сообщении. Возможны комбинации значений битов разных характеристик.
Биты 0-3 (тип сообщения):
0 (по умолчанию) – SMS.
1 – Flash-SMS.
2 – Бинарное SMS.
3 – Wap-push.
4 – HLR-запрос.
5 – Ping-SMS.
6 – MMS.
7 – Звонок.
8 – E-mail.
10 – Viber.
12 – Соцсети.
Бит 5 – оплата сообщения со второго баланса.
Бит 8 – признак шаблонного сообщения.
Биты 10,9 – тип шаблонного сообщения:
00 - сервисное.
01 - транзакционное.
10 - авторизационное.
11 - рекламное.
|
|---|
| 8194 (0x2002) | 2 | Integer | Количество частей в сообщении.
|
|---|
| 8195 (0x2003) | Var. max 5 | COctet String | mccmnc код страны/оператора абонента.
|
|---|
| 8196 (0x2004) | 2 | Integer | Дополнительный статус сообщения (2 – прочитано, 4 – нажата ссылка).
|
|---|
Также в команде DELIVER_SM передается текст статуса в следующем формате:
id:<id> sub:<sub> dlvrd:<dlvrd> submit date:<submit date> done date:<done date> stat:<status> err:<err>
Описание параметров:
| Параметр | Значение
|
|---|
| id | Идентификатор сообщения, назначенный сервером при отправке.
|
|---|
| sub | Количество SMS частей в отправленном сообщении.
|
|---|
| dlvrd | Количество доставленных SMS.
|
|---|
| submit date | Дата отправки.
|
|---|
| done date | Дата изменения статуса.
|
|---|
| status | Статус сообщения в виде строки (DELIVRD, EXPIRED, UNDELIV).
|
|---|
| err | Код ошибки, если сообщение не может быть доставлено (список).
|
|---|
Пример результата строки статуса (Delivery Report):
id:854019 sub:001 dlvrd:001 submit date:1108202241 done date:1108202241 stat:DELIVRD err:000
По умолчанию для длинных сообщений, разбиваемых на несколько SMS, сервер возвращает только один статус (DELIVER_SM)
для всего склеенного сообщения и одинаковые ID в ответе SUBMIT_SM_RESP для всех SMS-частей данного сообщения.
Для включения режима обработки и возврата статусов для каждой SMS-части отдельно установите следующий параметр в настройках подключения (либо в настройках личного кабинета):
system-type = "SINGLE"
Если необходимо указать несколько параметров в поле system-type, то укажите их через запятую:
system-type = "ISO,SINGLE"
Получение входящих сообщений
Для включения пересылки входящих SMS-сообщений по SMPP-подключению необходимо установить галочку "Передавать входящие SMS по SMPP-подключению" в настройках личного кабинета (раскрывающаяся вкладка "Настройки API") либо обратиться в службу поддержки. При этом передача входящих сообщений на обработчик Клиента должна быть отключена.
Входящие сообщения приходят в PDU-команде DELIVER_SM. Для получения необходимо подключаться к SMPP-серверу в режиме transceiver или receiver.Коды ошибок в статусеВозможные коды ошибок в статусе сообщений или HLR-запросов (значения <err>):
| Код | Название | Описание
|
|---|
| 0 | Нет ошибки | Абонент существует и доступен.
|
|---|
| 1 | Абонент не существует | Указанный номер телефона не существует.
|
|---|
| 6 | Абонент не в сети | Телефон абонента отключен или находится вне зоны действия сети.
|
|---|
| 11 | Не подключена услуга | Означает, что абонент не может принять SMS-сообщение. Например, услуга не подключена,
или абонент находится в роуминге, где не активирован прием сообщений, или у оператора абонента не налажен обмен SMS с
текущим роуминговым оператором. Также это может быть городской номер без приема сообщений.
|
|---|
| 12 | Ошибка в телефоне абонента | Не удается доставить сообщение абоненту из-за ошибки в телефонном аппарате или SIM-карте.
|
|---|
| 13 | Абонент заблокирован | Возникает, например, если на счету абонента нулевой или отрицательный баланс, и
он находится в роуминге, или заблокирован оператором за продолжительную неуплату либо добровольно самим абонентом. Также
данная ошибка может возвращаться при повреждении SIM-карты либо неправильном вводе PIN и PUK-кодов SIM-карты.
|
|---|
| 21 | Нет поддержки сервиса | Аппарат абонента не поддерживает работу с данной услугой (сервисом).
|
|---|
| 200 | Виртуальная отправка | Данное уведомление появляется под статусом сообщения в случае отправки
сообщения в режиме тестирования (при установленной в настройках галочке "Режим тестирования (виртуальная отправка без
оплаты)").
|
|---|
| 219 | Замена sim-карты | Ошибка отправки сообщения в связи с заменой абонентом sim-карты. После физической замены sim-карты абоненту заблокирован прием сообщений от буквенных имен отправителей на 24 часа. Блокировка может быть снята путем пополнения баланса на 100 рублей.
|
|---|
| 220 | Переполнена очередь у оператора | Указанная ошибка может возникать в случае, когда абонент недоступен
для приема SMS, но сообщения продолжают приходить оператору и происходит переполнение внутренней очереди сообщений
для данного абонента. В редких случаях возможно появление ошибки в результате сбоя в сети самого оператора или переполнении
общей очереди сообщений. Во всех подобных ситуациях система с определенными интервалами несколько раз пытается отправить
указанные сообщения повторно.
|
|---|
| 224 | Недостаточно средств | На счете Клиента недостаточная сумма для отправки сообщения.
|
|---|
| 237 | Абонент не отвечает | Возникает, если в процессе попытки дозвона абонент не взял трубку.
|
|---|
| 238 | Нет шаблона | Возникает, если отправка сообщения возможна только по определенному шаблону, а отправляемое
сообщение ему не удовлетворяет.
|
|---|
| 239 | Запрещенный ip-адрес | Возникает при попытке отправки сообщения с ip-адреса, не входящего в список ip-адресов,
разрешенных Клиентом для отправки. Также может возникать при попытке отправки сообщения с ip-адреса, ранее не используемого
для отправки сообщений и входов в личный кабинет.
|
|---|
| 240 | Абонент занят | Возникает при передаче голосового сообщения абоненту, если линия занята или абонент
отменил вызов.
|
|---|
| 241 | Ошибка конвертации | При преобразовании текста или звукового файла в конечный формат для передачи
абоненту голосового сообщения произошла ошибка конвертации звука. Также данная ошибка может возникать при передаче
SMS-сообщения отдельными частями, когда оператору переданы не все части.
|
|---|
| 242 | Зафиксирован автоответчик | Означает, что во время отправки голосового сообщения на стороне абонента был
зафиксирован автоответчик.
|
|---|
| 243 | Не заключен договор | Возникает при попытке отправки рассылок рекламного или массового характера без
заключенного договора.
|
|---|
| 244 | Рассылка запрещена | Означает, что для данного Клиента запрещена отправка массовых и рекламных рассылок,
либо в тексте сообщения встретилась запрещенная ссылка.
|
|---|
| 245 | Статус не получен | В течение суток статус доставки не был получен от оператора, в этом
случае нельзя точно сказать, было сообщение доставлено или нет.
|
|---|
| 246 | Ограничение по времени | Если в личном кабинете в пункте "Настройки" во вкладке "Лимиты и ограничения"
установлено "Время отправки" и галочка "запретить отправку в другое время", то при попытке отправки SMS-сообщений в период
времени, отличный от указанного в поле "Время отправки", отправка сообщений будет запрещаться с указанием данной ошибки.
|
|---|
| 247 | Превышен лимит сообщений | Превышен общий суточный лимит сообщений, указанный Клиентом в личном кабинете
в пункте "Настройки".
|
|---|
| 248 | Нет маршрута | Означает, что на данный номер отправка сообщений недоступна в нашем сервисе.
Например, ввели несуществующий мобильный код, либо для указанного номера и текста нет рабочего SMS-шлюза.
|
|---|
| 249 | Неверный формат номера | Возникает, когда мобильный код указанного номера и соответствующая этому коду
длина номера неверны.
|
|---|
| 250 | Номер запрещен настройками | Номер попал под ограничения, установленные Клиентом для мобильных номеров в
личном кабинете в пункте "Настройки".
|
|---|
| 251 | Превышен лимит на один номер | Превышен суточный лимит сообщений на один номер. Лимит устанавливается
Клиентом в личном кабинете в пункте "Настройки". Также такая ошибка возможна при отправке более 50 сообщений одному абоненту,
которые были отправлены с перерывом между сообщениями менее 30 секунд.
|
|---|
| 252 | Номер запрещен | Возникает, например, при попытке указания Клиентом одного из наших федеральных номеров в
качестве получателя SMS-сообщения.
|
|---|
| 253 | Запрещено спам-фильтром | Если текст сообщения содержит нецензурные выражения и оскорбления, призывы отправить
sms и некоторые другие запрещенные тексты, то отправка сообщения заблокируется. Также запрещено указывать в качестве
отправителя короткие платные номера, номер получателя сообщений, названия операторов, чужих интернет-ресурсов, компаний и
государственных организаций.
|
|---|
| 254 | Незарегистрированный sender id | Данная ошибка возникает при попытке отправки сообщения от незарегистрированного
имени отправителя.
|
|---|
| 255 | Отклонено оператором | Оператор отклонил сообщение без указания точного кода ошибки.
Такое бывает, например,
когда номер не принадлежит ни одному мобильному оператору, т.е. с несуществующим кодом, либо по какой-то другой причине оператор
не может доставить сообщение.
|
|---|
Возможные коды ошибок в статусе e-mail сообщений (значения <err>):
| Код | Название | Описание
|
|---|
| 0 | Нет ошибки | Получатель существует и доступен.
|
|---|
| 1 | Адресат не существует | Указанный e-mail адрес не существует.
|
|---|
| 2 | Переполнен почтовый ящик | Почтовый сервер получателя отклонил сообщение с указанным кодом ошибки.
|
|---|
| 3 | Сервер получателя не найден | Домен, указанный в качестве почтового сервера, не найден.
|
|---|
| 4 | Почтовый ящик заблокирован | От почтового сервера получателя вернулась ошибка о невозможности доставки
сообщения по причине блокировки ящика.
|
|---|
| 239 | Запрещенный ip-адрес | Возникает при попытке отправки сообщения с ip-адреса, не входящего в список ip-адресов,
разрешенных Клиентом для отправки. Также может возникать при попытке отправки сообщения с ip-адреса, ранее не используемого
для отправки сообщений и входов в личный кабинет.
|
|---|
| 245 | Статус не получен | В течение суток статус доставки не был получен от почтового сервера получателя, в этом
случае нельзя точно сказать, было сообщение доставлено или нет.
|
|---|
| 248 | Нет маршрута | Означает, что на данный e-mail адрес отправка сообщений недоступна в нашем сервисе.
Например, для указанного адреса и текста нет рабочего e-mail шлюза.
|
|---|
| 249 | Неверный формат адреса | Возникает, когда ввели некорректный по формату e-mail адрес получателя.
|
|---|
| 252 | E-mail адрес запрещен | Возникает, например, при нахождении указанного e-mail адреса в черном списке.
|
|---|
| 253 | Запрещено спам-фильтром | Если текст сообщения содержит нецензурные выражения и оскорбления, призывы отправить
sms или e-mail и некоторые другие запрещенные тексты, то отправка сообщения заблокируется. Также запрещено указывать в качестве
отправителя e-mail адрес получателя сообщения, адреса чужих интернет-ресурсов, компаний и государственных организаций.
|
|---|
| 254 | Незарегистрированный отправитель | Данная ошибка возникает при попытке отправки сообщения от незарегистрированного
e-mail адреса отправителя.
|
|---|
| 255 | Отклонено сервером получателя | Почтовый сервер получателя отклонил сообщение без указания точного кода ошибки.
Такое бывает, например,
при возникновении внутренней ошибки сервера, когда он не может обработать сообщение.
|
|---|
|
