Тарифи  Послуги  API  Партнерам  Про сервіс  Контакти 
0 (800) 30 7672
Безкоштовно по Україні
 

Інтеграція з сервісом (API)

API дозволяє розсилати повідомлення через ваші проекти і сервіси по протоколах HTTP, HTTPS, SMTP та SMPP. Готові бібліотеки на різних мовах програмування підключаються до вашому проекту і допомагають відправляти повідомлення з будь-якого місця за допомогою однієї команди.


HTTP/HTTPS SMTP SMPP SOAP OMS SMS-команди Бібліотеки і приклади коду

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 = 100

Максимально можливий інтервал бездіяльності становить 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 Mб).

Швидкість розсилок

Пропускна здатність підключення або кількість відправлених кожну секунду SMS-повідомлень залежить від розміру вікна передачі (smpp window size). У прикладі налаштувань даний параметр називається max-pending-submits. Для масових розсилок краще ставити великі значення (1000-2000). Також у прикладі параметр throughput задає обмеження на максимальну кількість SMS-повідомлень в секунду.

Разом з масовими розсилками через одне підключення можна відправляти і термінові поодинокі SMS-повідомлення. Система встановить максимальний пріоритет таким повідомленнями і відправить їх раніше будь-яких масових розсилок без очікування в черзі.

При масової відправки повідомлень не варто забувати про систему контролю швидкості відправки повідомлень в секунду, при перевищенні якої відбувається генерація помилки перевищення швидкості (throttling). У разі отримання даної помилки Клієнту за SMPP-стандарту необхідно повторити відправку, знизивши загальну швидкість на своїй стороні. За замовчуванням задана швидкість 100 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-повідомлення, призначеного для відправлення, вказати спеціальну комбінацію "\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 – чоловічий альтернативний голос.
  • w – жіночий голос.
  • w2 – жіночий альтернативний голос.
При відправленні голосового повідомлення у кінці тексту можна вказати спеціальну комбінацію "\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 и тд.

Для надсилання 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-поля з кодами 0x2000 і 0x2001, що містять інформацію про вартість і тип повідомлення:

Ім'я (код) поляРозмірТипОпис
8192 (0x2000)Var. max 6COctet StringВартість повідомлення у форматі "n.nnnn".
8193 (0x2001)2IntegerПрапор у вигляді 2-х байтового числа, що містить різну інформацію про повідомленні. Можливі комбінації значень бітів різних характеристик.

Біти 0-3 (тип повідомлення):
0 (за замовчуванням) – SMS.
1 – Flash-SMS.
2 – Бінарне SMS.
3 – Wap-push.
4 – HLR-запит.
5 – Ping-SMS.
6 – MMS.
7 – Дзвінок.
10 – Viber.

Біт 5 – оплата повідомлення з другого балансу.
Біт 8 – ознака шаблонного повідомлення.

Також в команді 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-повідомлення. Наприклад, послуга підключена, або абонент знаходиться в роумінгу, де не активований прийом повідомлень, або у оператора абонента не налагоджено обмін SMS з поточним роумінговими оператором. Також це може бути міський номер без прийому повідомлень.
12Помилка в телефоні абонентаНе вдається доставити повідомлення абоненту з-за помилки в телефонному апараті або на SIM-картці.
13Абонент заблокованийВиникає, наприклад, якщо на рахунку абонента нульовий або негативний баланс, і він знаходиться в роумінгу, або заблоковано оператором за тривалу несплату або добровільно самим абонентом. Також дана помилка може повертатися при пошкодженні SIM-карти або неправильному введенні PIN і PUK-кодів SIM-карти.
21Немає підтримки сервісуАпарат абонента не підтримує роботу з даною послугою (сервісом).
200Віртуальна відправленняДане повідомлення з'являється під статусом у разі відправлення повідомлення повідомлення в режимі тестування (при встановленій у налаштуваннях галочці "Режим тестування (віртуальна відправка без оплати)").
219Заміна sim-картиПомилка відправки повідомлення у зв'язку з заміною абонентом sim-карти. Після фізичної заміни sim-карти абоненту заблокований прийом повідомлень від буквених імен відправників на 24 години. Блокування може бути знято шляхом поповнення балансу на 100 рублів.
220Переповнена чергу у оператораЗазначена помилка може виникати у випадку, коли абонент недоступний для прийому SMS, але повідомлення продовжують приходити оператору і відбувається переповнення внутрішньої черги повідомлень для даного абонента. У рідкісних випадках можлива поява помилки в результаті збою в мережі оператора або переповненні загальної черги повідомлень. У всіх подібних ситуаціях система з певними інтервалами кілька разів намагається відправити зазначені повідомлення повторно.
224Недостатньо коштівНа рахунку Клієнта недостатня сума для відправки повідомлення.
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Відхилено операторомОператор відхилив повідомлення без зазначення точного коду помилки.
Таке буває, наприклад, коли номер не належить жодному мобільному оператору, тобто з неіснуючим кодом, або з якоїсь іншої причини оператор не може доставити повідомлення.



© 2003–2021 ТОВ «СМСЦЕНТР»
Код за ЄДРПОУ 38404962
support@smsc.ua
Контакти
Дизайн — Студія Артемія Лебедєва
Інформація про сайт
Яндекс.Метрика