Содержание
- Подключение
- Отправка сообщения
- Проверка статуса
- Получение входящих сообщений
- Коды ошибок в статусе
Подключение
Через наш SMS-шлюз возможно отправлять сообщения по протоколу SMPP версии 3.4.
Для получения доступа по SMPP-протоколу необходимо включить в настройках в группе "Настройки API"
соответствующую опцию и добавить IP-адреса, с которых будете выполнять подключение, на этой странице.
Адрес SMPP-сервера: smpp.billing.smstraf.ru, порт: 3700.
Для шифрованного SSL-подключения используется порт 3443.
Адрес резервного SMPP-сервера: smpp2.billing.smstraf.ru.
Пример настроек для подключения (формат kannel):
group = smsc
smsc = smpp
smsc-id = smsc
host = smpp.billing.smstraf.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>".
Здесь:
- <message> − текст сообщения;
- <subject> − тема сообщения.
Отправка голосового сообщения (звонок)
Для отправки голосового сообщения используйте команду SUBMIT_SM с текстом "__CALL__: <message>\nvoice:<voice>".
Здесь:
- <message> − текст сообщения;
- <voice> − голос, используемый для озвучивания текста. Возможные значения:
- m (по умолчанию) – мужской голос.
- m2 – мужской альтернативный голос.
- w – женский голос.
- w2 – женский альтернативный голос 1.
- w3 – женский альтернативный голос 2.
- w4 – женский альтернативный голос 3.
При отправке голосового сообщения в конце текста можно указать специальную комбинацию "\n~~~\n" (перевод строки, 3 символа
тильды и снова перевод строки), после которой передать параметр param, определяющий некоторые характеристики звонка
(более подробно можно посмотреть в описании).
Отправка 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-подключению необходимо обратиться в службу поддержки.
Данные сообщения приходят в PDU-команде DELIVER_SM. Для получения необходимо подключаться к SMPP-серверу в режиме
transceiver или receiver.
Коды ошибок в статусе
Возможные коды ошибок в статусе SMS-сообщений или 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 | Отклонено оператором | Оператор отклонил сообщение без указания точного кода ошибки. Такое бывает, например,
когда номер не принадлежит ни одному мобильному оператору, т.е. с несуществующим кодом, либо по какой-то другой причине оператор
не может доставить сообщение.
|
---|
|