Тарифи  Послуги  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 = 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.
При відправці повідомлень також можливе зазначення мови озвучування тексту у вигляді: "m, en", "w, fr", "w, de" і т. п.

В процесі формування повідомлення в кінці тексту можна вказати спеціальну комбінацію "\n~~~\n"(подача рядка, 3 символу тильди і знову переведення рядка), після якої передати параметр param, що визначає деякі характеристики дзвінка (більш детально можна подивитися в опис).

Відправка viber-повідомлення

Для відправки viber-повідомлення використовуйте команду SUBMIT_SM з текстом "_ _ VIBER__: <message>" (текст "__VIBER__", двокрапка, пробіл, текст повідомлення).

При формуванні тексту повідомлення можна використовувати спеціальні макроси для створення кнопки, при натисканні на яку буде відбуватися відкриття браузера і перехід за вказаним у макросі посиланням, а також прикріплювати файли. Більш детально додаткові можливості при відправці viber-повідомлень описані в документації до http-протоколу.

Відправка soc-повідомлення

Для відправки soc-повідомлення, що відправляється користувачам соціальних мереж "Однокласники", "ВКонтакте" або користувачам "Mail.Ru Агент", використовуйте команду SUBMIT_SM з текстом " __SOC__: <message>" (текст "__SOC__", двокрапка, пробіл, текст повідомлення).

Відправлення повідомлення в чат-бот Telegram

Для відправки повідомлення в чат-бот Telegram використовуйте команду SUBMIT_SM з текстом " _ _ BOT__: <message>\nbot:@<bot_name>" (текст "__BOT__", двокрапка, пробіл, текст повідомлення, подача рядка, текст "bot", двокрапка, ім'я бота).

Відправка 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 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 – Дзвінок.
8 – E-mail.
10 – Viber.
12 – Соцмережі.

Біт 5 – оплата повідомлення з другого балансу.
Біт 8 – ознака шаблонного повідомлення.
8194 (0x2002)2IntegerКількість частин в повідомленні.
8195 (0x2003)Var. max 5COctet Stringmccmnc код країни / оператора абонента.
8196 (0x2004)2IntegerДодатковий статус повідомлення (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 адресу одержувача.
252E-mail адреса забороненаВиникає, наприклад, при знаходженні вказаної e-mail адреси в чорному списку.
253Заборонено спам-фільтромЯкщо текст повідомлення містить нецензурні вирази і образи, заклики відправити sms або e-mail і деякі інші заборонені Тексти, то відправка повідомлення заблокується. Також заборонено вказувати в якості відправника e-mail адреса одержувача повідомлення, адреси чужих інтернет-ресурсів, компаній і державних організацій.
254Незареєстрований відправникДана помилка виникає при спробі відправки повідомлення від незареєстрованого e-mail адреси відправника.
255Відхилено сервером одержувачаПоштовий сервер одержувача відхилив повідомлення без вказівки точного коду помилки.
Таке буває, наприклад, при виникненні внутрішньої помилки сервера, коли він не може обробити повідомлення.



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