Тарифи	Послуги	API	Партнерам	Про сервіс	Контакти

^{Безкоштовно по Україні}

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

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

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

ПІДКЛЮЧЕННЯ

ШВИДКІСТЬ РОЗСИЛОК

МНОЖИННІ ПІДКЛЮЧЕННЯ

ВІДПРАВЛЕННЯ ПОВІДОМЛЕННЯ

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

Коментарі в SMS-повідомленнях

Надсилання MMS-повідомлення

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

Відправка голосового повідомлення (дзвінок)

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

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

Відправка HLR-запиту

ПЕРЕВІРКА СТАТУСУ

ОТРИМАННЯ ВХІДНИХ ПОВІДОМЛЕНЬ

КОДИ ПОМИЛОК У СТАТУСІ

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 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 – Дзвінок. 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 Контакти		Дизайн — Студія Артемія Лебедєва Інформація про сайт