| Управління розсилкамиДії з розсилкамиДля створення розсилки необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/jobs.php?add=1&login=<login>&psw=<password>&name=<name>&phones=<phones>&mes=<message>
Для видалення розсилки необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/jobs.php?del=1&login=<login>&psw=<password>&id=<id>
Для відключення розсилки, що очікує відправки, необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/jobs.php?cancel=1&login=<login>&psw=<password>&id=<id>
Для отримання інформації про конкретну розсилку, необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/jobs.php?get=1&login=<login>&psw=<password>&id=<id>
Для отримання списку розсилок, необхідно викликати методом GET або POST адреса:
https://smsc.ua/sys/jobs.php?get_all=1&login=<login>&psw=<password>
Опис параметрів, що передаються Серверу при створенні розсилки (будь-який з додаткових параметрів застосовується до кожного повідомлення в розсилці; для роботи з e-mail розсилками необхідно в запиті передавати додатковий параметр):
| Параметр | Значення
|
|---|
| login | Логін Клієнта.
|
|---|
| psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
|---|
| apikey | Спеціальний API-ключ, який використовується для спрощеної авторизації замість пари "логін + пароль" (можна створити на даний сторінка).
|
|---|
| name | Назва розсилки.
|
|---|
| phones | Номер або розділений комою або крапкою з комою список номерів мобільних телефонів в міжнародному форматі,
на які відправляється повідомлення. Номери можуть передаватися без знака "+".
Якщо номер переданий без знака "+", то він може бути виправлений автоматичним форматуванням
і приведений до правильного міжнародного формату. Таким чином, деякі
помилки при введенні номерів телефонів можуть бути виправлені автоматично.
Для відключення автовиправлення передайте номер зі знаком "+".
Також можна відправляти повідомлення на групу номерів, вказавши спеціальний код "G<номер группы>".
Повідомлення буде відправлено на всі номери, що належать цій групі. Для E-mail повідомлення передається список e-mail адрес одержувачів. Для telegram в якості одержувача повідомлення можлива вказівка Ніка абонента або його ID у вигляді #ID.
|
|---|
| mes | Текст повідомлення, що відправляється. Максимальний розмір – 1000 символів. Повідомлення при
необхідності буде розбите на кілька SMS, відправлених абоненту і оплачених окремо. Розмір одного
SMS – 160 символів у латиниці або 70 символів у кирилиці. При розбивці повідомлення на кілька SMS в кожну частину
додається заголовок для об'єднання частин в одне повідомлення на телефоні одержувача, і максимальна довжина стає
67 для кирилиці і 153 для латинських букв. У текст повідомлення можна додавати коментарі,
призначені для перегляду відправником історії в особистому кабінеті.
|
|---|
| Додаткові параметри
|
|---|
| sender | Ім'я відправника, що відображається в телефоні одержувача.
Дозволені англійські букви, цифри, пробіл і деякі символи. Довжина – 11 символів або 15 цифр.
Всі імена реєструються в особистому кабінеті на даній сторінці.
|
|---|
| sender2 | Даний параметр використовується в якості імені відправника при автоповторі по SMS в разі недоставки повідомлень через первинний варіант відправки.
|
|---|
| translit | Ознака того, що повідомлення необхідно перевести у трансліт.
0 (за замовчуванням) – не переводити в трансліт.
1 – перекласти в трансліт у вигляді "translit".
2 – перевести в трансліт у вигляді "mpaHc/Ium".
|
|---|
| tinyurl | Автоматично скорочувати посилання в повідомленнях. Дозволяє замінювати посилання в тексті
повідомлення на короткі для скорочення довжини, а також для відстеження кількості переходів на
цій сторінці.
0 (за замовчуванням) – залишити посилання в тексті повідомлення без змін.
1 – скоротити посилання.
|
|---|
| time | Час відправки SMS-повідомлення абоненту.
Формати:
- DDMMYYhhmm або DD.MM.YY hh: mm.
- h1-h2. Задає діапазон часу в годиннику. Якщо поточний час менше h1, то SMS-повідомлення
буде відправлено абоненту при настанні часу h1, якщо поточний час потрапляє в проміжок від h1 до h2,
то повідомлення буде відправлено негайно, в іншому випадку відправка буде виконана на наступний день при
досягненні часу h1. Ця функція, наприклад, корисна для того, щоб не допустити отримання SMS-повідомлень
абонентами в нічний час.
- 0ts, де ts-timestamp, час у секундах, що минув з 1 січня 1970 року.
- +m. задає відносне зміщення часу від поточного в хвилинах. Символ + повинен кодуватися як %2B в http-запиті.
Якщо time = 0 або вказано вже минулий час, то повідомлення буде відправлено негайно.
|
|---|
| rpt | Визначає періодичність відправки новостворюваної розсилки.
0 (за замовчуванням) – вручну.
1 – щогодини.
2 – кожен день.
3 – кожен робочий день.
4 – кожні вихідні.
5 – щотижня.
6 – кожен місяць.
7 – кожен рік.
|
|---|
| rptn | Встановлює максимальну кількість повторів для відкладеної періодичної розсилки.
|
|---|
| tz | Часовий пояс, в якому задається параметр time. Вказується щодо московського часу.
Параметр tz може бути як позитивним, так і негативним. Якщо tz дорівнює 0, то буде використаний московський часовий
пояс, якщо ж параметр tz не заданий, то часовий пояс буде взятий із налаштувань клієнта.
|
|---|
| period | Проміжок часу, протягом якого необхідно відправити розсилку. Являє собою число
в діапазоні від 0.1 до 720 годин. Застосовується спільно з параметром freq. Даний параметр дозволяє розтягнути розсилку в
часі для поступового отримання SMS-повідомлень абонентами.
|
|---|
| freq | Інтервал або частота, з якою потрібно відправляти SMS-розсилку на чергову групу номерів. Кількість
номерів у групі розраховується автоматично на основі параметрів period і freq. Задається в проміжку від 1 до 1440 хвилин.
Без параметра period параметр freq ігнорується.
|
|---|
| flash | Ознака Flash повідомлення, що відображається одразу на екрані телефону.
0 (за замовчуванням) – звичайне повідомлення.
1 – Flash повідомлення.
|
|---|
| bin | Ознака бінарного повідомлення.
0 (за замовчуванням) – звичайне повідомлення.
1 – бінарне повідомлення. У http-запиті потрібно кодувати за допомогою функції urlencode.
2 – бінарне повідомлення, представлене у вигляді шістнадцяткового рядка (hex).
Бінарне повідомлення передається разом з UDH заголовком на початку в параметрі mes, в якому перший байт задає довжину заголовка.
Щоб передати бінарне повідомлення без UDH заголовка, вкажіть нульовий байт на початку повідомлення (00 в hex).
Для можливості передачі параметрів pid і dcs необхідно в кінець бінарного повідомлення додати спеціальну комбінацію
"\n~~~ \ n "(переклад рядка, 3 символу тильди і знову переклад рядка) і потім текст "pid: значеніе1, dcs: значеніе2" з точним збереженням
пробіл.
|
|---|
| push | Ознака WAP-push повідомлення, за допомогою якого можна відправити інтернет-посилання на телефон.
0 (за замовчуванням) – звичайне повідомлення.
1 – wAP-push повідомлення. В параметрі mes необхідно передати посилання і заголовок через переведення рядка.
|
|---|
| hlr | Ознака HLR-запиту для отримання інформації про номер із бази оператора без відправки реального SMS.
0 (за замовчуванням) – звичайне повідомлення.
1 – HLR-запит. Буде виконано HLR-запит для кожного номера телефону в списку. Параметр mes не використовується.
|
|---|
| ping | Ознака спеціального SMS, що не відображається в телефоні, для перевірки номерів на доступність в реальному часі за статусом доставки.
0 (за замовчуванням) – звичайне повідомлення.
1 – ping-sms. Буде надіслано ping-SMS на кожен номер телефону у списку.
Параметр mes не використовується.
|
|---|
| mms | Ознака MMS-повідомлення, за допомогою якого можна передавати текст (txt), зображення різних форматів (jpg, gif, png),
музику (wav, amr, mp3, mid) і відео (mp4, 3gp). Файли передаються в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення.
1 – MMS-повідомлення. Буде надіслано MMS на кожен номер телефону у списку.
|
|---|
| mail | Ознака e-mail повідомлення. Файли, що прикріплюються до повідомлення, передаються методом POST в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення.
1 – e-mail повідомлення.
|
|---|
| soc | Ознака soc-повідомлення, що відправляється користувачам соціальних мереж "Однокласники", "ВКонтакті" або користувачам "Mail.Ru Агент".
0 (за замовчуванням) – звичайне повідомлення.
1 – soc-повідомлення.
|
|---|
| viber | Ознака viber-повідомлення, що відправляється користувачам месенджера Viber.
0 (за замовчуванням) – звичайне повідомлення.
1 – viber-повідомлення.
|
|---|
| tg | При вказівці значення даного параметра рівним 1 буде відправлено telegram-повідомлення з кодом підтвердження, переданим в параметрі mes.
|
|---|
| bot | Ім'я бота, в який необхідно відправити повідомлення. Для telegram має вигляд - "@botname_bot", для whatsapp - "wa:botnumber".
|
|---|
| smsreq | Використовується спільно з параметром bot для telegram. При вказівці даного параметра, система не буде відображати текст повідомлення, відправленого користувачеві і виводити попередження про необхідність підтвердження номера телефону, якщо з моменту останнього підтвердження пройшло більше smsreq днів. Діапазон значень від 10 до 999.
|
|---|
| fileurl | Повний http-адреса файлу для завантаження і передачі в повідомленні. Мінімальний розмір файлу становить 101 байт.
|
|---|
| mes2 | Даний параметр задає варіант повідомлення для пересилання по SMS в режимі автоматичного повтору при недоставці на альтернативні маршрути, наприклад, відправка в месенджери. Для включення автоматичного повтору необхідно в запиті додатково передати прапор fl[5], рівний 1.
|
|---|
| call | Ознака голосового повідомлення. При формуванні голосового повідомлення можна передавати як текст, так і прикріплювати файли.
Файли, що додаються до повідомлення, повинні передаватися методом POST у тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення.
1 – голосове повідомлення.
|
|---|
| voice | Голос, який використовується для озвучування тексту (тільки для голосових повідомлень).
m – чоловічий голос.
m2 – чоловічий голос 2.
m3 (за замовчуванням) - чоловічий голос 3.
m4 – чоловічий голос 4.
w – жіночий голос.
w2 – жіночий голос 2.
w3 – жіночий голос 3.
w4 – жіночий голос 4.
При відправці повідомлень також можливе зазначення мови озвучування тексту у вигляді: "m, en", "w, fr", "w, de" і т. п.
|
|---|
| subj | Тема MMS або e-mail повідомлення. При відправці e-mail вказання теми, тексту і адреси відправника обов'язкове. Для MMS обов'язковим
є указання теми або тексту. Якщо не вказати тему MMS, то в її якості буде використане ім'я відправника, передане в запиті або
те, що використовується за замовчуванням.
|
|---|
| charset | Кодування переданого повідомлення, якщо використовується відмінна від кодування по
замовчування windows-1251. Варіанти: utf-8 і koi8-r.
|
|---|
| cost | Ознака необхідності отримання вартості розсилки.
0 (за замовчуванням) – звичайна відправка.
1 –
додати у відповідь вартість розсилки.
|
|---|
| fmt | Формат відповіді сервера про успішну відправку.
0 – (за замовчуванням) у вигляді рядка (OK - 1 SMS, ID - 1234).
1 – повернути відповідь у вигляді чисел: ID і кількість SMS через кому (1234,1), при cost = 2 ще вартість через
кому (1234,1,1.40), при cost = 3 ще новий баланс клієнта (1234,1,1.40,100.50) , при cost = 1 вартість і кількість
SMS через кому (1.40,1).
2 – відповідь у xml форматі.
3 – відповідь у json форматі.
|
|---|
| list | Список номерів телефонів і відповідних їм повідомлень, розділених двокрапкою або крапкою з комою і
представлений у вигляді:
phones1:mes1
phones2:mes2
...
Рядки розділяються через символ нового рядка (%0A). В якості phones можна вказати кілька номерів телефонів через
кому. Якщо в повідомленні mes потрібно передати символ нового рядка, то вкажіть його через \n. у разі неможливості коригування тексту мультистрокового повідомлення можливе включення спеціального режиму для передачі такого типу повідомлень. Для цього необхідно додатково передавати в запиті параметр nl, рівний 1.
У разі необхідності передачі різних імен відправників (і, можливо, різних часових поясів абонентів (працює тільки для запитів, в яких параметр time представлений у вигляді DDMMYYhhmm або DD.MM.YY hh: mm)) для різних повідомлень можна використовувати наступний формат передачі:
sender1,tz1|phones1:mes1
sender2,tz2|phones2:mes2
...
В даному випадку параметр tz є необов'язковим.
Параметр list дозволяє виконувати множинну розсилку з різними повідомленнями на кілька телефонів одним
http-запитом. Повідомленням у запиті присвоюється єдиний ідентифікатор. Весь параметр повинен бути закодований за
допомогою функції urlencode.
|
|---|
| tpl | ID шаблону, який буде використаний в якості тексту повідомлення. Для використання шаблону необхідно,
щоб параметр mes був порожнім.
|
|---|
| valid | Термін" життя " SMS-повідомлення. Визначає час, протягом якого оператор буде намагатися доставити
повідомлення абоненту. Діапазон від 1 до 24 годин. Також можливо передавати час у форматі чч: мм в діапазоні від 00:01 до 24:00.
|
|---|
Обов'язковими параметрами є login, psw, name, phones і mes або login, psw, name і list.
Опис параметрів, що передаються на Сервер при видаленні, відключенні або отриманні списку розсилок:
| Параметр | Значення
|
|---|
| login | Логін Клієнта.
|
|---|
| psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
|---|
| id | Ідентифікатор розсилки. Повертається Сервером після створення і використовується для подальшої ідентифікації розсилки.
|
|---|
| Додаткові параметри
|
|---|
| start | Дата, з якої потрібно отримати список розсилок. Якщо цей параметр не вказано, повертає список розсилок за останні 2 місяці, але не більше 10. Застосовується спільно з параметром get_all. Формат: 'дд.мм.рррр'.
|
|---|
| end | Дата, до якої потрібно отримати список розсилок. Якщо цей параметр не вказано, то повертається список розсилок до поточної дати, але не більше 10. Застосовується спільно з параметром get_all. Формат: 'дд.мм.рррр'.
|
|---|
Обов'язковими параметрами є login, psw і id.
Після прийняття та обробки даних Сервер повертає Клієнту підтвердження із зазначенням результату обробки.
Всі параметри, які містять спеціальні символи (плюс, пробіл і т. д.), повинні бути закодовані за допомогою функції urlencode для передачі в HTTP-запиті.
Розсилання. Відповідь сервера та коди помилок
Сервер відправляє відповідь у вигляді рядка:
Якщо сталася помилка, то відповідь буде однією із наступних:
При fmt = 0:
- ERROR = N (описание) – для помилок 1,2,3,4,5,9.
При fmt = 1:
- 0,-N - для помилок 1,2,3,4,5,9.
При fmt = 2:
- Для помилок 1,2,3,4,5,9:
<result>
<error>опис</error>
<error_code>N</error_code>
</result> |
При fmt = 3:
- Для помилок 1,2,3,4,5,9:
{
"error": "опис",
"error_code": N
} |
N – номер помилки, може приймати наступні значення:
| Значення | Опис
|
|---|
| 1 | Помилка в параметрах.
|
|---|
| 2 | Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
|---|
| 3 | Помилка збереження запису.
|
|---|
| 4 | IP-адреса тимчасово заблокована через часті помилки у запитах. Докладніше
|
|---|
| 5 | Невірний формат дати.
|
|---|
| 9 | Надсилання більше одного однакового запиту на дії з розсилками протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
|---|
У разі успішної обробки запиту повертається рядок наступного виду:
При створенні розсилки:
- при cost = 0 і fmt = 0: OK, ID - <id>
- при cost = 1 і fmt = 0: OK, ID - <id>, COST - <cost>
- при cost = 0 і fmt = 1: <id>
- при cost = 1 і fmt = 1: <id>,<cost>
- при cost = 0 і fmt = 2:
<result>
<id>id</id>
</result> |
- при cost = 1 і fmt = 2:
<result>
<id>id</id>
<cost>cost</cost>
</result> |
- при cost = 0 і fmt = 3:
- при cost = 1 і fmt = 3:
{
"id": <id>,
"cost": "<cost>"
} |
При відключенні або видаленні розсилки:
- при fmt = 0,1: OK
- при fmt = 2:
- при fmt = 3:
При отриманні інформації про конкретну розсилку (при mail=1 параметр "phones" змінюється на "emails"):
- при fmt = 0: <id>|<name>|<subject>|<repeat_send>|<repeat_cnt>|<created>|<changed>|<need_date>|<last_sent>|<phones>|<message>|<format>|<validity>|<period>|<frequency>|<status>|<sender_id>
- при fmt = 1: <id>;<name>;<subject>;<repeat_send>;<repeat_cnt>;<created>;<changed>;<need_date>;<last_sent>;<phones>;<message>;<format>;<validity>;<period>;<frequency>;<status>;<sender_id>
- при fmt = 2:
<job>
<id>id</id>
<name>name</name>
<subject>subject</subject>
<repeat_send>repeat_send</repeat_send>
<repeat_cnt>repeat_cnt</repeat_cnt>
<created>created</created>
<changed>changed</changed>
<need_date>need_date</need_date>
<last_sent>last_sent</last_sent>
<phones>phones</phones>
<message>message</message>
<format>format</format>
<validity>validity</validity>
<period>period</period>
<frequency>frequency</frequency>
<status>status</status>
<sender_id>sender_id</sender_id>
</job> |
- при fmt = 3:
[
{
"id": <id>,
"name": "<name>",
"subject": "<subject>",
"repeat_send": <repeat_send>,
"repeat_cnt": <repeat_cnt>,
"created": "<created>",
"changed": "<changed>",
"need_date": "<need_date>",
"last_sent": "<last_sent>",
"phones": "<phones>",
"message": "<message>",
"format": <format>,
"validity": <validity>,
"period": "<period>",
"frequency": <frequency>,
"status": <status>,
"cost": "<cost>",
"sms_sent": <sms_sent>,
"sms_ok": <sms_ok>,
"sender_id": "<sender_id>"
}
] |
При отриманні списку розсилок (при mail=1 параметр "phones" змінюється на "emails"):
- при fmt = 0: <id>|<name>|<changed>|<need_date>|<last_sent>|<phones>|<message>|<phones_cnt>|<cost>|<status>|<sender_id>|<format>
- при fmt = 1: <id>;<name>;<changed>;<need_date>;<last_sent>;<phones>;<message>;<phones_cnt>;<cost>;<status>;<sender_id>;<format>
- при fmt = 2:
<sms_jobs>
<job>
<id>id</id>
<name>name</name>
<changed>changed</changed>
<need_date>need_date</need_date>
<last_sent>last_sent</last_sent>
<phones>phones</phones>
<message>message</message>
<phones_cnt>phones_cnt</phones_cnt>
<cost>cost</cost>
<status>status</status>
<sender_id>sender_id</sender_id>
<format>format</format>
</job>
...
</sms_jobs>
|
- при fmt = 3:
[
{
"id": <id>,
"name": "<name>",
"changed": "<changed>",
"need_date": "<need_date>",
"last_sent": "<last_sent>",
"phones": "<phones>",
"message": "<message>",
"phones_cnt": <phones_cnt>,
"cost": "<cost>",
"status": <status>,
"sender_id": "<sender_id>",
"format": <format>,
"sms_sent": <sms_sent>,
"sms_ok": <sms_ok>
},
...
] |
Де:
<id> – ідентифікатор розсилки, переданий клієнтом або призначений Сервером автоматично.
<name> – назва розсилки.
<subject> – тема (для e-mail розсилок).
<repeat_send> – період повтору.
<repeat_cnt> – кількість повторів розсилки.
<created> – дата створення розсилки.
<changed> – дата зміни розсилки.
<need_date> – призначена дата відправки.
<last_sent> – дата останньої відправки.
<phones> (<emails>) – список телефонів (e-mail адрес) одержувачів повідомлень.
<message> – текст повідомлення.
<format> – формат повідомлення.
<validity> – "час життя" повідомлення.
<period> – інтервал відправки повідомлень.
<frequency> – частота відправки повідомлень.
<status> – статус розсилки.
<sender_id> – ім'я відправника.
<phones_cnt> – кількість одержувачів.
<cost> – вартість розсилки.
<sms_sent> – кількість відправлених повідомлень.
<sms_ok> – кількість доставлених повідомлень.Приклади операцій з розсилкамиПриклади:
Створення SMS-розсилки:
https://smsc.ua/sys/jobs.php?add=1&login=alex&psw=123&phones=79999999999&name=Privet&mes=Hello!
Створення розсилки з голосовим повідомленням:
https://smsc.ua/sys/jobs.php?add=1&login=alex&psw=1234567890&phones=79999999999&call=1&voice=w2&name=Privet&mes=Hello!
Створення розсилки e-mail повідомленням на адресу "alex@mysite.com" з темою "Hi" та текстом "Hello!" від відправника "alex2@mysite2.com"
і назвою розсилки "Privet":
https://smsc.ua/sys/jobs.php?add=1&login=alex&psw=123&phones=alex%40mysite.com&mail=1&name=Privet&mes=Hello!&subj=Hi&sender=alex2%40mysite2.com
Створення Viber-розсилки з макросами та автоповторенням по SMS (текст SMS відрізняється від тексту Viber-повідомлення) на кілька номерів (тексти повідомлень необхідно закодувати за допомогою функції urlencode):
https://smsc.ua/sys/jobs.php?add=1&login=alex&psw=123&phones=79999999999,78888888888&name=rassilka1&mes={Ім'я}, це Viber-повідомлення&mes2=це SMS для {Ім'я}&sender=MyViber & fl[5]=1&viber=1
Видалення створеної розсилки з id рівним 701:
https://smsc.ua/sys/jobs.php?del=1&login=alex&psw=123&id=701
Відключення відкладеної розсилки з id рівним 701:
https://smsc.ua/sys/jobs.php?cancel=1&login=alex&psw=123&id=701 |
УПРАВЛІННЯ РОЗСИЛКАМИ
