SMS SMPP

SMPP (Short Message Peer-to-Peer) — протокол связи для отправки и получения коротких сообщений в пиринговых сетях. SMPP-протокол обеспечивает постоянное подключение, соединение с SMS-сервером не разрывается, что дает возможность рассылать и получать SMS с высокой скоростью (выше чем, при других способах, например через SMS REST API).

Exolve предоставляет учётные данные пользователям для подключения к SMPP-протоколу. Информацию о том, где найти данные для подключения, процесс подключения, как отправить и принять SMS, вы можете найти в следующих статьях:

Решения, где используется SMS SMPP

Попробовать бесплатно

Глоссарий

В статьях раздела SMS SMPP мы будем использовать следующие термины:

ESME (External Short Messaging Entity) — внешняя служба коротких сообщений. Это внешнее приложение, которое подключается к Центру обслуживания коротких сообщений (SMSC) для отправки или получения SMS-сообщений,

PDU (Protocol Data Unit) — пакет данных протокола. SMPP-протокол основан на обмене пар запрос-ответ PDU на 4м уровне OSI (TCP сессии или X25 SVC3),

SMSC (Short Message Service Center) — центр обслуживания коротких сообщений. Отвечает за хранение, передачу, конвертацию и доставку SMS-сообщений,

TLV (Tag-Length-Value) — формат представления данных, используется для передачи дополнительных параметров, настроек и метаданных в сообщениях. Обеспечивает гибкость и расширяемость передачи разнообразной информации в SMS. Каждый объект состоит из трех полей:

  • Tag (метка) указывает на тип данных или параметра (обязательно)
  • Length (длина) обозначает длину значения данных в байтах (обязательно)
  • Value (значение) представляет собой фактические данные или параметры, связанные с этой меткой (опционально)

UDH (User Data Header) — заголовок пользовательских данных. Это двоичная последовательность, которая может присутствовать в начале SMS-сообщения, чтобы указать, как должно обрабатываться сообщение.

Параметры подключения

Вы можете отправлять/получать SMS-сообщения через SMPP-протокол, и получать информацию о статусе отправки/получения, используя систему Exolve.

Exolve поддерживает версию SMPP-протокола 3.4.

Параметр Описание/Значение
system_id логин для подключения
password пароль для подключения
адрес smpp.exolve.ru
порт 2775

Логин и пароль для подключения вы можете найти в Личном кабинете разработчика:

  1. Перейдите во вкладку “Приложения” в верхнем меню аккаунта.
  2. Нажмите на приложение, данные SMPP-аккаунта которого хотите посмотреть.
  3. Выберите вкладу “Сообщения” → “SMPP-аккаунт” в левом меню.

На открывшейся странице вы увидите логин, пароль и домен для подключения.

Подключение

Поддерживаемые команды

Команда Описание Комментарий
bind_transceiver подключение ESME к SMSC в режиме передачи сообщений используйте эту команду для отправки сообщений от SMSC к ESME, и для приема отчетов о доставке сообщений
bind_receiver (получатель) подключение ESME к SMSC в режиме приема сообщений используйте эту команду только для приема сообщений от SMSC к ESME
enquire_link проверка соединения с SMSC для поддержки соединения, выполняйте эту команду с периодичностью менее 15 мин, иначе уведомления о доставке перестанут приходить, в связи с тем, что соединение с ESME разорвано
submit_sm отправка сообщения используйте эту команду для отправки сообщения
deliver_sm отчет о доставке/отправка входящего сообщения
unbind отключение от SMSC используйте эту команду для отключения ESME от SMSC

Подключение

При запуске сессии командой bind_transceiver или bind_receiver установите в PDU следующие параметры:

Параметр Описание/Значение
system_id логин для подключения
password пароль для подключения

Подробнее о команде bind_* вы можете прочитать в спецификации SMPP-протокола 3.4 в разделе 4.1 (стр 45).

Статус подключения

При попытке подключения отправляется ответ о статусе подключения в PDU bind_transceiver_resp или bind_receiver_resp, в зависимости от режима подключения. Статус подключения будет передан в поле command_status.

Ответ при успешном подключении

PDU Hex значение command_status Decimal значение command_status Описание
bind_transceiver_resp 0x00000000 0 ошибок при подключении в режиме приема и передачи сообщений нет
bind_receiver_resp 0x00000000 0 ошибок при подключении в режиме приема сообщений нет

Ответ при неуспешном подключении

PDU Hex значение command_status Decimal значение command_status Описание
bind_transceiver_resp 0x0000000d 13 подключение в режиме приема и передачи сообщений не удалось
bind_receiver_resp 0x0000000d 13 подключении в режиме приема сообщений не удалось

Все статусы неудачных подключений вы можете найти в спецификации SMPP-протокола 3.4 в разделе 5.1.3 (стр 112).

Отправка/получение сообщений

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

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

При отправке сообщения командой submit_sm установите в PDU следующие параметры:

Команда Описание/Значение
source_addr номер отправителя
destination_addr номер получателя
short_message/payload текст сообщения
source_addr_ton тип номера для исходящих сообщений. Установите значение “1” для DEF номеров
dest_addr_npi тип номера для входящий сообщений. Установите значение “1” для DEF номеров
registered_delivery индикатор запроса уведомлений. Установите значение “1”, если вам необходимо получать уведомления о доставке в SMSC
data_coding кодировка текста (0x00 - GSM7; 0x03 - Latin1; 0x06 - ISO88595; 0x08 - UCS2)

Подробнее о команде submit_sm и дополнительных параметрах вы можете прочитать в спецификации SMPP-протокола 3.4 в разделе 4.4 (стр 58).

Способы передачи текста сообщения

SMPP-сервер поддерживает два способа передачи сообщений: “short_message” и “payload”. Используйте только один из этих параметров при отправке сообщения. Требования по отправке сообщений через каждый параметр вы можете найти в статье “Требования к отправке сообщения”.

Отправка шаблонных сообщений

По SMPP можно отправить персонализированные сервисные, авторизационные или транзакционные SMS от индивидуального имени. Для этого зарегистрируйте имя и шаблонный текст сообщения у нужных операторов. Подробнее о шаблонах можно узнать в этой статье.

Для отправки такого SMS укажите идентификатор согласованного шаблона в опциональном поле формата TLV. На скриншоте ниже Tag TagTemplateResourceId со свободным TagID «0x0110» (8 байт, uint64) находится в Options.

SMPP template SMS

Получить ID шаблона можно с помощью API-запроса GetTemplates или в Личном кабинете в разделе «Каналы» → «SMS» → «Шаблоны».

Отчет о доставке сообщения

На каждое отправленное сообщение в подключении transceiver приходит отчет о доставке. Отчёт о доставке отправляется в PDU “deliver_sm”. Отчёт о доставке сообщения будет иметь поле esm_class со значением 0x04 (Hex).

На каждый полученный от SMSC PDU deliver_sm ESME должно отправить подтверждение о получении deliver_sm_resp со статусом 0 (OK).

В поле short_message будет передана информация отчета, со следующими полями:

Параметр Описание/Значение
id идентификатор сообщения, который был указан в запросе на отправку сообщения
sub код состояния подписки
dlvrd количество успешно доставленных сообщений
submit date дата и время запроса на отправку сообщения
done date дата и время отправки сообщения
stat код состояния доставки. Описание кодов вы можете найти в спецификации SMPP-протокола 3.4 в разделе Appendix B (стр 168)
err код ошибки, если доставка не удалась
text первые 10 символов сообщения

Пример отчета о доставке

{
    "esm_class":4,
    "short_message":
        {
            "message": "id:456846948280827906 sub:001 dlvrd:001 submit date:2304181526 done date:2304181526 stat:DELIVRD err:0 text:Hello! How"
        }
}

Получение сообщения

Так же как и отчет о доставке сообщения, входящее сообщение отправляется в PDU “deliver_sm”. Входящее сообщение будет иметь поле esm_class со значением 0x00 (Hex).

Пример отчета о входящем сообщении

{
    "esm_class":0,
    "short_message":
        {
            "message":"I'm fine!"
        }
}

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

Если сообщение не отправилось, SMSC может передать код ответа в PDU submit_sm_resp или в PDU deliver_sm в виде отчёта о доставке. Даже если сообщение принято к отправке, доставка SMS не гарантирована.

Типичные коды ошибок в submit_sm_resp

Коды ошибок передаются в поле command_status.

Код Hex значение Decimal значение Описание
ESME_ROK 0x00000000 0 успешная отправка сообщения
ESME_RINVMSGLEN 0x00000001 1 превышена длинна сообщения
ESME_RINVSRCADR 0x0000000A 10 ошибка в номере, с которого отправляется сообщение
ESME_RINVDSTADR 0x0000000B 11 ошибка в номере, на который отправляется сообщение
ESME_RSUBMITFAIL 0x00000045 69 техническая ошибка

Больше статусов неудачных отправок сообщений вы можете найти в спецификации SMPP-протокола 3.4 в разделе 5.1.3 (стр 112).

Коды ошибок в отчетах о доставке deliver_sm

Коды ошибок передаются в short_message в поле err.

Код ошибки Описание/Значение
0 сообщение доставлено успешно
301 ошибка при оплате
401 недостаточно средств на счету
501 ошибка отправки сообщения
601 ошибка доставки сообщения

Требования для отправки сообщения

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

  1. Протокол взаимодействия с SMSC — SMPP-протокол 3.4.

  2. Максимальное количество сегментов в одном сообщении — 10.

  3. Для обмена сообщениями между ESME и SMSC могут использоваться следующие типы подключения: receiver, transceiver — в зависимости от направления трафика. Подключение transmitter пока недоступно.

  4. При отправке сообщения обязательно нужно передавать параметр data_coding, с помощью которого вы указываете в какой кодировке было передано сообщение. Поддерживаемые кодировки: GSM7, UCS2, ISO88595, Latin1. Рекомендуется использовать GSM7 для латинского алфавита и UCS2, если в сообщении содержится кириллица.

  5. ESME должно отправлять PDU enquire_link каждые 15 минут вне зависимости от наличия или отсутствия трафика в SMPP-соединении. Если в течении 15 минут не было отправлено ни одного сообщения со стороны пользователя или ESME (в том числе enquire_link), то соединение будет разорвано.

  6. Чтобы отслеживать правильность взаимодействия SMSC и ESME по протоколам TCP и SMPP, мы рекомендуем использовать протокольный анализатор — Wireshark.

Если возникнут проблемы в работе сервиса, просим вас провести анализ SMPP-трафика с нашим сервером и сгенерировать с помощью Wireshark файл с расширением pcap, описать проблему и отправить в техническую поддержку Exolve сгенерированный файл.

Требования для отправки сообщения через short_message

  1. Для отправки сообщения через “short_message” установите в PDU текст сообщение в поле “short_message”. Убедитесь, что текст сообщения представлен в одной из кодировок: GSM7, UCS2, ISO88595, Latin1.

  2. Сообщение более чем из одного сегмента должно содержать UDH (User Data Header), чтобы абонентский терминал получателя корректно соединил части сообщения.

  3. В одной части составного сообщения можно передавать не более 67 символов в кириллице и 153 в латинице.

  4. Если SMSC получает от ESME составное сообщение, то отправляет ответ в PDU submit_sm_resp каждый раз, когда получает часть сообщения. При этом message_id будет строиться следующем образом:

    • Сегмент 1: 452777198852505602,
    • Сегмент 2: 452777198852505602_2,
    • Сегмент 3: 452777198852505602_3

Требования для отправки сообщения через payload

  1. Для отправки сообщения через параметр “payload” установите в PDU текст сообщение в поле “payload”.

  2. Вам не нужно разделять текст на сегменты при отправке сообщения через параметр “payload”, но важно учитывать, чтобы общая длина текста не превышала 10 сегментов.

  3. При отправке сообщения через параметр “payload” убедитесь, чтобы поле “short_message” было пустое, иначе текст будет браться из этого поля “short_message”.

Решения, где используется SMS SMPP

Попробовать бесплатно