Меню
Шлюз для автоматизації сповіщення

HTTP API для SMS та Viber-розсилок

Для того, щоб почати працювати з нашим API, вам необхідно в розділі налаштувань шлюзу поставити галочку "HTTP API" у полі «Способи підключення». Після цього буде створено унікальний ключ аутентифікації, який можна буде змінити в будь-який час.

Всі запити потрібно відправляти на URL типу https://api.turbosms.ua/модуль/метод.формат, де модуль/метод відповідає доступній для виклику команді API, а формат вказує на тип даних, які повертатимуться. Зараз відповідь підтримується лише у форматі JSON, якщо вам потрібна відповідь у вигляді XML документу чи будь-якогму іншому форматі даних, зверніться до нашої служби підтримки і ми додамо його підтримку. Зазначення формату не є обов'язковим, однак ми рекомендуємо завжди вказувати його, щоб в майбутньому уникнути проблем через зміну нами формату за замовчуванням. Наразі форматом за замовчуванням є JSON.

З кожним запитом необхідно обов'язково передавати ключ аутентифікації. Це можна зробити кількома способами:

  • GET-параметром token=AUTH_TOKEN;
  • POST-параметром token=AUTH_TOKEN при наявності заголовка Content-Type: application/x-www-form-urlencoded;
  • HTTP-заголовком Authorization: Basic AUTH_TOKEN;
  • HTTP-заголовком Authorization: Bearer AUTH_TOKEN.

Дані також можна передавати кількома способами:

  • GET-параметрами (загальна довжина URL не може бути більшою, ніж 2000 символів);
  • POST-параметрами при наявності заголовка Content-Type: application/x-www-form-urlencoded;
  • POST-запитом, що містить JSON дані та заголовок Content-Type: application/json;

Зверніть увагу, в одному запиті дані можна передавати тільки одним способом. Наприклад, не можна передавати частину даних GET параметрами, а іншу - у вигляді JSON.

На будь-який коректний HTTP запит API завжди повертає HTTP код 200. Загальний формат відповіді виглядає таким чином:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": null
}
  • response_code - цифровий код результату обробки запиту, має значення від 0 до 999;
  • response_status - статус результату обробки запиту, виглядає як скорочений опис результату;
  • response_result - дані відповіді, якщо передбачені методом. Може бути null, об'єктом чи масивом об'єктів.

Для тестування стану API в кожному модулі є метод ping, який повертає наступну віповідь:

{
   "response_code": 1,
   "response_status": "PONG",
   "response_result": null
}

Якщо отримано таку відповідь, це означає, що API працює коректно і його можна використовувати.

Модуль message

Модуль передбачає роботу з повідомленнями, такими як створення розсилок, їх відправка та перевірка статусів доставки. Функціонал буде з часом розширюватись.

Метод send

Приклад адреси виклику: https://api.turbosms.ua/message/send.json

Метод дозволяє надсилати SMS і Viber повідомлення, а також підтримує гібридну Viber відправку (якщо повідомлення не було доставлено в Viber, воно автоматично надсилається у вигляді SMS).

Загальний вигляд тіла запиту:

{
   "глобальний_параметр_1": "значення",
   "глобальний_параметр_2": "значення",
   ...
   "глобальний_параметр_Х": "значення",
   "recipients":[
      "отримувач_1",
      "отримувач_2",
      ...
      "отримувач_Х"
   ],
   "viber":{
      "локальний_viber_параметр_1": "значення",
      "локальний_viber_параметр_2": "значення",
      ...
      "локальний_viber_параметр_Х": "значення"
   },
   "sms":{
      "локальний_sms_параметр_1": "значення",
      "локальний_sms_параметр_2": "значення",
      ...
      "локальний_sms_параметр_Х": "значення"
   }
}

Залежно від того, який тип повідомлення необхідно надіслати, в тілі запиту повинні бути присутні параметри viber або sms, або обидва, для гибридної відправки. При створенні повідомлення, спершу використовуються значення глобальних параметрів, але за необхідності їх значення можна перевизначити локальними параметрами. Наприклад, можна вказати глобальний параметр text і за наявності параметрів viber і sms, його значення використовуватиметься як для Viber, так і для sms повідомлення. Якщо в параметрі sms вказати інше значення параметра text, то для sms використовуватиметься воно. Таким чином, якщо значення параметра співпадає для обох типів повідомлення, то його можна зазначити лише в глоабльних параметрах і не дублювати в локальних.


Доступні параметри

Параметр Застосування Тип даних Обов'язкове Призначення
sender sms і viber string(20) Ім'я відправника, від якого буде надіслано повідомлення (альфаім'я для SMS або відправник для Viber). Відправник повинен бути активованим у Вашому аккаунті.
start_time sms і viber datetime Дата і час відкладеної відправки, підтримує безліч ISO форматів, рекомендовано викристовувати формат РРРР-ММ-ДД ГГ:ХХ. Допускається зазначення дати, що не перевищує 14 днів від поточного моменту. Не передавайте цей параметр, якщо повідомлення необхідно надіслати негайно.
start_date sms і viber datetime Синонім параметра start_time, доданий для зручності.
text sms і viber string(1000) Текст повідомлення. Для Viber може містити до 1000 символів, для SMS — 1521 символ латиницею або 661 символ кириличного тексту (10 сегментів). Підтримуються символи кодування UTF-8.
recipients sms і viber array Отримувачі повідомлення, зазначаються у міжнародному форматі (380ХХХХХХХХХ). Параметр повинен завжди передаватися у вигляді масиву, навіть якщо отримувач лише один. Допускаєтся не більше ніж 5000 отримувачів в одному запиті.
is_flash sms boolean Прапорець flash повідомлення (1 - так, будь-які інші значення або відсутність цього параметру - ні).
ttl viber integer Термін дії повідомлення, протягом якого воно буде доставлятися. Якщо повідомлення не було доставлено по закінченню цього часу, воно вважатиметься недоставленим. Зазначається в секундах, можливі значення від 60 до 86400, за замовчуванням 3600.
image_url viber string URL адреса зображення, яке відображатиметься в повідомленні.
caption viber string Текст на кнопці в повідомленні.
action viber string URL адреса, куди перейде отримувач повідомлення, натисканні на кнопку.
is_transactional viber boolean Прапорець транзаційного повідомлення (1 - так, будь-які інші значення або відсутність цього параметру - ні). Відправку транзакційних повідомлень від загального відправника заборонено.

Якщо не зазначено час відкладеної відправки, а в розсилці, яка створюється, не більше 5 отримувачів, то повідомлення будуть надіслані одразу ж. Viber повідомлення надсилаються за замовчуванням як рекламні, якщо параметр is_transactional не вставлено.

У відповідь на запит створення повідомлення, сервер поверне дані наступної структури:

{
   "response_code": 802,
   "response_status": "SUCCESS_MESSAGE_PARTIAL_ACCEPTED",
   "response_result":[
      {
         "phone": "отримувач_1",
         "response_code": 406,
         "message_id": null,
         "response_status": "NOT_ALLOWED_RECIPIENT_COUNTRY"
      },
      {
         "phone": "отримувач_2",
         "response_code": 0,
         "message_id": "f83f8868-5e46-c6cf-e4fb-615e5a293754",
         "response_status": "OK"
      }
   ]
}

Тут, глобальні параметри response_code та response_status містять загальний результат обробки запиту, а в параметрі response_result повертається масив об'єктів, кожен з яких містить результат обробки конкретного отримувача з запиту. В значенні параметра message_id міститься унікальний ідентифікатор повідомлення, згідно з яким Ви можете актуалізувати статус доставки. Якщо відправити повідомлення цьому отримувачеві неможливо, то параметр message_id матиме значення null, а в параметрах response_code та response_status міститиметься інформація про помилку, що виникла.

Приклади даних надсилання повідомлень

Відправка SMS, JSON POST запит:

{
   "recipients":[
      "380678998668",
      "380503288668",
      "380638998668"
   ],
   "sms":{
      "sender": "TurboSMS",
      "text": "TurboSMS вітає Вас!"
   }
}

Ці ж самі дані, GET запит:

https://api.turbosms.ua/message/send.json?recipients[0]=380678998668&recipients[1]=380503288668&recipients[2]=380638998668&sms[sender]=TurboSMS&sms[text]=TurboSMS+%D0%B2%D1%96%D1%82%D0%B0%D1%94+%D0%92%D0%B0%D1%81%21&token=AUTH_TOKEN

Відправка Viber:

{
   "recipients":[
      "380678998668",
      "380503288668",
      "380638998668"
   ],
   "viber":{
      "sender": "TurboSMS",
      "text": "TurboSMS вітає Вас!"
   }
}

Гібридна відправка Viber:

{
   "recipients":[
      "380678998668",
      "380503288668",
      "380638998668"
   ],
   "viber":{
      "sender": "Viber TurboSMS",
      "text": "TurboSMS вітає Вас в Viber!"
   },
   "sms":{
      "sender": "TurboSMS",
      "text": "TurboSMS вітає Вас в SMS!"
   }
}

Відправка Viber у вказаний час:

{
   "start_time": "2020-03-08 10:00",
   "recipients":[
      "380678998668"
   ],
   "sms":{
      "sender": "TurboSMS",
      "text": "Максиме, вітаємо з Днем народження!",
   }
}

Метод status

Приклад адреcи виклику: https://api.turbosms.ua/message/status.json

Метод дозволяє отримати інформацію про статус доставки повідомлення, варто лише передати список message_id у вигляді масива.

Загальний вигляд тіла запиту:

{
   "messages": [
      "2d80c1c0-5e3c-78c9-134b-2fc4fcbfa0ba",
      "f83f8868-5e46-c6cf-e4fb-615e5a293754",
      "c51f4301-5e3c-78c9-134b-d1ce1e56a9ff",
      "2d8148d2-5e3c-78c9-134b-4cc6a0ef7898"
   ]
}

Структура відповіді:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result":[
      {
         "message_id": "2d80c1c0-5e3c-78c9-134b-2fc4fcbfa0ba",
         "response_code": 414,
         "response_status": "NOT_ALLOWED_MESSAGE_ID"
      },
      {
         "message_id": "f83f8868-5e46-c6cf-e4fb-615e5a293754",
         "response_code": 0,
         "recipient": "отримувач_2",
         "sent": "2020-01-29 10:19:21",
         "updated": "2020-01-29 10:21:32",
         "status": "Read",
         "type": "viber",
         "response_status": "OK"
      },
      {
         "message_id": "c51f4301-5e3c-78c9-134b-d1ce1e56a9ff",
         "response_code": 0,
         "recipient": "отримувач_3",
         "sent": null,
         "updated": "2020-01-29 18:27:34",
         "status": "Queued",
         "type": "sms",
         "response_status": "OK"
      }
   ]
}

В параметрі sent міститься час фактичного надсилання повідомлення. Якщо значення становить null, це означає, що повідомлення все ще знаходиться в черзі і буде надіслане пізніше. Параметр updated відображає час оновлення статусу доставки. За параметром type можна визначити, який канал використовувався для надсилання повідомлення.


Опис значень поля status

status Опис
Queued Повідомлення взято в обробку і буде надіслано
Accepted Повідомлення надіслано в мобільну мережу, але відповідь від оператора ще не оброблена
Sent Повідомлення надіслано і очікується його доставка
Delivered Повідомлення доставлено отрмувачую
Read Повідомлення прочитано отримувачем
Expired Сплив термін дії повідомлення, за який воно повинне було надіслатися
Undelivered Не доставлено
Rejected Повідомлення відхилено
Unknown Невідомий статус
Failed Неможливо відправити повідомлення
Cancelled Відправка скасована і кредити було повернуто на баланс

Опис кодів обробки запитів

response_status response_code Опис
OK 0 Запит оброблено успішно.
PONG 1 Успішний результат виклику методу ping.
REQUIRED_TOKEN 103 Відсутній токен аутентифікації.
REQUIRED_CONTENT 104 Відсутні дані запиту.
REQUIRED_AUTH 105 Aутентифікація не була пройдена, некоректний токен.
REQUIRED_ACTIVE_USER 106 Користувача заблоковано, робота з API недоступна до розблокування.
REQUIRED_MESSAGE_SENDER 200 Відсутній або пустий параметр відправника повідомлення.
REQUIRED_MESSAGE_TEXT 201 Відсутній або пустий параметр тексту повідомлення.
REQUIRED_MESSAGE_RECIPIENT 202 Відсутній або пустий список отрмимувачів повідомлення.
REQUIRED_BALANCE 203 Недостатньо кредитів на балансі для створення розсилки.
REQUIRED_MESSAGE_BUTTON 204 Відсутні або пусті параметри кнопки в повідомленні, коли вона обов'язкова.
REQUIRED_MESSAGE_BUTTON_CAPTION 205 Відсутній або пустий параметр тексту на кнопці в повідомленні.
REQUIRED_MESSAGE_BUTTON_ACTION 206 Відсутній або пустий параметр URL адреси, куди перейде отримувач, натиснувши на кнопку.
INVALID_REQUEST 300 Некоректний запит, перевірте його структуру і коректність даних.
INVALID_TOKEN 301 Некоректний токен аутентифікації.
INVALID_MESSAGE_SENDER 302 Некоректний відправник повідомлення.
INVALID_START_TIME 303 Некоректна дата відкладеної відправки повідомлення.
INVALID_MESSAGE_TEXT 304 Недопустиме значення тексту повідомлення. Повертається, якщо передано не строкове значення чи кодування символів не входить в набір UTF-8.
INVALID_PHONE 305 Недопустимий номер отримувача, система не змогла розпізнати країну та оператора отримувача.
INVALID_TTL 306 Недопустиме значення параметра ttl, значення має бути цілочисловим і передано не у вигляді строки.
INVALID_MESSAGE_ID 307 Недопустиме значення параметра message_id, некоректний формат.
NOT_ALLOWED_MESSAGE_SENDER 400 Недозволений відправник для поточного користувача.
NOT_ALLOWED_MESSAGE_SENDER_NOT_ACTIVE 401 Відправник дозволений, але наразі не активований (не сплачено використання в поточному місяці, незавершена реєстрація та ін.).
NOT_ALLOWED_MESSAGE_IMAGE 402 Недопустимий тип файла зображення.
NOT_ALLOWED_START_TIME 403 Недопустима дата відкладеної відпраки повідомлення (виходить за межі встановлених обмежень).
NOT_ALLOWED_NUMBER_STOPLIST 404 Номер отримувача знаходиться в стоплісті (для sms) або в ігнорлісті (для Viber), відравка неможлива.
NOT_ALLOWED_RECIPIENTS_LIMIT 405 Недопустима кількість отримувачів.
NOT_ALLOWED_RECIPIENT_COUNTRY 406 Недопустима країна отримувача. У користувача не активована можливість відправляти повідомлення отримувачам цієї країни. Для активації такої можливості зв'яжіться з нашим відділом підтримки клієнтів.
NOT_ALLOWED_RECIPIENT_DUPLICATE 407 Отримувача вже включено до розсилки, дублікати ігноруються.
NOT_ALLOWED_MESSAGE_BUTTON_TEXT_LENGTH 408 Текст на кнопці занадто довгий, длопускаєтся не більше ніж 30 символів.
NOT_ALLOWED_MESSAGE_TTL 409 Недопустиме значення параметра ttl (виходить за межі встановлених обмежень).
NOT_ALLOWED_MESSAGE_TRANSACTION_CONTENT 410 Недопустимий контент в транзакційному повідомленні. В таких повідомленнях можна надсилати лише текст, а кнопка та зображення заборонені.
NOT_ALLOWED_MESSAGE_DATA 411 Якийсь з параметрів має недопустиме значення, зв'яжіться з нашим відділом підтримки клієнтів для уточнення деталей.
NOT_ALLOWED_MESSAGE_TEXT 412 Текст містить заборонені фрагменти.
NOT_ALLOWED_MESSAGE_TEXT_LENGTH 413 Перевищена допустима довжина тексту повідомлення.
NOT_ALLOWED_MESSAGE_ID 414 Дані повідомлення з переданим message_id недоступні для поточного користувача.
NOT_ALLOWED_MESSAGE_TRANSACTION_SENDER 415 Заборонено надсилати транзакційні повідомлення від загального відправника.
FAILED_CONVERT_RESULT2JSON 500 Не вдалося зконвертувати дані результату в JSON формат, негайно зв'яжіться з нашим відділом підтримки клієнтів для уточнення деталей.
FAILED_CONVERT_RESULT2XML 501 Не вдалося зконвертувати дані результату в XML формат, негайно зв'яжіться з нашим відділом підтримки клієнтів для уточнення деталей.
FAILED_PARSE_BODY 502 Не вдалося розпізнати тіло запиту (некоректний формат).
FAILED_SMS_SEND 503 Невдалося надіслати SMS повідомлення.
FAILED_VIBER_SEND 504 Не вдалося надіслати Viber повідомлення.
FAILED_SAVE_IMAGE 505 Не вдалося зберегти зображення.
SUCCESS_MESSAGE_ACCEPTED 800 Повідомлення успішно створені і додані в чергу на відправку. Деякі повідомлення можуть потрапляти на попередню модерацію.
SUCCESS_MESSAGE_SENT 801 Повідомлення успішно надіслані.
SUCCESS_MESSAGE_PARTIAL_ACCEPTED 802 Повідомлення успішно створені і додані в чергу на відправку, однак деякі отримувачі не потрапили до списку розсилки, деталі дивіться у відповіді.
SUCCESS_MESSAGE_PARTIAL_SENT 803 >Повідомлення успішно надіслані, однак деякі отримувачі не потрапили до списку розсилки, деталі дивіться у відповіді.
FATAL_ERROR 999 Помилка виконання запиту, зв'яжіться з відділом підтримки для уточнення деталей.


Ошибка