Руководство по эксплуатации: интеграция по протоколу SMPP 3.4
- Руководство по эксплуатации: интеграция по протоколу SMPP 3.4
1. Описание протокола
SMPP — (Short Message Peer-to-Peer) короткие сообщения одноранговой Сети.
Протокол SMPP является открытым стандартом, который разработан, чтобы обеспечить интерфейс для передачи коротких сообщений между устройствами, приложениями, СМС-шлюзами и СМС-центрами.
В данной статье для ознакомления доступно два варианта описания протокола — на английском (оригинал) и русском (перевод) языках.
В русскоязычном варианте описания протокола SMPP можно встретить неточности перевода и неверную трактовку некоторых терминов, поэтому рекомендуем использовать только оригинальную версию на английском языке.
2. Ограничения
В рамках взаимодействия с партнерами, протокол SMPP используется по части подключения, обмена, получения, отправки сообщений и поддержания сессий.
Не предусмотрена функциональность, реализующая пакетную отправку, замену и отмену отправленных сообщений.
В данном документе представлены базовые термины, необходимые для запуска сервиса, с полным описанием можно ознакомится непосредственно в спецификации SMPP v3.4.
3. Требования по взаимодействию
| Описание | Значение |
|---|---|
| Версия SMPP | 3.4 |
| Количество сессий по-умолчанию | 1 |
| Количество сессий по-согласованию | до 20 |
| Режим работы подключения по-умолчанию | Transceiver |
| Режим работы подключения по-согласованию | Transmitter, Receiver |
| Интервалы между Enquire_link | 30 секунд |
| Таймаут для переподключения после потери SMPP | не менее 60 секунд |
| data_coding для передачи символов латиницы | 0 |
| data_coding для передачи символов юникод | 8 |
4. Правила сегментации сообщений
При использовании протокола SMPP для правильной сегментации многосоставных сообщений важно соблюдение следующих правил:
- Каждый сегмент должен быть передан отдельным submit_sm
- В каждом submit_sm многосоставных сообщений должен быть задан UDH (User Data Header) — специальный заголовок, который содержит информацию о конкатенации частей: идентификатор части (reference number), общее количество сегментов (total number of parts) и номер текущего сегмента (part's number)
- Использование метода payload запрещено. (Payload — метод, когда весь контент многосоставного сообщения передается в одном submit_sm)
Мы выполняем проверку длины каждого сегмента. Крайне важно верно указать Message length в submit_sm, в противном случае сообщение может быть отклонено и не доставлено до получателя.
Ниже приведена информация по размерности сообщений в зависимости от используемой кодировки.
| encodings | data_coding | Количество символов для сегмента односоставного сообщения | Количество символов для сегмента многосоставного сообщения |
|---|---|---|---|
| 7-bit (ASCII, GSM7bit) | 0x00 | 160 | 153 |
| 8-bit (Binary, Latin-1) | 0x03 | 140 | 134 |
| 16-bit (Unicode/UCS-2) | 0x08 | 70 | 67 |
При выборе data_coding используйте следующие значения:
- 0x00 (ASCII, GSM)
- 0x03 (Latin-1)
- 0x08 (Unicode/UCS-2)
Любые другие варианты будут интерпретироваться как бинарные сообщения.
Следует обратить особое внимание на использование символов "^", "{", "}", "\\", "[", "~", "]", "|", "€" (далее спецсимволы, всего 9 таких символов), которые при передаче в сигнальную сеть оператора кодируются в 2 байта, фактически используют место 2 (двух) обычных символов. При формировании submit_sm необходимо считать каждый такой спецсимвол за два обычных символа.
5. Установка соединения (BIND)
Дл я установки соединения необходимо послать BIND_TRANSCEIVER (или BIND_TRANSMITTER, или BIND_RECEIVER), в команде должны быть следующие поля:
| Параметр | Описание | Пример |
|---|---|---|
| system_id | Идентификатор подключения. Допустимые символы 0...9a...zA...Z_ Максимальная длина 16 символов | client_1 |
| password | Пароль, максимальная длина 9 символов | yh5rC23K |
| system_type | Тип подключения. Необходимо оставить пустым |
Ответ будет передан командой BIND_TRANSCEIVER_RESP (или BIND_TRANSMITTER_RESP, или BIND_RECEIVER_RESP), в поле command_status будет передано одно из значений из справочника.
6. Разрыв соединения (UNBIND)
При необходимости разорвать подключение необходимо послать команду UNBIND, в ответ будет передана команда UNBIND_RESP и закрыто TCP-соединение.
7. Поддержание соединения (ENQUIRE_LINK)
Как клиент, так и сервер (платформа SevenTech) должны регулярно проверять связность между собой посылом команды ENQUIRE_LINK.
Интервал посыла команды ENQUIRE_LINK должен находится в промежутке от 30 до 180 секунд.
Каждая из сторон при получении ENQUIRE_LINK должна ответить ENQUIRE_LINK_RESP в течение 30 секунд.
| Событие | Действие |
|---|---|
| Клиент не получил ENQUIRE_LINK_RESP от сервера | Послать команду UNBIND, получить UNBIND_RESP, после чего, не разрывая TCP-соединение, выждав 60 секунд, установить соединение, послав команду BIND. Если результат не получен, закрыть TCP-соединение и выполнить подключения заново. |
| Клиент не вернул ENQUIRE_LINK_RESP серверу | Сервер закрывает соединение с клиентом. Клиент восстанавливает соединение самостоятельно. |
8. Отправка сообщений (SUBMIT_SM)
Для отправки сообщений абоненту необходимо выполнить команду SUBMIT_SM, используемые параметры:
| Параметр | Описание |
|---|---|
| source_addr | Имя отправителя. Сообщение абоненту будет отправлено с номера, указанного в данном параметре. Допустимая длина 2-11 символов. Допустимые символы: 0...9a...zA...Z!@#$%^&*()/';:,+-_ и пробел. |
| destination_addr | Номер абонента в международном формате. Пример 79031234567 |
| esm_class | Режим работы и тип сообщения |
| data_coding | Тип кодирования сообщения. Рекомендуем использовать 0 для латинских сообщений и 8 для передачи символов юникода. |
| registered_delivery | Флаг для запроса отчета о статусе доставки. 0 — отчет не нужен, 1 — передать отчет |
9. Получение отчетов о доставке (DELIVER_SM)
Отчет о статусе доставки будет передан в пакете DELIVER_SM, в ответ партнер должен передать команду DELIVER_SM_RESP с указанием command_status равном 0, любой другой статус либо задержка в ответе более 30 секунд приведет к повторной отправке DELIVER_SM.
Отчет о доставке будет сформирован только на сообщение, при иницииации которого в пакете SUBMIT_SM был указан запрос на получения статуса (registered_delivery=1).
Используемые параметры DELIVER_SM:
| Параметр | Описание |
|---|---|
| source_addr | Номер абонента в международном формате |
| destination_addr | Сервисный номер |
| esm_class | Режим работы и тип сообщения. Будет использован x x 0 0 0 1 x x |
Используемые TLV-параметры DELIVER_SM:
| Параметр | Код TLV | Тип данных | Размер (октетов) | Описание |
|---|---|---|---|---|
| receipted_message_id | 0x001E | Octet String | 1-65 | Идентификатор сообщения |
| message_state | 0x0427 | Integer | 1 | Статус доставки сообщения абоненту. Значения из справочника |
| network_error_code | 0x0423 | Integer | 3 | Расширенный код ошибки. Значения из справочника |
| message_type | 0x1440 | Octet String | 3, 4 или 6 | Тип сообщения. В случае использования каскада, целевое сообщение может быть доставлено абоненту по каналу, отличного от исходного. Примеры: VIBER, VK, SMS (оканчивается 0x00 байтом) |
10. Коды ошибок
10.1 BIND_RESP
| Код | Значение | Описание |
|---|---|---|
| 0x00000000 | ESME_ROK | Подключение установлено |
| 0x0000000D | ESME_RBINDFAIL | Соединение не установлено, необходимо повторить попытку |
| 0x00000005 | ESME_RALYBND | Подключение уже установлено |
| 0x0000000F | ESME_RINVSYSID | Неверный system_id |
| 0x0000000E | ESME_RINVPASWD | Неверный password |
10.2 SUBMIT_SM_RESP
| Код | Значение | Описание |
|---|---|---|
| 0x00000000 | STATUS_OK | Сообщение принято |
| 0x00000001 | STATUS_INVMSGLEN | Неверная длина сообщения |
| 0x00000003 | STATUS_INVCMDID | Передан неверный набор TLV-параметров |
| 0x00000008 | STATUS_SYSERR | Системная ошибка |
| 0x0000000A | STATUS_INVSRCADR | Запрещена отправка от данного имени отправителя |
| 0x0000000B | STATUS_INVDSTADR | Запрещена отправка сообщений на данный номер |
| 0x00000058 | STATUS_THROTTLED | Превышение установленной для подключения скорости |
| 0x00000104 | ESME_RINVDCS | Выбранная Data coding не поддерживается |
10.3 DELIVER_SM_RESP
10.3.1 Стандартные коды ошибок
| Код | Значение | Описание |
|---|---|---|
| 2 | DELIVERED | Сообщение успешно доставлено |
| 3 | EXPIRED | Время жизни сообщения истекло |
| 5 | UNDELIVERED | Сообщение не может быть доставлено |
| 8 | REJECTED | Сообщение отклонено |
10.3.2 Расширенные коды ошибок
| Код | Значение | Описание |
|---|---|---|
| 0 | no_extra_status | В случае успешной доставки |
| 1 | unknown | Неизвестная причина недоставки сообщения |
| 6 | absent-subscriber | Абонент недоступен. Например, из-за уровня сигнала, выключения телефона |
| 8 | unknown-subscriber | Номер телефона не существует (или не обслуживается, не распознан оператором, абонент не зарегистрирован в сети оператора и т.п.) |
| 11 | sms-unavailable | Сервис коротких сообщений не предоставляется. Например, услуга СМС не подключена или временно заблокирована |
| 12 | subscriber-error | Ошибка в телефоне абонента |
| 13 | call-barred | У абонента включен запрет на прием сообщений или абонент временно заблокирован оператором (например, в связи с отрицательным балансом) |
| 245 | timeout | Время ожидания статуса доставки истекло |
| 252 | filter-destination_addr | Заблокировано спам-фильтром: запрещена отправка SMS на данный номер телефона. |
| 253 | filter-message | Заблокировано спам-фильтром: текст сообщения содержит запрещенные слова. |
| 254 | filter-source_addr | Заблокировано спам-фильтром: запрещена отправка SMS с данного короткого номера. |
| 255 | failure | Внутренняя ошибка оператора. Например, ошибка маршрутизации, ошибка коммутатора (внутренняя ошибка передачи данных) и т.п. |
| 500 | Абонент заблокировал имя отправителя (для мессенджеров) | |
| 501 | У абонента отсутствует приложение для получения сообщения (для мессенджеров) |