МТС Маркетолог

Документация SMPP

📩 Если возникнут проблемы, пишите на omnisupport@mts.ru
В письмо добавьте подробности — так поможем быстрее
  • Название компании
  • system_id — логин для подключения к платформе
  • описание проблемы
  • пример сообщения: дата, время, system_id, имя отправителя, номер получателя, message_id, коды ошибок
  • tcpdump, логи с ошибкой, статистика по ошибке
     

Почему SMS могут не отправляться

  1. Не куплен пакет SMS. Если у вас тестовый период — пакет нужно подключать каждый день. Посмотреть пакеты можно в личном кабинете иконка кошелька → пакеты SMS
  2. Не подключено имя отправителя. Проверить статус имени можно в личном кабинете Инструменты → Имя отправителя
  3. Имя отправителя подключено не на всех операторов. Тогда  SMS будут уходить только на подключённых операторов

 

⚙️ Чтобы SMS отправлялись

  1. В личном кабинете МТС Маркетолога должно быть подключено имя отправителя для рассылок по своей базе PRO.
  2. Должен быть подключен пакет SMS.

Подробнее

Как настроить SMPP-подключение

  1. Установите stunnel на компьютер и запустите его. Инструкция по установке на разные ОС есть в конце статьи.
  2. При подключении командой bind_transceiver, используйте ip-адрес stunnel 127.0.0.1 и порт 3800. Если stunnel и SMPP клиент находятся на разных хостах, укажите ip-адрес хоста, на котором установлен stunnel.
  3. При запуске сессии командой bind_ установите в PDU параметры:
    system_id — логин, который вы получили при создании SMPP-подключения в кабинете МТС Маркетолога
    password — пароль, оттуда же
  4. Как запустите сессию — можно отправлять SMS командой submit_sm.

 

 Подробнее о команды bind_* и submit_sm — в спецификации SMPP 3.4

🔒 Как получить логин и пароль 

1. Зайти в МТС Маркетолог

2. Создать профиль как ИП или юридическое лицо

3. Зайти в раздел Инструменты → Интеграции → SMPP и создать подключение — сгенерируем логин и пароль. 

 

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

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

Термины

SMSC — SMS-центр
Пользователь — вы
Оборудование — например, ваш сервер
Абонент — получатель SMS

  • Протокол взаимодействия с SMSC — SMPP v3.4
  • Сервис работает в синхронном и асинхронном режимах. Размер окна — 99, пропускная способность — 10 SMS в секунду.
  • Для обмена SMS между оборудованием и SMSC может использоваться любой из типов подключения: transmitter, receiver, transceiver — в зависимости от направления трафика: на Пользователя, от Пользователя, на и от Пользователя.
  • Если SMPP- и TCP-сессии оборвутся, ожидайте 1,5 минуты — после установите новую TCP-сессию и отправьте в сторону SMSC PDU команду bind_transceiver/ bind_transmitter / bind_receiver. Если соединение оборвётся, увеличьте ожидание до 2 минут.
  • При отправке PDU bind_transceiver выставите значения полей
Address TON (addr_ton) = 0
Address NPI (addr_npi) = 0
Address Range (address_range) = NULL
  • Номер получателя в формате 79ххххххххх должен иметь
 destination_addr_ton = 1 и destination_addr_npi = 1

 Буквенно-цифровой номер отправителя (alphanumeric) 

 source_addr_ton = 5, source_addr_npi = 0
Пример настройки интерфейса 
  • Оборудование должно отправлять на каждый полученный от SMSC PDU deliver_sm (data_sm) подтверждение deliver_sm_resp (data_sm_resp) со статусом 0 (OK). Отправка PDU generic_nack запрещена
  • Оборудование должно отправлять PDU enquire_link каждые 30 секунд вне зависимости от наличия или отсутствия трафика в SMPP-соединении.
  • SMS из более чем из одного сегмента, отправленные со стороны контент-провайдера, должны содержать UDH или SAR параметры — чтобы корректно соединить части сообщения абонентским терминалом Пользователя
  • В одной части составного SMS можно передавать не более 67 символов в кириллице и 153 в латинице.
  • Если SMSC получает от Оборудования составное SMS, то отправляет ответ в PDU submit_sm_resp — каждый раз, когда получает часть SMS. При этом Оборудование должно передать все части составного SMS за период не более 60 секунд. Если не соблюдать требование, SMSC не отправит полученные от Оборудования части составного SMS и отправит на Оборудование PDU deliver_sm с отчётом о доставке delivery report, содержащим код ошибки 0x00000384 (ESME_RCNCTTIMEOUT).
  • Используйте схему кодировки DCS 0х03 (HEX) для текста на латинице и DCS 0х08 (HEX) для текста на кириллице — в соответствии со спецификациями SMPP v3.4/v.5.0, 3GPP TS 23.038.
  • Значение параметра validity_period не должно быть меньше 60 секунд. Если значение будет меньше — оно принудительно изменится на 60.
  • Кодировка поля destination_addr должна быть в ASCII (символы между 36 (0x24) и 126 (0x7E)).
  • Значение поля protocol_id должно быть = 0.
  • Контролируйте равномерность скорости отправки SMS. Например, если установлено ограничение 100 SMS в секунду — отправляйте SMS каждые 10 миллисекунд, а не 100 SMS за первые 100 миллисекунд.
  • Если при разрыве TCP-сессии со стороны SMSC в сторону Оборудования отправляется TCP-пакет с флагом FIN, то в ответ Оборудование должно отправить пакет FIN (FIN, ACK). Любой другой ответ запрещён.
  • Чтобы отслеживать правильность взаимодействия SMSC и Оборудования по протоколам TCP и SMPP, рекомендуем использовать протокольный анализатор — например, Wireshark. Если возникнут проблемы в работе сервиса следует провести анализ tcpdump, описать проблему и направить tcpdump на omnisupport@mts.ru

 

Ошибки при отправке

Как обрабатывать ошибки протокола SMPP

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

Даже если SMS принято к отправке, доставка SMS не гарантирована

ОперацияКод ошибкиЧто делать 
submit_sm_resp Invalid Destination AddressУдалите сообщение из очереди и больше не пытайтесь отправить
submit_sm_respThrottling errorПоместите сообщение, на которое пришла ошибка, в начало очереди на отправку. Время ожидания перед повторной отправкой сообщений с Оборудования в данном соединении должно составлять 1 секунду.
submit_sm_respMessage Queue Full

Поместите сообщение, на которое пришла ошибка, в конец очереди. И выполните от 3 до 5 повторных попыток отправки, каждый раз возвращая это SMS в конец очереди — если ошибка повторяется.

Рекомендуем применять прогрессивный метод обработки этой ошибки: после первой ошибки делать паузу перед отправкой 5 секунд, при второй — 15 секунд, третьей — 45 секунд и т. д. Если после 3-5 попыток доставить SMS возвращается ошибка Message Queue Full, удалите его из очереди.

 

 deliver_sm620
submit_sm_respInvalid Source AddressЗаблокируйте отправку сообщений с данного номера отправителя. Не повторяйте отправки, пока не получите от МТС уведомление, что номер внесли в разрешённый список номеров отправителей на SMSC.
submit_sm_resp Message Length is invalidУменьшите количество символов в тексте сообщения в полях short_message или message_payload TLV в соответствии с ограничениями протокола GSM. Спецификация GSM 03.40/3GPP TS 23.040
deliver_sm950Приостановите отправку SMS, удалите  сообщения из очереди и не отправляйте снова в течение 24 часов.

Код ошибки 903 SMSC delivery timeout (ESME_RDLVRTIMEOUT) формируется, если через 72 часа после принятия SMS к отправке от SMSC не получен pdu deliver_sm c delivery_report. Либо после истечения срока, заданного в pdu submit_sm (validity period).

Коды ошибок в submit_sm_resp

 

SMPP Error CodeValue (HEX)DescriptionCDR ‘command_status’ field
(message status)
Value (HEX)Value (DEC)Description
ESME_ROK0x00000000No ErrorMSG_ERROR_NONE0x000No error occurred
ESME_RINVMSGLEN0x00000001Message Length is invalidMSG_ERROR_VALIDATION0x84132Message is invalid
ESME_RSYSERR0x00000008System ErrorMSG_ERROR_UNROUTABLE0x0b11Unroutable message
ESME_RINVSRCADR0x0000000AInvalid Source AddressMSG_ERROR_INVALID_SRC0x85133Invalid source address
ESME_RINVSRCADR0x0000000AInvalid Source AddressMSG_ERROR_FORBIDDEN_SRC0x8b139Forbidden source address
ESME_RINVDSTADR0x0000000BInvalid Dest AddrMSG_ERROR_UNKNOWN_RECIPIENT0x81129The recipient is unknown
ESME_RINVDSTADR0x0000000BInvalid Dest AddrMSG_ERROR_INVALID_DST0x88136Invalid destination address(es)
ESME_RINVDSTADR0x0000000BInvalid Dest AddrMSG_ERROR_FORBIDDEN_DST0x8c140Forbidden destination address
ESME_RINVDSTADR0x0000000BInvalid Dest AddrMSG_ERROR_MNP_CHECK_BARRING0x8e142MNP check barring error
ESME_RMSGQFUL0x00000014Message Queue FullMSG_ERROR_CONGESTION0x0a10Congestion error
ESME_RTHROTTLED0x00000058Throttling error (ESME has exceeded
allowed message limits)
MSG_ERROR_THROTTLED0x099Throttling error
ESME_RINVEXPIRY0x00000062Invalid message validity period
(Expiry time)
MSG_ERROR_EXPIRED0xff255The message has expired
ESME_RX_T_APPN0x00000064ESME Receiver Temporary App
Error Code
MSG_ERROR_TEMPORARY0x011A temporary error occurred
ESME_RX_T_APPN0x00000064ESME Receiver Temporary App
Error Code
MSG_ERROR_TRANSPORT_ERROR0x022A transport error occurred
ESME_RX_T_APPN0x00000064ESME Receiver Temporary App
Error Code
MSG_ERROR_SRI_TRANSPORT_ERROR0x033A SRI transport error occurred
ESME_RX_T_APPN0x00000064ESME Receiver Temporary App
Error Code
MSG_ERROR_SIM_CARD_FULL0x044The SIM card of the receiver is full GSM MAP memoryCapacityExceed error
ESME_RX_T_APPN0x00000064ESME Receiver Temporary App
Error Code
MSG_ERROR_ABSENT_SUBSCRIBER0x055The mobile subscriber is absent GSM MAP absentSubscriber error
ESME_RX_T_APPN0x00000064ESME Receiver Temporary App
Error Code
MSG_ERROR_TIMEOUT0x066Transaction has timed out
ESME_RX_T_APPN0x00000064ESME Receiver Temporary App
Error Code
MSG_ERROR_ILLEGAL_EQUIPMENT0x077GSM MAP illegalEquipment error
ESME_RX_T_APPN0x00000064ESME Receiver Temporary App
Error Code
MSG_ERROR_CANCELLED0x088Message processing has been cancelled
ESME_RX_T_APPN0x00000064ESME Receiver Temporary App
Error Code
MSG_ERROR_NO_RETRY_LEFT0x82130No retry left
ESME_RX_P_APPN0x00000065ESME Receiver Permanent App Error
Code
MSG_ERROR_DEFINITIVE0x80128A definitive error occurred
ESME_RX_P_APPN0x00000065ESME Receiver Permanent App Error
Code
MSG_ERROR_VALIDATION0x84132Message is invalid
ESME_RPROHIBITED0x00000101ESME Prohibited from using specified
operation.
MSG_ERROR_CHARGING0x8d141Charging error
ESME_RPROHIBITED0x00000101ESME Prohibited from using specified
operation.
MSG_ERROR_BLACKLISTED0x8f143Blacklisted recipient
Коды ошибок в deliver_sm

 

Код ошибки в DR (DEC)Соответствует коду ошибки SMPPКод ошибки в submit_sm_resp (HEX)
601Message Length is invalid (ESME_RINVMSGLEN)0x000000001
608System Error (ESME_RSYSERR)0x000000008
610Invalid Source Address (ESME_RINVSRCADR)0x00000000A
611Invalid Dest Addr (ESME_RINVDSTADR)0x00000000B
620Message Queue Full (ESME_RMSGQFUL)0x000000014
688Throttling error (ESME has exceeded allowed message limits)  (ESME_RTHROTTLED)0x000000058
698Invalid message validity period Expiry time (ESME_RINVEXPIRY)0x000000062
700ESME Receiver Temporary App Error Code  (ESME_RX_T_APPN)0x000000064
701ESME Receiver Permanent App Error Code (ESME_RX_P_APPN)0x000000065
857ESME Prohibited from using specified operation (ESME_RPROHIBITED)0x000000101
900Сoncatenation timeout (ESME_RCNCTTIMEOUT)0x00000384
901Routing error (ESME_ROUTERR0x00000385
902SMSC response timeout (ESME_RRESPTIMEOUT)0x00000386
903SMSC delivery timeout (ESME_RDLVRTIMEOUT)0x00000387
904 – 949Резерв 
950Временный код ошибки, формируется в течение 24 часов после замены SIM-карты абонентом «МТС».0x000007FFF
951-998Резерв 

 

Как установить stunnel

Нужна версия  5.56+
 

Windows x64
  1. Скачайте программу stunnel-5.XX-win64-installer.exe для windows на сайте stunnel.org
  2. Запустите установщик (exe файл)
  3. По инструкции установщика установите stunnel на компьютер, оставьте все параметры по умолчанию
  4. После установки нажмите на ярлык на рабочем столе, чтобы запустить программу
  5. В открывшемся окне выберите пункт configuration → edit configuration
  6. Откроется файл конфигурации. Удалите из него всё и внесите новые данные:
1
2
3
4
[smpp]
client = yes
accept = 0.0.0.0:3800
connect smpp.marketolog.mts.ru:3800

 

7. Перезапустите stunnel

linux

Ubuntu 20.04 и выше


1. Установите stunnel:

sudo apt-get install stunnel4

2. Создайте файл conf и сконфигурируйте коннект:
 

sudo nano /etc/stunnel/stunnel.conf
[smpp]
client = yes
accept = 0.0.0.0:3800
connect = smpp.marketolog.mts.ru:3800

3. Запустите stunnel:

sudo systemctl start stunnel
sudo systemctl enable stunnel

 

1. Скачайте stunnel, не ниже версии 5.56:
wget https://www.stunnel.org/downloads/stunnel-5.59.tar.gz

2. Распакуйте:
tar -xvf stunnel-5.59.tar.gz

3. Установите:

apt-get install stunnel4

4. Создайте файл conf и сконфигрурируйте коннект:

sudo nano /etc/stunnel/stunnel.conf

 

CentOS 7 и ниже

  1. Скачайте stunnel (вместо XX указать доступную версию):
wget https://www.stunnel.org/downloads/stunnel-5.XX.tar.gz

2. Распакуйте:

tar -xvf stunnel-5.XX.tar.gz

3. Соберите и установите. В процессе сборки могут потребоваться дополнительные пакеты в системе, их необходимо будет доставить. 

cd stunnel-5.XX
./configure
make
make install

4. Создайте файл conf и сконфигурируйте коннект:
 

sudo vim /etc/stunnel/stunnel.conf
[smpp]
client = yes
accept = 0.0.0.0:3800
connect = smpp.marketolog.mts.ru:3800

5. Запустите stunnel:

stunnel /etc/stunnel/stunnel.conf
Установка stunnel из докера

sudo docker run -d -e STUNNEL_CLIENT=yes -e STUNNEL_ACCEPT=0.0.0.0:3800 -e STUNNEL_CONNECT=smpp.marketolog.mts.ru:3800 -e STUNNEL_SERVICE=smpp -p 3800:3800 dweomer/stunnel

 

© 0 ПАО «МТС» 18+