| Протокол 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 Кб.
Опис параметрів, що передаються Серверу :
| Параметр | Значення
|
|---|
| login | Логін Клієнта.
|
|---|
| psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
|---|
| phones | Номер або розділений комами або крапками з комами список номерів мобільних телефонів в міжнародному форматі,
на які відправляється повідомлення. Номери можуть передаватися без знака "+".
Якщо номер переданий без знака "+", то він може бути виправлений автоматичним форматуванням
і приведено до належного міжнародного формату. Таким чином, деякі
помилки при введенні номерів телефонів можуть бути виправлені автоматично.
Для відключення автоматичного виправлення передайте номер зі знаком "+".
Також можна відправляти повідомлення на групу номерів, вказавши спеціальний код "G<номер группы>".
Повідомлення буде відправлено на всі номери, що належать даній групі. E-mail повідомлення передається список e-mail адрес
одержувачів.
|
|---|
| mes | Текст повідомлення, що надсилається. Максимальний розмір – 1000 символів. Повідомлення
необхідності буде розбито на кілька SMS, відправлених абоненту та оплачені окремо. Розмір одного
SMS – 160 символів у латиниці або 70 символів у кирилиці. При розбивці повідомлення на кілька SMS на кожну частину
додається заголовок для об'єднання частин в одне повідомлення на телефоні одержувача, і максимальна довжина стає
67 для кирилиці і 153 для латинських літер. У текст повідомлення можна додавати коментарі
призначені для перегляду відправником історії у особистому кабінеті.
|
|---|
| Додаткові параметри
|
|---|
| id | Ідентифікатор повідомлення. Призначається Клієнтом. Служить для подальшої ідентифікації повідомлення. Якщо не вказувати, то буде призначений автоматично. Не обов'язково унікальний. Ідентифікатор представляє собою 32-бітове число в діапазоні від до 1 2147483647, або рядок довжиною до 40 символів, що складається з латинських букв, цифр і символів ".-_".
|
|---|
| sender | Ім'я відправника, який відображається в телефоні одержувача.
Можна англійські літери, цифри, пробіл і деякі символи. Довжина – 11 символів або 15 цифр.
Всі імена реєструються в особистому кабінеті на сторінки.
|
|---|
| 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 або вказано вже минулий час, то повідомлення буде відправлено негайно.
|
|---|
| 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.
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 Агент".
| | __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. |
