SMS SMPP
SMPP (Short Message Peer-to-Peer) — протокол связи для отправки и получения коротких сообщений в пиринговых сетях. SMPP-протокол обеспечивает постоянное подключение, соединение с SMS-сервером не разрывается, что дает возможность рассылать и получать SMS с высокой скоростью (выше чем, при других способах, например через SMS REST API).
Exolve предоставляет учётные данные пользователям для подключения к SMPP-протоколу. Информацию о том, где найти данные для подключения, процесс подключения, как отправить и принять SMS, вы можете найти в следующих статьях:
-
Глоссарий - список терминов, используемых в статьях;
-
Параметры подключения - инструкция, где найти параметры подключения к SMPP-протоколу в Личном кабинете;
-
Подключение - описание процесса подключения к SMPP-протоколу;
-
Требования для отправки сообщения - требования к SMS для отправки через SMPP-протокол.
Решения, где используется 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 |
Логин и пароль для подключения вы можете найти в Личном кабинете разработчика:
- Перейдите во вкладку “Приложения” в верхнем меню аккаунта.
- Нажмите на приложение, данные SMPP-аккаунта которого хотите посмотреть.
- Выберите вкладу “Сообщения” → “SMPP-аккаунт” в левом меню.
На открывшейся странице вы увидите логин, пароль и домен для подключения.
Подключение
Поддерживаемые команды
Команда | Описание | Комментарий |
---|---|---|
bind_transceiver | подключение ESME к SMSC в режиме приема и передачи сообщений | используйте эту команду для одновременной отправки и приема сообщений в обоих направлениях между ESME и SMSC, и для приема отчетов о доставке сообщений |
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
.
Получить 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 | ошибка доставки сообщения |
Требования для отправки сообщения
Общие требования
-
Протокол взаимодействия с SMSC — SMPP-протокол 3.4.
-
Максимальное количество сегментов в одном сообщении — 10.
-
Для обмена сообщениями между ESME и SMSC могут использоваться следующие типы подключения:
receiver
,transceiver
— в зависимости от направления трафика. Подключениеtransmitter
пока недоступно. -
При отправке сообщения обязательно нужно передавать параметр
data_coding
, с помощью которого вы указываете в какой кодировке было передано сообщение. Поддерживаемые кодировки:GSM7
,UCS2
,ISO88595
,Latin1
. Рекомендуется использоватьGSM7
для латинского алфавита иUCS2
, если в сообщении содержится кириллица. -
ESME должно отправлять PDU
enquire_link
каждые 15 минут вне зависимости от наличия или отсутствия трафика в SMPP-соединении. Если в течении 15 минут не было отправлено ни одного сообщения со стороны пользователя или ESME (в том числе enquire_link), то соединение будет разорвано. -
Чтобы отслеживать правильность взаимодействия SMSC и ESME по протоколам
TCP
иSMPP
, мы рекомендуем использовать протокольный анализатор — Wireshark.
Если возникнут проблемы в работе сервиса, просим вас провести анализ SMPP-трафика с нашим сервером и сгенерировать с помощью Wireshark файл с расширением pcap
, описать проблему и отправить в техническую поддержку Exolve сгенерированный файл.
Требования для отправки сообщения через short_message
-
Для отправки сообщения через “short_message” установите в PDU текст сообщение в поле “short_message”. Убедитесь, что текст сообщения представлен в одной из кодировок:
GSM7
,UCS2
,ISO88595
,Latin1
. -
Сообщение более чем из одного сегмента должно содержать UDH (User Data Header), чтобы абонентский терминал получателя корректно соединил части сообщения.
-
В одной части составного сообщения можно передавать не более 67 символов в кириллице и 153 в латинице.
-
Если SMSC получает от ESME составное сообщение, то отправляет ответ в PDU
submit_sm_resp
каждый раз, когда получает часть сообщения. При этомmessage_id
будет строиться следующем образом:- Сегмент 1: 452777198852505602,
- Сегмент 2: 452777198852505602_2,
- Сегмент 3: 452777198852505602_3
Требования для отправки сообщения через payload
-
Для отправки сообщения через параметр “payload” установите в PDU текст сообщение в поле “payload”.
-
Вам не нужно разделять текст на сегменты при отправке сообщения через параметр “payload”, но важно учитывать, чтобы общая длина текста не превышала 10 сегментов.
-
При отправке сообщения через параметр “payload” убедитесь, чтобы поле “short_message” было пустое, иначе текст будет браться из этого поля “short_message”.