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

Всі запити потрібно відправляти на 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;

Важливо! Всі приклади JSON у цій документації розбиті на рядки для наочності, але під час реальної роботи з API усі JSON-дані мають бути представлені у вигляді одного рядка. Якщо в якомусь значенні потрібно вставити перехід рядка, використовуйте комбінацію символів \n.

На будь-який коректний 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 використовуватиметься воно. Таким чином, якщо значення параметра співпадає для обох типів повідомлення, то його можна зазначити лише в глоабльних параметрах і не дублювати в локальних.

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

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

Усі транзакційні повідомлення, що відправляються на номери України, повинні відповідати заздалегідь зареєстрованим шаблонам. Якщо при відправці транзакційного повідомлення не буде знайдено відповідний шаблон, то воно буде відхилено з кодом NOT_ALLOWED_MESSAGE_TRANSACTION_PATTERN. Не виключені ситуації, коли шаблон буде знайдений у нас, але Viber з якихось причин не знайде його у себе, в такому випадку повідомлення буде протарифіковано як рекламне. Ми намагаємося виявляти подібні випадки, щоб наші клієнти могли оперативно внести зміни в шаблон і отримати ціну транзакційного повідомлення.

За допомогою параметру file_id ви можете відправляти файли користувачам, наприклад, документи, рахунки, та інше. Для відправки файлу необхідно разом з параметром file_id передати параметр caption, в якому ви можете вказати назву файлу, наприклад "Рахунок.pdf", цей параметр може містити до 25 латинських символів або до 12 кириличних. Параметри тексту, кнопки і зображення повинні бути відсутніми.

Ви також можете використовувати file_id для відправки зображення або посилання на кнопці. Для зображення просто вкажіть file_id відповідного зображення, параметр image_url в такому випадку буде проігнорований. Якщо вказано параметр caption і відсутній параметр action, тоді файл буде відправлений у вигляді посилання на кнопці.

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

{
   "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!"
   }
}

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

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

Відправка файлу у Viber:

{
   "recipients": [
      "380678998668"
   ],
   "viber": {
      "sender": "TurboSMS",
      "file_id": 12345,
      "caption": "Договір.pdf"
   }
}

Відправка файлу у вигляді посилання на кнопці у Viber повідомленні:

{
   "recipients": [
      "380678998668"
   ],
   "viber": {
      "sender": "TurboSMS",
      "text": "Вам виставлено рахунок на суму 1000 гривень відповідно заказу №12345.",
      "file_id": 23456,
      "caption": "Скачати рахунок"
   }
}

Метод sendmulti

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

Даний метод дозволяє надсилати кілька запитів send одним HTTP запитом, заощаджуючи час, який витрачається на підключення до API при кожному запиті. Іншими словами, виклик методу sendmulti з даними для 100 запитів відпрацює швидше, ніж 100 викликів send.

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

{
   "унікальный_ключ_для_запиту_1": {дані_запиту_1},
   "унікальный_ключ_для_запиту_2": {дані_запиту_2},
   ...
   "унікальный_ключ_для_запиту_Х": {дані_запиту_Х}
}

У відповідь сервер поверне дані наступної структури:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": {
      "унікальный_ключ_для_запиту_1": {дані_відповіді_на_запит_1},
      "унікальный_ключ_для_запиту_2": {дані_відповіді_на_запит_2},
      ...
      "унікальный_ключ_для_запиту_Х": {дані_відповіді_на_запит_Х}
   }
}

Структури даних відповіді та запиту повністю ідентичні структурам методу send.

Метод 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",
         "rejected_status": "",
         "click_time": "2020-01-29 10:22:54",
         "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 можна визначити, який канал використовувався для надсилання повідомлення. Для Viber повідомлень також повертається параметр click_time, що містить час натискання на кнопку в повідомленні, або null, якщо на кнопку не натискали.

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

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

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

Модуль chat

Модуль передбачає роботу з Viber чатами.

Метод senders

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

Цей метод повертає масив об'єктів із даними відправників користувача. Тіло запиту порожнє.

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

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 1,
         "name": "TurboSMS",
         "status": "OK",
         "logo_url": "/user-files/viber-logo/0e1/ed0/eb7/5bed39ee1c676789700607.png",
         "start_date": "2020-01-01",
         "reserve": 8400,
         "spent": 1234.56,
         "balance": 7165.44,
         "paid_date": "2023-12-01",
         "2way": 1,
         "recipients": 34567,
         "unread_messages": 7,
         "last_message_date": "2022-10-01 15:34:18"
      },
      {
         "id": 2,
         "name": "Mobibon",
         "status": "OK",
         "logo_url": "/user-files/viber-logo/fc4/163/53a/7c193960f07a63ce553dbd6235bc0a80.png",
         "start_date": "2020-01-01",
         "reserve": 8400,
         "spent": 2345.67,
         "balance": 6054.33,
         "paid_date": "2099-01-01",
         "2way": 0,
         "recipients": 0,
         "unread_messages": 0,
         "last_message_date": ""
      }
   ]
}

Опис значень параметрів відповіді

Метод recipients

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

Цей метод повертає масив одержувачів відправника. Відправника можна передати або у параметрі sender_id, вказавши його id, або у параметрі sender вказати його назву. Так як одержувачів може бути багато, передбачена можливість вибирати обмежену кількість даних із підтримкою пагінації. Використовуйте параметр page, передаючи номер сторінки та rows для кількості даних, що повертаються. За замовчуванням повертається набір із 30 одержувачів, максимальне значення параметра rows — 500. Якщо додати параметр new_only, то будуть повернуті лише ті одержувачі, які мають непрочитані повідомлення, не більше 30 за запит.

Приклади запитів:

{
   "sender_id": 1,
   "page": 10,
   "rows": 50
}

{
   "sender": "TurboSMS",
   "new_only": 1
}

Приклад відповіді:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "chat_id": 1234,
         "number": "380501234567",
         "contact_id": 2345,
         "name": "Василь Гупало",
         "total_messages": 123,
         "unread_messages": 3,
         "last_message_date": "2022-10-03 12:51:38"
      },
      {
         "chat_id": 2345,
         "number": "380672345678",
         "contact_id": 0,
         "name": "",
         "total_messages": 7,
         "unread_messages": 0,
         "last_message_date": "2022-10-02 16:14:41"
      }
   ]
}

Опис значень параметрів відповіді

Метод sessions

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

Цей метод повертає масив даних сесій. У параметрах можна передавати або id чату у chat_id, або id сесії у session_id. Метод також підтримує параметри пагінації.

Приклади запиту:

{
   "chat_id": 1234,
   "rows": 10
}

{
   "session_id": 123321
}
   

Приклад відповіді:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 123456,
         "price": 0.88,
         "started": "2022-10-04 11:51:29",
         "ended": null,
         "sent_messages": 16,
         "unreplied_messages": 2
      },
      {
         "id": 123321,
         "price": 0.88,
         "started": "2022-10-03 09:12:41",
         "ended": "2022-10-04 09:12:41",
         "sent_messages": 31,
         "unreplied_messages": 0
      }
   ]
}

У відповіді повертаються id сесії, її вартість у гривні, яка була знята з балансу відправника або користувача, дати та час початку та кінця дії, а також кількість відправлених та невідповідних поспіль сесійних повідомлень. Якщо час кінця сесії null, то вона ще не завершилася і в ній можна відправляти сесійні повідомлення.

Метод messages

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

Цей метод повертає масив повідомлень чатів. Для отримання повідомлень конкретного чату можна передати його id у параметрі chat_id. Цей метод також підтримує можливість обмежувати кількість даних у відповіді з пагінацією, повідомлення повертаються відсортовані за часом додавання від нових до старих. Якщо вказати параметр new_only, то буде повернено лише непрочитані повідомлення, при цьому параметри пагінації ігноруються і метод поверне все нові повідомлення вказаного чату. Зверніть увагу, що всі непрочитані повідомлення, які будуть повернуті даним методом, автоматично будуть позначені системою як прочитані. Ви також можете передати id повідомлення у параметрі last_message_id, тоді буде повернено масив повідомлень, які йдуть після вказаного, відсортований від старих до нових.

Приклади запитів:

{
   "chat_id": 1234,
   "page": 2,
   "rows": 15
}

{
   "chat_id": 1234,
   "last_message_id": 1000
}

{
   "chat_id": 2345,
   "new_only": 1
}

Приклад відповіді:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 1391,
         "chat_id": 1234,
         "added": "2022-10-03 09:18:52",
         "type": "Outbox",
         "message": "Ваше замовлення відправлено, ТТН 1234567890",
         "status": "Delivered",
         "file_id": 0,
         "file_url": "",
         "file_source": "",
         "button_caption": "",
         "button_action": "",
         "session_id": 123456
      },
      {
         "id": 1248,
         "chat_id": 1234,
         "added": "2022-10-02 18:51:38",
         "type": "Inbox",
         "message": "",
         "status": "Read",
         "file_id": 12387,
         "file_url": "https://turbosms.ua/user-files/f46/ce1/91b/123456.pdf",
         "file_name": "scan.pdf",
         "button_caption": "",
         "button_action": "",
         "session_id": 123456
      },
      {
         "id": 1234,
         "chat_id": 1234,
         "added": "2022-10-02 18:37:12",
         "type": "Outbox",
         "message": "Товар зарезервовано, скачайте рахунок та надішліть скан його оплати",
         "status": "Read",
         "file_id": 0,
         "file_url": "",
         "file_name": "",
         "button_caption": "Скачати рахунок",
         "button_action": "https://turbosms.ua/user-files/f46/ce1/91b/123110.pdf",
         "session_id": 0
      }
   ]
}

Опис значень параметрів відповіді

Метод send

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

Метод надсилання сесійного повідомлення для чату, переданого у параметрі chat_id. Повідомлення можуть містити текст у параметрі message, або файл, data схему якого можна передати в параметрі file_data, вказавши в параметрі file_name назву файлу, яку побачить одержувач повідомлення. Замість data схеми можна передати URL файлу у параметрі file_url.

Приклади запитів:

{
   "chat_id": 1234
   "message": "Вашу оплату отримано, чекайте на інформацію про відправлення замовлення",
}

{
   "chat_id": 1234
   "file_name": "Презентація.pdf",
   "file_data": "data:application/pdf;base64,JVBERi0xLjMKJcTl8uXrp/Og0M....lRU9GCg==",
}

Приклад відповіді:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": {
      "message_id": 17693
   }
}

Модуль user

Модуль передбачає роботу з даними облікового запису користувача.

Метод balance

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

Даний метод повертає залишок коштів на балансі користувача. Тіло запиту порожнє.

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

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": {
         "balance": 12345.67,
      }
   ]
}

Модуль file

Модуль передбачає роботу з файлами користувача.

Метод add

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

Даний метод дозволяє завантажити файл на наш сервер. Можна надіслати файл як у вигляді url, звідки він буде викачаний, так і безпосередньо в тілі запиту в параметрі data, де має бути його вміст у вигляді data схеми згідно RFC 2397 (докладніше). У data схемі вміст файлу може бути передано як у вигляді base64 рядку, так і у не закодованому вигляді. Однак, враховуйте, що при відправці запиту методом GET ви зіткнетеся з обмеженням довжини URL, яке становить 2Кб, тому, при передачі файлу в data, відправляйте запит методом POST.

Приклади запитів:

{
   "url": "https://turbosms.ua/files/news/http-api.png"
}

{
   "data": "data:image/gif;base64,R0lGODlhEgASAIIAAHqIltvp9/L4/+nz/+by/5imtN7s+gAAACH5BAAAAAAALAAAAAASABIAAAhxAAsIHEiwIEEBCBMqXChAIMOHCR1CfChwgIGLGDNmHFBRo0eMHAtYxAgAAEmTF0OOvFjSZEuQHTO2LLkxpkyaNUVqnIkypU0DL1/61Hmy6NCVH3MSSOqRgEACAQxEnSq1alSnBaAG2Mq1K1esBsMSDAgAOw=="
}

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

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": {
       "id": 32895,
       "link": "https://turbosms.ua/public/4ce/14a/c31/32895.jpg",
       "source": "https://turbosms.ua/files/news/http-api.png",
       "size": 12555,
       "created": "2021-01-21 18:00:09"
   }
}

Значення id можна використовувати у Viber розсилках. У параметрі link міститься публічне посилання на файл, по якому його можна відкрити. source — початковий ресурс файлу, який був зазначений при створенні. У size повертається розмір файлу в байтах, а в created — дата його збереження на нашому сервері.

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

На даний час підтримується наступний набір розширень файлів: doc, docx, rtf, dot, dotx, odt, odf, fodt, txt, pdf, xps, pdax, eps, xls, xlsx, ods, fods, csv, xlsm, xltx, jpg, jpeg, png, gif. Усі ці типи файлів підтримуються для відправки у Viber повідомленнях. Спроби додати файли з будь-якими іншими розширеннями повертатимуть код NOT_ALLOWED_FILE_TYPE. Розмір одного файлу не може перевищувати 3Мб.

Метод details

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

Метод повертає деталі файлу по переданому id.

Приклад запиту:

{
   "id": 32895
}

Відповідь даного методу повністю ідентична відповіді методу додавання файлу.

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