SMSTeam

SMPP протокол

1. Подключение
2. Отправка сообщения
3. Отправка HLR-запроса
4. Проверка статуса
5. Получение входящих сообщений
6. Коды ошибок в статусе

Подключение

Через наш SMS-шлюз возможно отправлять сообщения по протоколу SMPP версии 3.4.

Для получения доступа по SMPP-протоколу необходимо обратиться в службу поддержки, сообщить IP-адреса, с которых будете выполнять подключение, и порт, который нужно открыть (обычный или SSL).

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

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

Логин и пароль используются от личного кабинета, но они не должны быть на русском языке.

Данный раздел содержит только краткое описание SMPP-протокола. Подробности смотрите в спецификации.

Скачать спецификацию протокола SMPP v3.4 smpp34.zip (500 Кб) smpp34rus.zip (1,1 Mб).

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

Для отправки SMS-сообщения используйте команду SUBMIT_SM согласно спецификации.

Поддерживаются следующие кодировки:

  • 7-битная GSM для латинского текста с поддержкой европейских символов − (coding = 0);
  • 8-битная ISO-8859-1 (ASCII) для латинского текста или бинарных данных − (coding = 1);
  • UCS2 (UTF-16) для текстов в национальных алфавитах (например, на русском) − (coding = 2).

Для использования кодировки ISO-8859-1 (ASCII) вместо GSM при подключении нужно указать:
system-type = "ISO"

Команда SUBMIT_MULTI для множественной рассылки пока не реализована.

Сервер не принимает более одного одинакового запроса на отправку SMS-сообщений в течение минуты для защиты от ошибок и зацикливаний в программе на стороне Клиента для того, чтобы снизить нагрузку и не расходовать средства Клиента, а также не допустить многократной отправки сообщения одному абоненту.

Сервер также блокирует отправку более 50 сообщений одному абоненту, которые были отправлены с перерывом между сообщениями менее 30-ти секунд, для защиты от флуда и лишнего списания средств со счета Клиента, так как многие операторы не пропускают большое количество сообщений одному абоненту за короткий промежуток времени.

Отправка 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, сервер возвращает статус только для первой части склеенного сообщения. Для включения режима возврата статусов для каждой части обратитесь в службу поддержки.

Получение входящих сообщений

Для включения пересылки входящих SMS-сообщений по SMPP-подключению необходимо обратиться в службу поддержки. Данные сообщения приходят в PDU-команде DELIVER_SM. Для получения необходимо подключаться к SMPP-серверу в режиме transceiver или receiver.

Коды ошибок в статусе

Возможные коды ошибок в статусе SMS-сообщений или HLR-запросов (значения <err>):

Значение Описание Подробно
0 Нет ошибки. Абонент существует и доступен.
1 Абонент не существует. Указанный номер телефона не существует.
6 Абонент отсутствует. Телефон абонента отключен или находится вне зоны действия сети.
11 Нет услуги SMS. Означает, что абонент не может принять SMS-сообщение. Например, услуга не подключена, или абонент находится в роуминге, где не активирован прием сообщений, или у оператора абонента не налажен обмен SMS с текущим роуминговым оператором. Также это может быть городской номер без приема сообщений.
13 Абонент заблокирован. Возникает, например, если на счету абонента нулевой или отрицательный баланс, и он находится в роуминге, или заблокирован оператором за продолжительную неуплату либо добровольно самим абонентом. Также данная ошибка может возвращаться при повреждении SIM-карты либо неправильном вводе PIN и PUK-кодов SIM-карты.
21 Нет поддержки SMS. Аппарат абонента не поддерживает прием SMS-сообщений.
247 Превышен лимит сообщений. Превышен общий суточный лимит сообщений, указанный Клиентом в личном кабинете в пункте «Настройки».
248 Неподдерживаемый номер. Означает, что на данный номер отправка сообщений заблокирована в нашем сервисе. Например, ввели несуществующий мобильный код, либо для указанного номера нет рабочего SMS-шлюза.
249 Неверный формат номера. Возникает, когда мобильный код указанного номера и соответствующая этому коду длина номера неверны.
250 Номер запрещен настройками. Номер попал под ограничения, установленные Клиентом для мобильных номеров в личном кабинете в пункте «Настройки».
251 Превышен лимит на один номер. Превышен суточный лимит сообщений на один номер. Лимит устанавливается Клиентом в личном кабинете в пункте «Настройки». Также такая ошибка возможна при отправке более 50 сообщений одному абоненту, которые были отправлены с перерывом между сообщениями менее 2-х минут.
252 Номер запрещен. Возникает, например, при попытке указания Клиентом одного из наших федеральных номеров в качестве получателя SMS-сообщения.
253 Запрещено спам-фильтром. Данная ошибка возникает, например, если текст сообщения содержит нецензурные выражения и оскорбления, призывы отправить sms и некоторые другие запрещенные тексты.
254 Запрещенный sender id. Запрещено указывать в качестве отправителя короткие платные номера, номер получателя сообщений, а также названия операторов, чужих интернет-ресурсов, компаний и государственных организаций. Также данная ошибка возникает при попытке отправки от незарегистрированного имени отправителя.
255 Отклонено оператором. Оператор отклонил сообщение без указания точного кода ошибки.Такое бывает, например, когда номер не принадлежит ни одному мобильному оператору, т.е. с несуществующим кодом, либо по какой-то другой причине оператор не может доставить сообщение.