| Протокол SMTP (E-mail)Відправка повідомлення
Для відправки SMS необхідно послати e-mail на адресу
send send.smsc.ua з текстом у форматі:
<login>:<psw>:<id>:<time>,<tz>:<translit>,<format>,<sender>,<test>:<phones>:<mes>
або:
<login>:<psw>:<id>:<time>,<tz>:<translit>,<format>,<sender>,<test>::<list>
Можливе безпосереднє використання нашого SMTP-сервера. Адреса: send.smsc.ua. Авторизація не потрібна.
Лист повинен передаватися простим текстом із зазначенням кодування, за замовчуванням koi8-r. Кодування задається в заголовку Content-Type
(Content-Type: text/plain; charset="CHARSET"). Максимальний розмір листа становить 100 Кб.
У разі відсутності можливості передачі тексту листа з "Content-Type: text/plain" необхідно укласти текст у спеціальні теги "[text]текст листа [/text]".
Опис параметрів, що передаються Серверу :
| Параметр | Значення
|
|---|
| login | Логін Клієнта.
|
|---|
| psw | Пароль клієнта (можна додати або змінити на даний сторінка). При передачі в запиті порожнього значення поля login даний параметр інтерпретується, як API ключ авторизації (apikey).
|
|---|
| phones | Номер або розділений комою або крапкою з комою список номерів мобільних телефонів в міжнародному форматі,
на які відправляється повідомлення. Номери можуть передаватися без знака "+".
Якщо номер переданий без знака "+", то він може бути виправлений автоматичним форматуванням
і приведений до правильного міжнародного формату. Таким чином, деякі
помилки при введенні номерів телефонів можуть бути виправлені автоматично.
Для відключення автовиправлення передайте номер зі знаком "+".
Також можна відправляти повідомлення на групу номерів, вказавши спеціальний код "G<номер группы>".
Повідомлення буде відправлено на всі номери, що належать цій групі. Для E-mail повідомлення передається список e-mail адрес одержувачів. Для telegram в якості одержувача повідомлення можлива вказівка Ніка абонента або його ID у вигляді #ID.
|
|---|
| mes | Текст повідомлення, що відправляється. Максимальний розмір – 1000 символів. Повідомлення при
необхідності буде розбите на кілька SMS, відправлених абоненту і оплачених окремо. Розмір одного
SMS – 160 символів у латиниці або 70 символів у кирилиці. При розбивці повідомлення на кілька SMS в кожну частину
додається заголовок для об'єднання частин в одне повідомлення на телефоні одержувача, і максимальна довжина стає
67 для кирилиці і 153 для латинських букв. У текст повідомлення можна додавати коментарі,
призначені для перегляду відправником історії в особистому кабінеті.
|
|---|
| Додаткові параметри
|
|---|
| id | Ідентифікатор повідомлення. Призначається Клієнтом. Служить для подальшої ідентифікації повідомлення. Якщо не вказувати, то буде призначений автоматично. Не обов'язково унікальний. Ідентифікатор являє собою 32-бітне число в діапазоні від 1 до 2147483647, або рядок довжиною до 40 символів, який складається із латинських букв, цифр і символів ".-_".
|
|---|
| sender | Ім'я відправника, що відображається в телефоні одержувача.
Дозволені англійські букви, цифри, пробіл і деякі символи. Довжина – 11 символів або 15 цифр.
Всі імена реєструються в особистому кабінеті на даній сторінці.
|
|---|
| translit | Ознака того, що повідомлення необхідно перевести у трансліт.
0 (за замовчуванням) – не переводити в трансліт.
1 – перекласти в трансліт у вигляді "translit".
2 – перевести в трансліт у вигляді "mpaHc/Ium".
|
|---|
| 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 або вказано вже минулий час, то повідомлення буде відправлено негайно.
|
|---|
| tz | Часовий пояс, в якому задається параметр time. Вказується щодо московського часу.
Параметр tz може бути як позитивним, так і негативним. Якщо tz дорівнює 0, то буде використаний московський часовий
пояс, якщо ж параметр tz не заданий, то часовий пояс буде взятий із налаштувань клієнта.
|
|---|
| format | Визначає тип SMS-повідомлення.
0 (за замовчуванням) – звичайне текстове повідомлення.
1 – flash-sms. Повідомлення, що відображається відразу на екрані телефону.
2 – wap-push. Повідомлення, що містить посилання на сайт, перший рядок задає посилання, друга-назва.
3 – hLR-запит. Дозволяє отримати інформацію про номер з бази оператора без відправки SMS.
4 – бінарне повідомлення в двійковому вигляді.
5 – бінарне повідомлення, представлене у вигляді шістнадцяткового рядка (hex).
6 – ping-sms. Перевірка номера на доступність відправкою спеціального невидимого SMS.
7 – mms. Повідомлення, що дозволяє передавати текст (txt), зображення різних форматів (jpg, gif, png),
музику (wav, amr, mp3, mid) і відео (mp4, 3gp).
8 – e-mail. Повідомлення електронної пошти. Тема листа вказується в кінці тексту повідомлення через переведення рядка в
вигляді "subj: Тема". Вказівка теми, тексту і e-mail відправника обов'язково.
9 – голосове повідомлення (дзвінок). Голос, який використовується для озвучення, вказується в кінці тексту повідомлення через переведення рядка в
вигляді "voice: Голос". Можливі типи голосів детально описані на даний сторінка.
10 – viber-повідомлення, що відправляється користувачам месенджера Viber.
11 – whatsapp-повідомлення, яке надсилається користувачам месенджера WhatsApp.
12 – soc-повідомлення, що відправляється користувачам соціальних мереж "Однокласники", "ВКонтакте" або користувачам "Mail.Ru Агент".
|
|---|
| test | Вказує на необхідність відправляти у відповідь лист з результатом відправки SMS-повідомлення.
Якщо 0 або не вказано, то відповідь надсилається тільки при помилку в параметрах, якщо 1, то відповідь відправляється в будь-якому випадку.
Параметр використовується для налагодження при початковому налаштуванні сервісу.
|
|---|
| list | Список номерів телефонів і відповідних їм повідомлень, розділених двокрапкою або крапкою з комою і
представлений у вигляді:
phones1:mes1
phones2:mes2
...
Як phones можна вказати кілька номерів телефонів через кому. Якщо в повідомленні mes потрібно передати символ нового рядка, то вкажіть його через \ n. у разі неможливості коригування тексту мультистрокового повідомлення можливе включення спеціального режиму для передачі такого типу повідомлень. Для цього необхідно в параметрі test передати значення, рівне 2.
Параметр list дозволяє виконувати множинну розсилку з різними повідомленнями на кілька телефонів одним
запит. Повідомленнями в запиті присвоюється єдиний ідентифікатор. Деякі параметри (наприклад, subj, voice) передаються
в кінці списку повідомлень list через переклад рядка.
|
|---|
Параметри повинні йти строго в заданому порядку. Обов'язковими є login, psw,
phones і mes. Якщо якийсь необов'язковий параметр відсутній, то двокрапка повинна залишатися.
Приклад (<id>, поле <time>,<tz> і поле <translit>,<format>,<sender>,<test> не вказані):
alex:123::::79999999999:повідомлення
У складеному полі <translit>,<format>,<sender>,<test> будь-який параметр може бути відсутнім,
зберігаючи початкову кому.
Приклади:
alex:psw:::1,1,Alex:79999999999:повідомлення
alex:psw:::1:79999999999:повідомлення
alex:psw:::,1:79999999999:повідомлення
alex:psw:::,1,Alex:79999999999:повідомлення
alex:psw:::,1,,1:79999999999:повідомлення
Для відправки різних типів повідомлень можна скористатися можливістю вказівки спеціальних префіксів на початку або замість тексту повідомлення.
Підтримувані префікси:
| Назва | Опис
|
|---|
| __CALL__: повідомлення | Відправка голосового повідомлення (дзвінка). При відправці голосового повідомлення в кінці тексту можна вказати
спеціальну комбінацію "\n~~~\n"(переклад рядка, 3 символу тильди і знову переклад рядка), після якої передати параметр param,
визначальний деякі характеристики дзвінка (більш детально можна подивитися в опис).
| | __VIBER__: повідомлення | Відправка повідомлення користувачам месенджера Viber.
| | __SOC__: повідомлення | Відправка повідомлення користувачам соціальних мереж "Однокласники", "ВКонтакте" або користувачам "Mail.Ru Агент".
| | __MAIL__: повідомлення | Відправка e-mail повідомлення.
| | __BOT__: повідомлення | Надсилання повідомлення користувачам чат-бота Telegram.
| | __PING__ | Відправка спеціального SMS, що не відображається в телефоні, для перевірки номерів на доступність в реальному часі за статусом доставки.
| | __HLR__ | Ознака HLR-запиту для отримання інформації про номер із бази оператора без відправки реального SMS.
|
Якщо була допущена помилка в параметрах або сталася будь-яка інша помилка, і параметром test був запитаний
відповідь, то він буде наступним:
- ERROR = N (описание) – для помилок 1,2,4,5,9;
- ERROR = N (описание), ID - <id сообщения> – для помилок 3,6,7,8.
N – номер помилки, може приймати наступні значення:
| Значення | Опис
|
|---|
| 1 | Помилка в параметрах.
|
|---|
| 2 | Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
|---|
| 3 | Недостатньо коштів на рахунку Клієнта.
|
|---|
| 4 | IP-адреса тимчасово заблокована через часті помилки у запитах. Докладніше
|
|---|
| 5 | Невірний формат дати.
|
|---|
| 6 | Повідомлення заборонене (за текстом або по імені відправника).
|
|---|
| 7 | Неправильний формат номера телефону.
|
|---|
| 8 | Повідомлення на вказаний номер не може бути доставлене.
|
|---|
| 9 | Відправка більше одного однакового запиту на передачу SMS-повідомлення протягом хвилини.
|
|---|
У разі успішного прийняття повідомлення та запиту відповіді параметром test повертається рядок наступного вигляду:
Де:
<n> - це кількість відправлених SMS, обчислюється як кількість SMS в повідомленні, помножене на кількість
одержувач.
<id> – ідентифікатор повідомлення, переданий Клієнтом або призначений Сервером автоматично.
Сервер не приймає більше двох однакових запитів на відправку SMS-повідомлень протягом
хвилини для захисту від помилок і зациклень в програмі на стороні клієнта для того, щоб знизити навантаження і не витрачати
кошти клієнта, а також не допустити багаторазової відправки повідомлення одному абоненту.
Сервер також блокує надсилання більше 50 повідомлень одному абоненту, які були відправлені з перервою
між повідомленнями менше 2-х хвилин, для захисту від флуду і зайвого списання коштів з рахунку клієнта,
так як багато операторів не пропускають велику кількість повідомлень одному абоненту за короткий проміжок часу.
Відправка HLR-запиту
Для відправки HLR-запиту використовуйте команду звичайної відправки SMS-повідомлення, вказуючи format рівним 3.
Параметр <mes> з текстом повідомлення не використовується і може бути порожнім.
Результат запиту можна отримати за HTTP-протоколом автоматичним викликом обробника або самостійно запросити статус
відправленого SMS-повідомлення спеціальною командою. Так як HLR-запит виконується асинхронно, і результат може повернутися від оператора не відразу,
то при самостійному запиті статусу важливо робити цикл з декількох ітерацій з засипанням (команда sleep).Функція E-mail2smsВ особистому кабінеті Клієнта в "Налаштуваннях користувача"є можливість вказівки списку номерів телефонів, на які
відбуватиметься пересилання у вигляді SMS-повідомлень текстів електронних листів, що прийшли на адресу
ваш_логінsend.smsc.ua.
Ця функція може бути використана, наприклад, для отримання повідомлень на телефон про різні події з
програм або інтернет-сервісів, в яких можлива вказівка тільки адреси E-mail. |
