Тарифы  Услуги  API  Партнерам  О сервисе  Контакты 
8 (800) 700 7672
Бесплатно по России
 

Интеграция с сервисом (API)

API позволяет рассылать сообщения через ваши проекты и сервисы по протоколам HTTP/HTTPS, SMTP и SMPP. Готовые библиотеки на разных языках программирования подключаются к вашему проекту и помогают отправлять сообщения из любого места с помощью одной команды.


HTTP/HTTPS SMTP SMPP SOAP OMS SMS-команды Библиотеки и примеры кода

SMPP протокол

Подключение

Через наш SMS-шлюз возможно отправлять сообщения по протоколу SMPP версии 3.4.
Для получения доступа по SMPP-протоколу необходимо включить в настройках в группе "Настройки API" соответствующую опцию и добавить IP-адреса, с которых будете выполнять подключение, на этой странице.

Адрес SMPP-сервера: smpp.smsc.ru, порт: 3700.
Для шифрованного SSL-подключения используется порт 3443.

Адрес резервного SMPP-сервера: smpp2.smsc.ru.

Пример настроек для подключения (формат kannel): group = smsc
smsc = smpp
smsc-id = smsc
host = smpp.smsc.ru
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 = 100

При подключении необходимо обратить внимание на частоту отправки пакета ENQUIRE_LINK. Для исключения избыточной нагрузки и защиты от ошибок в ПО клиентов наша система ограничивает отправку данного пакета не чаще, чем раз в 10 секунд, но рекомендуется ставить 30-60 секунд.


Пример дополнительных настроек для подключения по 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-уведомления. Система установит максимальный приоритет таким сообщениям и отправит их раньше любых массовых рассылок без ожидания в очереди.

Множественные подключения

По умолчанию сервер обрабатывает одновременно с одного логина только одно подключение для более корректной отдачи статусов, поэтому при повторном подключении ранее подключенное соединение с таким же логином будет автоматически завершаться. Если же необходимо иметь несколько одновременных подключений для повышения скорости отправки, то можно в настройках всех подключений задать следующий параметр (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-сообщения, предназначенного для отправки, указать специальную комбинацию "\n~~~\n" (перевод строки, 3 символа тильды и снова перевод строки), и после этого любой текст, который будет считаться комментарием, не будет отправлен абоненту, но отобразится в истории.

Отправка MMS-сообщения

Для отправки MMS-сообщения используйте команду SUBMIT_SM с текстом "__MMS__: <message>\nsubj:<subject>" (текст "__MMS__", двоеточие, пробел, текст сообщения, перевод строки, текст "subj", двоеточие, тема MMS-сообщения).

Отправка e-mail сообщения

Для отправки e-mail сообщения используйте команду SUBMIT_SM с текстом "__MAIL__: <message>\nsubj:<subject>" (текст "__MAIL__", двоеточие, пробел, текст сообщения, перевод строки, слово "subj", двоеточие, тема e-mail сообщения).

Отправка голосового сообщения (звонок)

Для отправки голосового сообщения используйте команду SUBMIT_SM с текстом "__CALL__: <message>\nvoice:<voice>" (текст "__CALL__", двоеточие, пробел, текст сообщения, перевод строки, слово "voice", двоеточие, голос, используемый для озвучивания текста).

Возможные значения для используемого голоса:
  • m (по умолчанию) – мужской голос.
  • m2 – мужской альтернативный голос.
  • w – женский голос.
  • w2 – женский альтернативный голос 1.
  • w3 – женский альтернативный голос 2.
  • w4 – женский альтернативный голос 3.
При отправке голосового сообщения в конце текста можно указать специальную комбинацию "\n~~~\n" (перевод строки, 3 символа тильды и снова перевод строки), после которой передать параметр param, определяющий некоторые характеристики звонка (более подробно можно посмотреть в описании).

Отправка viber-сообщения

Для отправки viber-сообщения используйте команду SUBMIT_SM с текстом "__VIBER__: <message>" (текст "__VIBER__", двоеточие, пробел, текст сообщения).

При формировании текста сообщения можно использовать специальные макросы для создания кнопки, при нажатии на которую будет происходить открытие браузера и переход по указанной в макросе ссылке, а также прикреплять файлы. Более подробно дополнительные возможности при отправке viber-сообщений описаны в документации к http-протоколу.

Отправка 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. Для автоматического получения статуса необходимо подключаться в режиме transceiver или receiver и при отправке SMS указать флаг запроса статуса (registered_delivery). Кроме этого, возможно получать статусы на HTTP-обработчик.

При автоматическом возврате статуса в команде DELIVER_SM передаются TLV-параметры receipted_message_id (<id>), message_state (числовой <status>) и network_error_code (<err>), а также передается текст статуса в следующем формате:
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-сообщение. Например, услуга не подключена, или абонент находится в роуминге, где не активирован прием сообщений, или у оператора абонента не налажен обмен SMS с текущим роуминговым оператором. Также это может быть городской номер без приема сообщений.
13Абонент заблокированВозникает, например, если на счету абонента нулевой или отрицательный баланс, и он находится в роуминге, или заблокирован оператором за продолжительную неуплату либо добровольно самим абонентом. Также данная ошибка может возвращаться при повреждении SIM-карты либо неправильном вводе PIN и PUK-кодов SIM-карты.
21Нет поддержки SMSАппарат абонента не поддерживает прием SMS-сообщений.
200Виртуальная отправкаДанное уведомление появляется под статусом сообщения в случае отправки сообщения в режиме тестирования (при установленной в настройках галочке "Режим тестирования (виртуальная отправка без оплаты)").
220Переполнена очередь у оператораУказанная ошибка может возникать в случае, когда абонент недоступен для приема SMS, но сообщения продолжают приходить оператору и происходит переполнение внутренней очереди сообщений для данного абонента. В редких случаях возможно появление ошибки в результате сбоя в сети самого оператора или переполнении общей очереди сообщений. Во всех подобных ситуациях система с определенными интервалами несколько раз пытается отправить указанные сообщения повторно.
240Абонент занятВозникает при передаче голосового сообщения абоненту, если линия занята или абонент отменил вызов.
241Ошибка конвертации звукаПри преобразовании текста или звукового файла в конечный формат для передачи абоненту голосового сообщения произошла ошибка конвертации звука.
242Зафиксирован автоответчикОзначает, что во время отправки голосового сообщения на стороне абонента был зафиксирован автоответчик.
243Не заключен договорВозникает при попытке отправки рассылок рекламного или массового характера без заключенного договора.
244Рассылки запрещеныОзначает, что для данного Клиента запрещена отправка массовых и рекламных рассылок.
245Статус не полученВ течение суток статус доставки не был получен от оператора, в этом случае нельзя точно сказать, было сообщение доставлено или нет.
246Ограничение по времениЕсли в личном кабинете в пункте "Настройки" во вкладке "Лимиты и ограничения" установлено "Время отправки" и галочка "запретить отправку в другое время", то при попытке отправки SMS-сообщений в период времени, отличный от указанного в поле "Время отправки", отправка сообщений будет запрещаться с указанием данной ошибки.
247Превышен лимит сообщенийПревышен общий суточный лимит сообщений, указанный Клиентом в личном кабинете в пункте "Настройки".
248Нет маршрутаОзначает, что на данный номер отправка сообщений недоступна в нашем сервисе. Например, ввели несуществующий мобильный код, либо для указанного номера и текста нет рабочего SMS-шлюза.
249Неверный формат номераВозникает, когда мобильный код указанного номера и соответствующая этому коду длина номера неверны.
250Номер запрещен настройкамиНомер попал под ограничения, установленные Клиентом для мобильных номеров в личном кабинете в пункте "Настройки".
251Превышен лимит на один номерПревышен суточный лимит сообщений на один номер. Лимит устанавливается Клиентом в личном кабинете в пункте "Настройки". Также такая ошибка возможна при отправке более 50 сообщений одному абоненту, которые были отправлены с перерывом между сообщениями менее 30 секунд.
252Номер запрещенВозникает, например, при попытке указания Клиентом одного из наших федеральных номеров в качестве получателя SMS-сообщения.
253Запрещено спам-фильтромЕсли текст сообщения содержит нецензурные выражения и оскорбления, призывы отправить sms и некоторые другие запрещенные тексты, то отправка сообщения заблокируется. Также запрещено указывать в качестве отправителя короткие платные номера, номер получателя сообщений, названия операторов, чужих интернет-ресурсов, компаний и государственных организаций.
254Незарегистрированный sender idДанная ошибка возникает при попытке отправки сообщения от незарегистрированного имени отправителя.
255Отклонено операторомОператор отклонил сообщение без указания точного кода ошибки.
Такое бывает, например, когда номер не принадлежит ни одному мобильному оператору, т.е. с несуществующим кодом, либо по какой-то другой причине оператор не может доставить сообщение.



© 2003–2017 ООО «СМС-центр»
Лицензия № 150145
support@smsc.ru
Контакты
Дизайн — Студия Артемия Лебедева
Информация о сайте