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

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

Налаштування SMS та Viber API

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

Підключення до SMS та Viber 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 адреса, куди перейде отримувач повідомлення, натисканні на кнопку.
file_id viber integer id файлу, повернутий методом file/add.
count_clicks viber boolean Прапорець статистики переходів (1 - буде вестися статистика, будь-які інші значення або відсутність цього параметру - ні).
is_transactional viber boolean Прапорець транзаційного повідомлення (1 - так, будь-які інші значення або відсутність цього параметру - ні). Відправку транзакційних повідомлень від загального відправника заборонено.

Якщо не зазначено час відкладеної відправки, а в розсилці, яка створюється, не більше 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

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

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

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

rejected_status Опис
SRVC_NOT_VIBER_USER Отримувач не зареєстрований у Viber
SRVC_USER_BLOCKED Отримувач заблокував відправника, від імені якого було відправлено повідомлення, або абсолютно усі бізнес повідомлення
SRVC_NO_SUITABLE_DEVICE 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": ""
      }
   ]
}

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

Параметр Опис
id id відправника, яке потрібне для інших методів
name Назва відправника
status Статус відправника (ok - активний, frozen - не активний)
logo_url Шлях до логотипа відправника у нашому домені
start_date Дата початку роботи відправника
reserve Сума, зарезервована для користування відправником у наступних місяцях
spent Сума, витрачена відправником у поточному календарному місяці
balance Сума, що знаходиться на балансі відправника та доступна для відправок
paid_date Дата, до якої вже оплачено відправника
2way Підтримка двостороннього надсилання повідомлень (1 - так, 0 - ні)
recipients Кількість одержувачів (тільки для 2way відправників)
unread_messages Кількість непрочитаних вхідних повідомлень (тільки для 2way відправників)
last_message_date Дата та час останнього повідомлення в чаті (тільки для 2way відправників)

Метод 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"
      }
   ]
}

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

Параметр Опис
chat_id id чату, в якому зберігається листування з цим одержувачем
number Номер телефону одержувача у міжнародному форматі
contact_id id контактної картки у контактній книзі, якщо знайдено
name Ім'я та прізвище в контактній карті, якщо знайдені та заповнені
total_messages Загальна кількість повідомлень у чаті (вхідних та вихідних, надісланих будь-яким способом)
unread_messages Кількість непрочитаних вхідних повідомлень
last_message_date Дата та час останнього повідомлення у чаті

Метод 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
      }
   ]
}

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

Параметр Опис
id id повідомлення, за яким можна відстежувати зміну стану
chat_id id чату, в якому зберігається листування з цим одержувачем
added Дата та час створення повідомлення
type Тип повідомлення (Inbox — вхідне, Outbox — вихідне)
message Текст повідомлення
status Статус доставки повідомлення, аналогічні методу message/status
file_id id відправленого файлу, або 0
file_url URL відправленого файлу
file_name Назва відправленого файлу
button_caption Заголовок на кнопці рекламного повідомлення
button_action Посилання на кнопці рекламного повідомлення
session_id 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
}

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


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

response_status response_code Опис Наявний з
OK 0 Запит оброблено успішно. 25.02.2020
PONG 1 Успішний результат виклику методу ping. 25.02.2020
REQUIRED_TOKEN 103 Відсутній токен аутентифікації. 25.02.2020
REQUIRED_CONTENT 104 Відсутні дані запиту. 25.02.2020
REQUIRED_AUTH 105 Aутентифікація не була пройдена, некоректний токен. 25.02.2020
REQUIRED_ACTIVE_USER 106 Користувача заблоковано, робота з API недоступна до розблокування. 25.02.2020
REQUIRED_VIBER_SESSION 107 Відсутня активна сесія Viber, надсилання сесійного повідомлення неможливе. 27.10.2022
REQUIRED_MESSAGE_SENDER 200 Відсутній або пустий параметр відправника повідомлення. 25.02.2020
REQUIRED_MESSAGE_TEXT 201 Відсутній або пустий параметр тексту повідомлення. 25.02.2020
REQUIRED_MESSAGE_RECIPIENT 202 Відсутній або пустий список отрмимувачів повідомлення. 25.02.2020
REQUIRED_BALANCE 203 Недостатньо коштів на балансі для створення розсилки. 25.02.2020
REQUIRED_MESSAGE_BUTTON 204 Відсутні або пусті параметри кнопки в повідомленні, коли вона обов'язкова. 25.02.2020
REQUIRED_MESSAGE_BUTTON_CAPTION 205 Відсутній або пустий параметр тексту на кнопці в повідомленні. 25.02.2020
REQUIRED_MESSAGE_BUTTON_ACTION 206 Відсутній або пустий параметр URL адреси, куди перейде отримувач, натиснувши на кнопку. 25.02.2020
INVALID_REQUEST 300 Некоректний запит, перевірте його структуру і коректність даних. 25.02.2020
INVALID_TOKEN 301 Некоректний токен аутентифікації. 25.02.2020
INVALID_MESSAGE_SENDER 302 Некоректний відправник повідомлення. 25.02.2020
INVALID_START_TIME 303 Некоректна дата відкладеної відправки повідомлення. 25.02.2020
INVALID_MESSAGE_TEXT 304 Неприпустиме значення тексту повідомлення. Повертається, якщо передано не строкове значення чи кодування символів не входить в набір UTF-8. 25.02.2020
INVALID_PHONE 305 Неприпустимий номер отримувача, система не змогла розпізнати країну та оператора отримувача. 25.02.2020
INVALID_TTL 306 Неприпустиме значення параметра ttl, значення має бути цілочисловим і передано не у вигляді строки. 25.02.2020
INVALID_MESSAGE_ID 307 Неприпустиме значення параметра message_id, некоректний формат. 25.02.2020
INVALID_FILE_ID 308 Неприпустиме значення параметра id при визові методу file/details, некоректний формат. 22.01.2021
INVALID_SENDER_ID 309 Неприпустиме значення параметра sender_id при визові методу chat/recipients, некоректний формат. 27.10.2022
INVALID_CHAT_ID 310 Неприпустиме значення параметра chat_id при визові методів модуля chat, некоректний формат. 27.10.2022
INVALID_SESSION_ID 311 Неприпустиме значення параметра session_id при визові методу chat/session, некоректний формат. 27.10.2022
INVALID_PAGE 312 Неприпустиме значення параметра пагинації page. 27.10.2022
INVALID_ROWS 313 Неприпустиме значення параметра пагинації rows. 27.10.2022
NOT_ALLOWED_MESSAGE_SENDER 400 Недозволений відправник для поточного користувача. 25.02.2020
NOT_ALLOWED_MESSAGE_SENDER_NOT_ACTIVE 401 Відправник дозволений, але наразі не активований (не сплачено використання в поточному місяці, незавершена реєстрація та ін.). 25.02.2020
NOT_ALLOWED_MESSAGE_IMAGE 402 Неприпустимий тип файла зображення. 25.02.2020
NOT_ALLOWED_START_TIME 403 Неприпустима дата відкладеної відпраки повідомлення (виходить за межі встановлених обмежень). 25.02.2020
NOT_ALLOWED_NUMBER_STOPLIST 404 Номер отримувача знаходиться в стоплісті (для sms) або в ігнорлісті (для Viber), відравка неможлива. 25.02.2020
NOT_ALLOWED_RECIPIENTS_LIMIT 405 Неприпустима кількість отримувачів. 25.02.2020
NOT_ALLOWED_RECIPIENT_COUNTRY 406 Неприпустима країна отримувача. У користувача не активована можливість відправляти повідомлення отримувачам цієї країни. Для активації такої можливості зв'яжіться з нашим відділом підтримки клієнтів. 25.02.2020
NOT_ALLOWED_RECIPIENT_DUPLICATE 407 Отримувача вже включено до розсилки, дублікати ігноруються. 25.02.2020
NOT_ALLOWED_MESSAGE_BUTTON_TEXT_LENGTH 408 Текст на кнопці занадто довгий, длопускаєтся не більше ніж 30 символів. 25.02.2020
NOT_ALLOWED_MESSAGE_TTL 409 Неприпустиме значення параметра ttl (виходить за межі встановлених обмежень). 25.02.2020
NOT_ALLOWED_MESSAGE_TRANSACTION_CONTENT 410 Неприпустимий контент в транзакційному повідомленні. В таких повідомленнях можна надсилати лише текст, а кнопка та зображення заборонені. 25.02.2020
NOT_ALLOWED_MESSAGE_DATA 411 Якийсь з параметрів має неприпустиме значення, зв'яжіться з нашим відділом підтримки клієнтів для уточнення деталей. 25.02.2020
NOT_ALLOWED_MESSAGE_TEXT 412 Текст містить заборонені фрагменти. 25.02.2020
NOT_ALLOWED_MESSAGE_TEXT_LENGTH 413 Перевищена допустима довжина тексту повідомлення. 25.02.2020
NOT_ALLOWED_MESSAGE_ID 414 Дані повідомлення з переданим message_id недоступні для поточного користувача. 25.02.2020
NOT_ALLOWED_MESSAGE_TRANSACTION_SENDER 415 Заборонено надсилати транзакційні повідомлення від загального відправника. 25.02.2020
NOT_ALLOWED_MESSAGE_TRANSACTION_PATTERN 416 Не знайдено шаблон, відповідний переданому транзакційному повідомленню. 18.12.2020
NOT_ALLOWED_FILE_ID 417 Файл з переданим id не існує або недоступний для поточного користувача. 22.01.2021
NOT_ALLOWED_FILE_EMPTY 418 Зазначений завантажуваний файл не знайдений або порожній. 22.01.2021
NOT_ALLOWED_FILE_TYPE 419 Непідтримуваний тип файлу. 22.01.2021
NOT_ALLOWED_FILE_SIZE 420 Розмір файлу перевищує максимально допустимий розмір 3Мб. 22.01.2021
NOT_ALLOWED_MESSAGE_TRAFFIC_TYPE 421 Відправник не підтримує відправку повідомлення вказаного типу. 03.10.2022
NOT_ALLOWED_SESSION_OUTBOX_LIMIT 422 Заборонено надсилати більше ніж 5 сесійних повідомлень поспіль без відповіді отримувача. 27.10.2022
NOT_ALLOWED_FILE_NAME_LENGTH 423 Ім'я файлу у Viber повідомленні занадто довге, допускається не більше 25 символів. 27.10.2022
FAILED_CONVERT_RESULT2JSON 500 Не вдалося зконвертувати дані результату в JSON формат, негайно зв'яжіться з нашим відділом підтримки клієнтів для уточнення деталей. 25.02.2020
FAILED_CONVERT_RESULT2XML 501 Не вдалося зконвертувати дані результату в XML формат, негайно зв'яжіться з нашим відділом підтримки клієнтів для уточнення деталей. 25.02.2020
FAILED_PARSE_BODY 502 Не вдалося розпізнати тіло запиту (некоректний формат). 25.02.2020
FAILED_SMS_SEND 503 Невдалося надіслати SMS повідомлення. 25.02.2020
FAILED_VIBER_SEND 504 Не вдалося надіслати Viber повідомлення. 25.02.2020
FAILED_SAVE_IMAGE 505 Не вдалося зберегти зображення. 25.02.2020
FAILED_SAVE_FILE 506 Не вдалося зберегти файл. 22.01.2021
SUCCESS_MESSAGE_ACCEPTED 800 Повідомлення успішно створені і додані в чергу на відправку. Деякі повідомлення можуть потрапляти на попередню модерацію. 25.02.2020
SUCCESS_MESSAGE_SENT 801 Повідомлення успішно надіслані. 25.02.2020
SUCCESS_MESSAGE_PARTIAL_ACCEPTED 802 Повідомлення успішно створені і додані в чергу на відправку, однак деякі отримувачі не потрапили до списку розсилки, деталі дивіться у відповіді. 25.02.2020
SUCCESS_MESSAGE_PARTIAL_SENT 803 Повідомлення успішно надіслані, однак деякі отримувачі не потрапили до списку розсилки, деталі дивіться у відповіді. 25.02.2020
FATAL_ERROR 999 Помилка виконання запиту, зв'яжіться з відділом підтримки для уточнення деталей. 25.02.2020


Ошибка