Руководство по эксплуатации: интеграция по протоколу 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. Установка соединения (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 будет передано одно из значений из справочника.
5. Разрыв соединения (UNBIND)
При необходимости разорвать подключение необходимо послать команду UNBIND, в ответ будет передана команда UNBIND_RESP и закрыто TCP-соединение.
6. Поддержание соединения (ENQUIRE_LINK)
Как клиент, так и сервер (платформа Мегафон Хаб) должны регулярно проверять связность между собой посылом команды 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 серверу | Сервер закрывает соединение с клиентом. Клиент восстанавливает соединения самостоятельно. |
7. Отправка сообщений (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 — передать отчет |
8. Получение отчетов о доставке (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 байтом) |
9. Коды ошибок
9.1 BIND_RESP
| Код | Значение | Описание |
|---|---|---|
| 0x00000000 | ESME_ROK | Подключение установлено |
| 0x0000000D | ESME_RBINDFAIL | Соединение не установлено, необходимо повторить попытку |
| 0x00000005 | ESME_RALYBND | Подключение уже установлено |
| 0x0000000F | ESME_RINVSYSID | Неверный system_id |
| 0x0000000E | ESME_RINVPASWD | Неверный password |
9.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 | Превышение установленной для подключения скорости |
9.3 DELIVER_SM_RESP
9.3.1 Стандартные коды ошибок
| Код | Значение | Описание |
|---|---|---|
| 2 | DELIVERED | Сообщение успешно доставлено |
| 3 | EXPIRED | Время жизни сообщения истекло |
| 5 | UNDELIVERED | Сообщение не может быть доставлено |
| 8 | REJECTED | Сообщение отклонено |
9.3.2 Расширенные коды ошибок
| Код | Значение | Описание |
|---|---|---|
| 0 | no_extra_status | В случае успешной доставки |
| 1 | unknown | Неизвестная причина недоставки сообщения |
| 6 | absent-subscriber | Абонент недоступен. Например, из-за уровня сигнала, выключения телефона |
| 8 | unknown-subscriber | Номер телефона не существует (или не обслуживается, не распознан оператором, абонент не зарегистрирован в сети оператор а и т.п.) |
| 11 | sms-unavailable | Сервис коротких сообщений не предоставляется. Например, услуга СМС не подключена или временно заблокирована |
| 12 | subscriber-error | Ошибка в телефоне абонента |
| 13 | call-barred | У абонента включен запрет на прием сообщений или абонент временно заблокирован оператором (например, в связи с отрицательным балансом) |
| 14 | memory_capacity_exceeded | На абонентском устройстве нет свободной памяти, чтобы принять сообщение. |
| 15 | absent-subscriber | Сработала временная частичная блокировка услуг после осуществления владельцем номера сервисных операций (например, смена sim-карты). |
| 16 | failure | Заблокировано спам-фильтром на стороне оператора: при фиксировании аномальной смс-активности (спам-атаки) потерпевшие номера блокируются. Разблокировка таких номеров производится автоматически. |
| 245 | timeout | Время ожидания статуса доставки истекло |
| 252 | filter-destination_addr | Заблокировано спам-фильтром: запрещена отправка SMS на данный номер телефона. |
| 253 | filter-message | Заблокировано спам-фильтром: текст сообщения содержит запрещенные слова. |
| 254 | filter-source_addr | Заблокировано спам-фильтром: запрещена отправка SMS с данного короткого номера. |
| 255 | failure | Внутренняя ошибка оператора. Например, ошибка маршрутизации, ошибка коммутатора (внутренняя ошибка передачи данных) и т.п. |
| 500 | Абонент заблокировал имя отправителя (для мессенджеров) | |
| 501 | У абонента отсутствует приложение для получения сообщения (для мессенджеров) |