SMS SMPP

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

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

• Глоссарий - список терминов, используемых в статьях;
• Параметры подключения - инструкция, где найти параметры подключения к SMPP-протоколу в Личном кабинете;
• Подключение - описание процесса подключения к SMPP-протоколу;
• Получение входящих SMS - как принимать входящие SMS через SMPP;
• Требования для отправки сообщения - требования к SMS для отправки через SMPP-протокол.

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

SMS-рассылки

SMS-шлюз

Рекламные SMS-рассылки

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

Глоссарий

В статьях раздела 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.

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

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

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

Подключение

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

Подключение

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Отчет о доставке запрашивается установкой registered_delivery=1 в команде submit_sm. Если параметр не установлен, отчет о доставке не гарантируется.

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

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

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

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

{
    "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"
        }
}

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

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

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

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

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

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

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

Получение входящих SMS

Вы можете получать входящие SMS на номера вашего приложения через SMPP. Сообщения поступают от сервера Exolve в ваше приложение командой deliver_sm.

Подключение для получения сообщений

Для приема SMS используйте SMPP-реквизиты приложения, которому принадлежит принимающий номер.

Установите соединение с smpp.exolve.ru на порту 2775 и выберите режим подключения:

Передайте логин в поле system_id, пароль в поле password. Успешное подключение подтверждается ответом bind_receiver_resp или bind_transceiver_resp с command_status=0.

Для получения входящих SMS вам не нужно отправлять submit_sm или устанавливать registered_delivery=1. Параметр registered_delivery используется для запроса отчетов о доставке исходящих SMS.

Рекомендуем использовать одно принимающее SMPP-подключение на приложение. Входящие сообщения не рассылаются во все подключения приложения.

Формат входящего сообщения

При получении SMS сервер отправляет PDU deliver_sm со следующими параметрами:

Декодируйте текст в соответствии с data_coding. Для UCS2 используйте порядок байтов Big Endian.

Пример короткого входящего SMS

Ниже показаны значимые поля deliver_sm для сообщения «Hello». Номера приведены для примера.

{
    "command": "deliver_sm",
    "sequence_number": 101,
    "source_addr": "79990000001",
    "destination_addr": "79990000002",
    "esm_class": "0x00",
    "data_coding": "0x00",
    "short_message": "48 65 6C 6C 6F"
}

Значение short_message в примере записано в шестнадцатеричном виде. После декодирования GSM7 вы получите текст Hello.

Как отличить входящее SMS от отчета о доставке

Входящие SMS и отчеты о доставке передаются одной командой deliver_sm. Чтобы определить тип полученного сообщения, проверяйте поле esm_class:

В обработчике проверяйте биты поля esm_class:

{
    "delivery_receipt": "(esm_class & 0x3C) == 0x04",
    "udh_present": "(esm_class & 0x40) != 0"
}

Если вы получили отчет о доставке, обрабатывайте его по правилам раздела «Отчет о доставке сообщения». Поле id отчета позволяет связать его с message_id, полученным в ответе submit_sm_resp.

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

Длинное входящее SMS поступает несколькими PDU deliver_sm. Каждый PDU содержит один сегмент сообщения. Сервер устанавливает признак UDH в esm_class и добавляет заголовок в начало поля short_message.

Большинство символов GSM7 занимают одну единицу кодирования. Символы расширенной таблицы, например ^, {, } и €, занимают две. Одна буква кириллицы в UCS2 занимает одну кодовую единицу, то есть два байта.

Для входящих составных SMS используется UDH с 8-битным идентификатором:

{
    "udh": "05 00 03 RR NN SS"
}

Пример сообщения из двух сегментов

Сообщение из 80 букв «А» передается в UCS2 двумя сегментами: 67 букв в первом и 13 во втором.

В этом примере 2A — общий идентификатор сообщения. Каждая буква «А» представлена байтами 04 10. Заголовок UDH и байты текста находятся в одном поле short_message.

Чтобы восстановить сообщение:

1. Прочитайте UDH и определите общий идентификатор, количество и номера сегментов.
2. Исключите UDH из текстовых данных каждого сегмента.
3. Декодируйте оставшиеся байты по значению data_coding.
4. Объедините текст сегментов в порядке их номеров.

При объединении учитывайте отправителя, получателя и идентификатор из UDH. Идентификатор может повторяться у разных сообщений, поэтому не используйте его как единственный постоянный ключ. sequence_number служит для подтверждения отдельного PDU, а не для объединения сегментов.

Подтверждение получения

На каждый успешно принятый deliver_sm отправляйте deliver_sm_resp с command_status=0 и тем же sequence_number.

Например, для входящего PDU с sequence_number=101 отправьте:

{
    "command": "deliver_sm_resp",
    "sequence_number": 101,
    "command_status": "0x00000000"
}

Подтверждайте каждый сегмент длинного SMS отдельно, не дожидаясь сборки всего сообщения. Также подтверждайте получение отчетов о доставке.

Поддержание соединения

Для получения входящих сообщений поддерживайте активную SMPP-сессию. Используйте enquire_link для проверки соединения и обрабатывайте ответ enquire_link_resp.

После разрыва восстановите TCP-соединение и повторно выполните bind_receiver или bind_transceiver. Для завершения работы отправьте unbind.

Получение SMS, поступивших во время отсутствия принимающей сессии, и автоматическая повторная доставка не гарантируются.

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

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

1. Протокол взаимодействия с SMSC — SMPP-протокол 3.4.
2. Максимальное количество сегментов в одном сообщении — 10.
3. Для обмена сообщениями между ESME и SMSC могут использоваться следующие типы подключения: receiver, transceiver — в зависимости от направления трафика. Подключение transmitter пока недоступно.
4. При отправке сообщения обязательно нужно передавать параметр data_coding, с помощью которого вы указываете в какой кодировке было передано сообщение. Поддерживаемые кодировки: GSM7, UCS2. Рекомендуется использовать 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.
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

SMS-рассылки на <<Билайн>>

SMS-рассылки на <<Теле2>>

SMS-рассылки на <<Мегафон>>

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