| SMPP протоколПідключенняЧерез наш SMS-шлюз можливо відправляти повідомлення по протоколу SMPP версій 3.4 і 5.0.
Для отримання доступу по SMPP-протоколу необхідно включити в налаштуваннях в групі "Налаштування API"
відповідну опцію і додати IP-адреси, з яких будете виконувати підключення, на цій сторінці.
Адреса SMPP-сервера: smpp.smsc.ua, порт: 3700.
Для шифрованого SSL-підключення використовується порт 3443.
Адреса резервного SMPP-сервера: smpp2.smsc.ua.
Приклад налаштувань для підключення (формат kannel):
group = smsc
smsc = smpp
smsc-id = smsc
host = smpp.smsc.ua
port = 3700
smsc-username = <login>
smsc-password = <password>
system-type = ""
interface-version = 34
source-addr-autodetect = yes
source-addr-ton = 5
source-addr-npi = 1
dest-addr-ton = 1
dest-addr-npi = 1
validityperiod = 1440
transceiver-mode = true
receive-port = 0
enquire-link-interval = 60
wait-ack-expire = 0
max-pending-submits = 300
throughput = 30
Максимально можливий інтервал бездіяльності становить 2 хвилини. Протягом цього часу клієнту необхідно відправити повідомлення або виконати порожню команду ENQUIRE_LINK, інакше з'єднання буде розірвано через не активність.
Приклад додаткових налаштувань для підключення по SSL-протоколу (kannel версії 1.4.4 і вище):
...
port = 3443
ssl-client-certkey-file = "/etc/kannel.pem"
use-ssl = 1
...
Сертифікат можна згенерувати командою (Linux CentOS): /etc/ssl/certs/make-dummy-cert kannel.pem
Логін використовується від особистого кабінету, пароль повинен бути створений на сторінці Паролі для доступу. Логін і пароль не повинні бути російською мовою.
Даний розділ містить тільки короткий опис SMPP-протоколу. Подробиці дивіться в специфікації.
Завантажити специфікацію протоколу SMPP v3.4 smpp34.zip (500 Кб)
smpp34rus.zip (1,1 Мб).Швидкість розсилокПропускна спроможність підключення або кількість відправлених кожну секунду SMS-повідомлень залежить від розміру вікна передачі (smpp window size).
У прикладі налаштувань даний параметр називається max-pending-submits. Для масових розсилок краще ставити великі значення (1000-2000).
Також в прикладі параметр throughput задає обмеження на максимальну кількість SMS-повідомлень в секунду.
Разом із масовими розсилками через одне підключення можна відправляти і термінові одиночні SMS-повідомлення. Система встановить максимальний пріоритет
таким повідомленням і відправить їх раніше будь-яких масових розсилок без очікування в черзі.
При масовій відправці повідомлень не варто забувати про систему контролю швидкості відправки повідомлень у секунду, при перевищенні якої відбувається генерація помилки перевищення швидкості (throttling). У разі отримання даної помилки Клієнту по SMPP-стандарту необхідно повторити відправку, знизивши загальну швидкість на своїй стороні. За замовчуванням швидкість задана 30 SMS/сек для кожного аккаунта. Для зміни максимально дозволеної швидкості необхідно відправити запит в службу підтримки сервісу.Множинні підключенняЗа замовчуванням сервер обробляє одночасно з одного логіна тільки одне підключення для більш коректної віддачі статусів,
тому при повторному підключенні раніше підключене з'єднання з таким же логіном буде автоматично завершуватися.
Якщо ж необхідно мати кілька одночасних підключень для підвищення швидкості відправки, то можна в налаштуваннях
всіх підключень задати наступний параметр (multi connection):
system-type = "MCON2"
або
system-type = "MCON9"
Значення після MCON може бути від 1 до 9 і задає кількість одночасних підключень.
Також можливі одночасні підключення з різними логінами, прив'язаними до одного особистого кабінету і рахунку.
Для цього необхідно створити в особистому кабінеті в розділі "Реселлер" додаткові аккаунти з необхідним типом субаккаунта.Відправка повідомленняВідправка SMS-повідомлення
Для відправки SMS-повідомлення використовуйте команду SUBMIT_SM згідно специфікації.
Підтримуються наступні кодування:
- 7-бітна GSM для латинського тексту з підтримкою європейських символів − (coding = 0);
- 8-бітна ISO-8859-1 (ASCII) для латинського тексту або бінарних даних − (coding = 1);
- UCS2 (UCS-2BE або UTF-16BE) для національних алфавітів (наприклад, російської) − (coding = 2).
Поле coding кодується двома бітами в складеному полі data_coding, тому data_coding = coding * 4.
Для використання кодування ISO-8859-1 (ASCII) замість GSM при підключенні потрібно вказати:
system-type = "ISO"
У текст SMS-повідомлення можна додавати коментарі, призначені для перегляду
відправником історії повідомлень в особистому кабінеті.
Команда SUBMIT_MULTI для множинної розсилки поки не реалізована.
Сервер не приймає більше одного однакового запиту на відправку SMS-повідомлень протягом хвилини
для захисту від помилок і зациклень у програмі на стороні клієнта для того, щоб знизити навантаження і не
витрачати кошти клієнта, а також не допустити багаторазової відправки повідомлення одному абоненту.
Сервер також блокує надсилання більше 50 повідомлень одному абоненту, які були відправлені з перервою
між повідомленнями менше 30-ти секунд, для захисту від флуду і зайвого списання коштів із рахунку клієнта,
так як багато операторів не пропускають велику кількість повідомлень одному абоненту за короткий проміжок часу.
При відправці складеного повідомлення Всі SMS-частини повинні бути передані на сервер протягом хвилини. В противному випадку
оператор може відхилити повідомлення, так як для перевірки на фільтри і шаблони все SMS-частини попередньо необхідно
склеїти, і більшість операторів очікує не більше хвилини.
Коментарі в SMS-повідомленнях
При відправці SMS-повідомлень можна додавати в кінець тексту будь-який коментар, уточнюючий або доповнюючий SMS-повідомлення для відправника.
Даний текст не буде відправлятися абонентам і впливати на вартість SMS і доступний для перегляду і фільтрації в списку відправлених повідомлень в особистому кабінеті.
Для додавання коментаря необхідно в кінці тексту SMS-повідомлення, призначеного для відправки, вказати спеціальну комбінацію "\n~~~\n"
(переклад рядка, 3 символу тильди і знову переклад рядка), і після цього будь-який текст, який буде вважатися коментарем, не буде відправлений абоненту,
але відобразиться в історії.Надсилання MMS-повідомлення
Для відправки MMS-повідомлення використовуйте команду SUBMIT_SM з текстом " __MMS__: <message>\nsubj:<subject>" (текст "__MMS__", двокрапка, пробіл, текст повідомлення, переклад рядка, текст "subj", двокрапка, тема MMS-повідомлення).Відправка e-mail повідомлення
Для відправки e-mail повідомлення використовуйте команду SUBMIT_SM з текстом "_ _ MAIL__: <message>\nsubj:<subject>" (текст "__MAIL__", двокрапка, пробіл, текст повідомлення, переклад рядка, слово "subj", двокрапка, тема e-mail повідомлення).Надсилання голосового повідомлення (дзвінок)
Для відправки голосового повідомлення використовуйте команду SUBMIT_SM з текстом "_ _ CALL__: <message>\nvoice:<voice>" (текст "__CALL__", двокрапка, пробіл, текст повідомлення, переклад рядка, слово "voice", двокрапка, голос, який використовується для озвучування тексту).
Можливі значення для використовуваного голосу:
- m – чоловічий голос.
- m2 – чоловічий голос 2.
- m3 – чоловічий голос 3.
- m4 – за замовчуванням) - чоловічий голос 4.
- w – жіночий голос.
- w2 – жіночий голос 2.
- w3 – жіночий голос 3.
- w4 – жіночий голос 4.
При відправці голосового повідомлення в кінці тексту можна вказати спеціальну комбінацію "\n~~~\n"(переклад рядка, 3 символу
тильди і знову переклад рядка), після якої передати параметр param, що визначає деякі характеристики дзвінка
(більш детально можна подивитися в описі).Відправка viber-повідомлення
Для відправки viber-повідомлення використовуйте команду SUBMIT_SM з текстом "_ _ VIBER__: <message>" (текст "__VIBER__", двокрапка, пробіл, текст повідомлення).
При формуванні тексту повідомлення можна використовувати спеціальні макроси для створення кнопки, при натисканні на яку буде відбуватися відкриття браузера і перехід за вказаним у макросі посиланням, а також прикріплювати файли. Більш детально
додаткові можливості при відправці viber-повідомлень описані в документації до http-протоколу.Відправка soc-повідомленняДля відправки soc-повідомлення, що відправляється користувачам соціальних мереж "Однокласники", "ВКонтакте" або користувачам "Mail.Ru Агент", використовуйте команду SUBMIT_SM з текстом " __SOC__: <message>" (текст "__SOC__", двокрапка, пробіл, текст повідомлення).
Відправка HLR-запиту
Для відправки HLR-запиту використовуйте команду SUBMIT_SM з текстом __HLR__.
Результат запиту приходить у звичайному статусі (Delivery Report), який можна отримати
як по SMPP-підключенню, так і по HTTP на свій обробник.
Формат статусу з результатом HLR-запиту, що повертається по SMPP:
id:<id> stat:<status> err:<err> imsi:<imsi> msc:<msc> mcc:<mcc> mnc:<mnc> cn:<cn> net:<net> rcn:<rcn> rnet:<rnet>
Опис параметрів:
| Параметр | Значення
|
|---|
| id | Ідентифікатор повідомлення.
|
|---|
| status | Статус повідомлення.
|
|---|
| err | Код помилки, якщо абонент недоступний (список).
|
|---|
| imsi | Унікальний код IMSI SIM-карти абонента.
|
|---|
| msc | Номер сервіс-центру оператора, в мережі якого знаходиться абонент.
|
|---|
| mcc | Числовий код країни абонента.
|
|---|
| mnc | Числовий код оператора абонента.
|
|---|
| cn | Назва країни реєстрації абонента.
|
|---|
| net | Назва оператора реєстрації абонента.
|
|---|
| rcn | Назва роумінгової країни абонента при знаходженні в чужій мережі.
|
|---|
| rnet | Назва роумінгового оператора абонента при знаходженні в чужій мережі.
|
|---|
Рядкові дані, наприклад, країна і оператор, закодовані через функцію urlencode.
Приклад результату HLR-запиту:
id:855469 stat:DELIVRD err:000 imsi:250023012345678 msc:79232510066 mcc:250 mnc:02 cn:Russian+Federation net:MegaFON+open+Joint+Stock+Company rcn: rnet:
Приклад коду на PHP для розбору рядка з результатом HLR-запиту:
$dlr = strtr($dlr, ": ", "=&"); // $dlr - строка статуса
parse_str($dlr, $m); // $m - массив параметров, $m["id"], $m["err"], $m["imsi"] и тд.
Приклад розбору через регулярні вирази:
preg_match("/^id:(\d+) stat:(\w+) err:(\d+) imsi:(\d*) msc:(\d*) mcc:(\d*) mnc:(\d*) cn:([^ ]*) net:([^ ]*) rcn:([^ ]*) rnet:([^ ]*)/", $dlr, $m); // $dlr - строка статуса
for ($i = 6; $i <= 9; $i++)
$m[$i] = urldecode($m[$i]);
// $m - массив параметров, $m[1] = id, $m[2] = status, $m[3] = err и тд.
Для відправки ping-SMS використовуйте команду SUBMIT_SM з текстом __PING__.Перевірка статусу
Отримувати статус доставки відправленого SMS-повідомлення по SMPP-протоколу можна як в автоматичному режимі,
отримуючи від сервера відповідну PDU-команду DELIVER_SM відразу після зміни статусу, так і за запитом
окремою командою QUERY_SM. Для автоматичного отримання статусу по SMPP-протоколу необхідно підключатися в режимі
transceiver або receiver і при відправці SMS вказувати прапор запиту статусу (registered_delivery).
Якщо при відправці не вказувати цей прапор, то статуси повідомлень будуть передаватися на HTTP-обробник.
При автоматичному поверненні статусу в команді DELIVER_SM передаються стандартні TLV-параметри receipted_message_id (<id>), message_state (числовий <status>) та network_error_code (<err>), а також додаткові TLV-поля, описані нижче:
| Ім'я (код) поля | Розмір | Тип | Опис
|
|---|
| 8192 (0x2000) | Var. max 6 | COctet String | Вартість повідомлення у форматі "n.nnnn".
|
|---|
| 8193 (0x2001) | 2 | Integer | Прапор у вигляді 2-х байтового числа, що містить різну інформацію про повідомлення. Можливі комбінації значень бітів різних характеристик.
Біти 0-3 (тип повідомлення):
0 (за замовчуванням) – SMS.
1 – Flash-SMS.
2 – Бінарне SMS.
3 – Wap-push.
4 – HLR-запит.
5 – Ping-SMS.
6 – MMS.
7 – Дзвінок.
8 – E-mail.
10 – Viber.
12 – Соцмережі.
Біт 5 – оплата повідомлення з другого балансу.
Біт 8 – ознака шаблонного повідомлення.
|
|---|
| 8194 (0x2002) | 2 | Integer | Кількість частин в повідомленні.
|
|---|
| 8195 (0x2003) | Var. max 5 | COctet String | mccmnc код країни / оператора абонента.
|
|---|
| 8196 (0x2004) | 2 | Integer | Додатковий статус повідомлення (2-прочитано, 4-натиснуто посилання).
|
|---|
Також в команді DELIVER_SM передається текст статусу в наступному форматі:
id:<id> sub:<sub> dlvrd:<dlvrd> submit date:<submit date> done date:<done date> stat:<status> err:<err>
Опис параметрів:
| Параметр | Значення
|
|---|
| id | Ідентифікатор повідомлення, призначений сервером при відправці.
|
|---|
| sub | Кількість SMS частин у відправленому повідомленні.
|
|---|
| dlvrd | Кількість доставлених SMS.
|
|---|
| submit date | Дата відправки.
|
|---|
| done date | Дата зміни статусу.
|
|---|
| status | Статус повідомлення у вигляді рядка (DELIVRD, EXPIRED, UNDELIV).
|
|---|
| err | Код помилки, якщо повідомлення не може бути доставлене (список).
|
|---|
Приклад результату рядка статусу (Delivery Report):
id:854019 sub:001 dlvrd:001 submit date:1108202241 done date:1108202241 stat:DELIVRD err:000
За замовчуванням для довгих повідомлень, що розбиваються на кілька SMS, сервер повертає тільки один статус (DELIVER_SM)
для всього склеєного повідомлення і однакові ID у відповіді SUBMIT_SM_RESP для всіх SMS-частин даного повідомлення.
Для включення режиму обробки і повернення статусів для кожної SMS-частини окремо встановіть наступний параметр в налаштуваннях підключення (або в налаштуваннях особистого кабінету):
system-type = "SINGLE"
Якщо необхідно вказати кілька параметрів у поле system-type, то вкажіть їх через кому:
system-type = "ISO,SINGLE"
Отримання вхідних повідомлень
Для включення пересилання вхідних SMS-повідомлень по SMPP-підключенню необхідно встановити галочку "Передавати вхідні SMS по SMPP-підключенню" в налаштуваннях особистого кабінету (розкривна вкладка "Налаштування API") або звернутися в службу підтримки. При цьому передача вхідних повідомлень на обробник клієнта повинна бути відключена.
Вхідні повідомлення приходять в PDU-команді DELIVER_SM. Для отримання необхідно підключатися до SMPP-сервера в режимі transceiver або receiver.Коди помилок у статусіМожливі коди помилок у статусі повідомлень або HLR-запитів (значення <err>):
| Код | Назва | Опис
|
|---|
| 0 | Немає помилки | Абонент існує та доступний.
|
|---|
| 1 | Абонент не існує | Зазначений номер телефону не існує.
|
|---|
| 6 | Абонент не в мережі | Телефон абонента відключений або знаходиться поза зоною дії мережі.
|
|---|
| 11 | Не підключена послуга | Означає, що абонент не може прийняти SMS-повідомлення. Наприклад, послуга не підключена,
або абонент знаходиться в роумінгу, де не активований прийом повідомлень, або у оператора абонента не налагоджений обмін SMS із
поточним роумінговим оператором. Також це може бути міський номер без прийому повідомлень.
|
|---|
| 12 | Помилка в телефоні абонента | Неможливо доставити повідомлення абоненту через помилки в телефонному апараті або SIM-картці.
|
|---|
| 13 | Абонент заблокований | Виникає, наприклад, якщо на рахунку абонента нульовий або негативний баланс, і
він знаходиться в роумінгу, або заблокований оператором за тривалу несплату або добровільно самим абонентом. Також
ця помилка може повертатися при пошкодженні SIM-карти або неправильному введенні PIN і PUK-кодів SIM-карти.
|
|---|
| 21 | Немає підтримки сервісу | Апарат абонента не підтримує роботу з даною послугою (сервісом).
|
|---|
| 200 | Віртуальна відправка | Дане повідомлення з'являється під статусом повідомлення в разі відправки
повідомлення в режимі тестування (при встановленій в налаштуваннях галочці "Режим тестування (віртуальна відправка без
оплати)").
|
|---|
| 219 | Заміна sim-карти | Помилка відправки повідомлення у зв'язку з заміною абонентом sim-карти. Після фізичної заміни sim-карти абоненту заблокований прийом повідомлень від буквених імен відправників на 24 години. Блокування може бути знято шляхом поповнення балансу на 100 рублів.
|
|---|
| 220 | Переповнена чергу у оператора | Зазначена помилка може виникати в разі, коли абонент недоступний
для прийому SMS, але повідомлення продовжують приходити оператору і відбувається переповнення внутрішньої черги повідомлень
для даного абонента. У рідкісних випадках можлива поява помилки в результаті збою в мережі самого оператора або переповненні
загальної черги повідомлень. У всіх подібних ситуаціях система з певними інтервалами кілька разів намагається відправити
зазначені повідомлення повторно.
|
|---|
| 224 | Недостатньо коштів | На рахунку клієнта недостатня сума для відправки повідомлення.
|
|---|
| 237 | Абонент не відповідає | Виникає, якщо в процесі спроби дозвону абонент не взяв трубку.
|
|---|
| 238 | Немає шаблону | Виникає, якщо відправка повідомлення можлива тільки за певним шаблоном, а відправляється
повідомлення йому не задовольняє.
|
|---|
| 239 | Заборонена ip-адреса | Виникає при спробі відправки повідомлення з ip-адреси, що не входить в список ip-адрес,
дозволених Клієнтом для відправки. Також може виникати при спробі відправки повідомлення з ip-адреси, яка раніше не використовувалась
для відправки повідомлень і входів в особистий кабінет.
|
|---|
| 240 | Абонент зайнятий | Виникає при передачі голосового повідомлення абоненту, якщо абонент зайнятий, або
скасував виклик.
|
|---|
| 241 | Помилка конвертації | При перетворенні тексту або звукового файлу в кінцевий формат для передачі
абоненту голосового повідомлення сталася помилка конвертації звуку. Також дана помилка може виникати при передачі
SMS-повідомлення окремими частинами, коли оператору передані не всі частини.
|
|---|
| 242 | Зафіксовано автовідповідач | Означає, що під час відправки голосового повідомлення на стороні абонента був
зафіксований автовідповідач.
|
|---|
| 243 | Не укладено договір | Виникає при спробі відправки розсилок рекламного або масового характеру без
укладеного договору.
|
|---|
| 244 | Розсилка заборонена | Означає, що для даного Клієнта заборонена відправка масових і рекламних розсилок,
або в тексті повідомлення зустрілось заборонене посилання.
|
|---|
| 245 | Статус не отримано | Протягом доби статус доставки не був отриманий від оператора, в цьому
випадку не можна точно сказати, було повідомлення доставлено чи ні.
|
|---|
| 246 | Обмеження часу | Якщо в особистому кабінеті у пункті "Налаштування" у вкладці "Ліміти та обмеження"
встановлено "Час відправки" і галочка "заборонити відправку в інший час", то при спробі відправки SMS-повідомлень в період
часу, відмінний від зазначеного в полі "Час відправки", відправка повідомлень буде заборонятись із зазначенням даної помилки.
|
|---|
| 247 | Перевищено ліміт повідомлень | Перевищено загальний добовий ліміт повідомлень, зазначений Клієнтом в особистому кабінеті
у пункті "Налаштування".
|
|---|
| 248 | Немає маршруту | Означає, що на даний номер відправка повідомлень недоступна в нашому сервісі.
Наприклад, ввели неіснуючий мобільний код, або для зазначеного номера і тексту немає робочого SMS-шлюзу.
|
|---|
| 249 | Неправильний формат номеру | Виникає, коли мобільний код зазначеного номера і відповідна цьому коду
довжина номера невірні.
|
|---|
| 250 | Номер заборонений налаштуваннями | Номер потрапив під обмеження, встановлені Клієнтом для мобільних номерів в
особистому кабінеті в пункті "Налаштування".
|
|---|
| 251 | Перевищено ліміт на один номер | Перевищено добовий ліміт повідомлень на один номер. Ліміт встановлюється
Клієнтом в особистому кабінеті в пункті "Налаштування". Також така помилка можлива при відправці більше 50 повідомлень одному абоненту,
які були відправлені з перервою між повідомленнями менше 30 секунд.
|
|---|
| 252 | Номер заборонений | Виникає, наприклад, при спробі вказівки Клієнтом одного із наших федеральних номерів
як одержувача SMS-повідомлення.
|
|---|
| 253 | Заборонено спам-фільтром | Якщо текст повідомлення містить нецензурні вирази і образи, заклики відправити
sms і деякі інші заборонені тексти, то відправка повідомлення заблокується. Також заборонено вказувати в якості
відправника короткі платні номери, номер одержувача повідомлень, назви операторів, чужих інтернет-ресурсів, компаній і
державних організацій.
|
|---|
| 254 | Незареєстрований sender id | Дана помилка виникає при спробі відправки повідомлення від незареєстрованого
імені відправника.
|
|---|
| 255 | Відхилено оператором | Оператор відхилив повідомлення без вказівки точного коду помилки.
Таке буває, наприклад,
коли номер не належить жодному мобільному оператору, тобто з неіснуючим кодом, або з якоїсь іншої причини оператор
не може доставити повідомлення.
|
|---|
Можливі коди помилок в статусі e-mail повідомлень (значення <err>):
| Код | Назва | Опис
|
|---|
| 0 | Немає помилки | Одержувач існує і доступний.
|
|---|
| 1 | Адресат не існує | Вказана e-mail адреса не існує.
|
|---|
| 2 | Поштову скриньку переповнено | Поштовий сервер одержувача відхилив повідомлення з вказаним кодом помилки.
|
|---|
| 3 | Сервер одержувача не знайдено | Домен, вказаний як поштовий сервер, не знайдено.
|
|---|
| 4 | Поштову скриньку заблоковано | Від поштового сервера одержувача повернулася помилка про неможливість доставки
повідомлення через блокування ящика.
|
|---|
| 239 | Заборонена ip-адреса | Виникає при спробі відправки повідомлення з ip-адреси, що не входить в список ip-адрес,
дозволених Клієнтом для відправки. Також може виникати при спробі відправки повідомлення з ip-адреси, яка раніше не використовувалась
для відправки повідомлень і входів в особистий кабінет.
|
|---|
| 245 | Статус не отримано | Протягом доби статус доставки не був отриманий від поштового сервера одержувача, в цьому
разі не можна точно сказати, було повідомлення доставлено чи ні.
|
|---|
| 248 | Немає маршруту | Означає, що на даний e-mail адресу відправка повідомлень недоступна в нашому сервісі.
Наприклад, для вказаної адреси і тексту немає робочого e-mail шлюзу.
|
|---|
| 249 | Неправильний формат адреси | Виникає, коли ввели некоректну за форматом e-mail адресу одержувача.
|
|---|
| 252 | E-mail адреса заборонена | Виникає, наприклад, при знаходженні вказаної e-mail адреси в чорному списку.
|
|---|
| 253 | Заборонено спам-фільтром | Якщо текст повідомлення містить нецензурні вирази і образи, заклики відправити
sms або e-mail і деякі інші заборонені Тексти, то відправка повідомлення заблокується. Також заборонено вказувати в якості
відправника e-mail адреса одержувача повідомлення, адреси чужих інтернет-ресурсів, компаній і державних організацій.
|
|---|
| 254 | Незареєстрований відправник | Дана помилка виникає при спробі відправки повідомлення від незареєстрованого
e-mail адреси відправника.
|
|---|
| 255 | Відхилено сервером одержувача | Поштовий сервер одержувача відхилив повідомлення без вказівки точного коду помилки.
Таке буває, наприклад,
при виникненні внутрішньої помилки сервера, коли він не може обробити повідомлення.
|
|---|
|
