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 работает корректно и его можно использовать.

Нумерация запросов

Если вам нужно, чтобы запрос выполнился гарантированно только один раз, вы можете добавить параметр sequence_id, который будет содержать ваш уникальный идентификатор запроса. Данный параметр может содержать до 40 любых символов. Если за последние 30 дней уже выполнялся запрос с таким же идентификатором, то будут возвращены результаты его выполнения, повторно запрос выполняться не будет, а код ответа будет FAILED_DUPLICATE_REQUEST. Параметр не является обязательным, но рекомендуется к использованию при выполнении запросов создания сущностей. Обратите внимание, что идентификатор запроса привязывается к конкретному методу API, т.е. вы можете вызвать другой метод с тем же sequence_id.

Модуль message

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

Метод send

Пример адреcа вызова:
https://api.turbosms.ua/message/send.json

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

Общий вид тела запроса:

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

В зависимости от того, какой тип сообщения нужно отправлять, в теле запроса должны присутствовать параметры viber или sms, или оба, для гибридной отправки. При создании сообщения, в первую очередь, используются значения глобальных параметров, но при необходимости их значения можно переопределить локальными параметрами. Например, можно указать глобальный параметр text и при наличии параметров viber и sms его значение будет использовано и для Viber, и для sms сообщения. Если в параметре sms указать другое значение параметра text, то для sms будет использовано оно. Таким образом, если значение параметра совпадает для обоих типов сообщения, его можно указать только в глобальных параметрах и не дублировать в локальных.

Доступные параметры

Обязательно должен присутствовать параметр recipients или group_ids, либо оба, все дубликаты получателей будут проигнорированы.

Если не указано время отложенной отправки и в создаваемой рассылке не более 5 получателей, то сообщения будут отправлены сразу же, т.е. вы получите ответ только после обработки отправки этих сообщений, это может сделать некоторую задержку в получении ответа. Если вам важно получить ответ как можно скорее, то укажите время отложенной отправки, тогда сообщение попадёт в очередь и будет отправлено другим потоком. Viber сообщения по умолчанию отправляются как рекламные, если не установлен параметр is_transactional.

С помощью параметра file_id вы можете отправлять файлы пользователям, например, документы, счета, и прочее. Для отправки файла необходимо вместе с параметром file_id передать параметр caption, в котором вы можете указать название файла, например "Счёт.pdf", данный параметр может содержать до 25 латинских символов или до 12 кириллических. Параметры текста, кнопки и изображения должны отсутствовать.
Поддерживаются файлы следующих форматов: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, .xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx. Такие сообщения тарифицируются как рекламные.

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

Обратите внимание, что в сообщении с опросом поле text может содержать до 85 символов, а вариант ответа до 50 символов. Опросы тарифицируются как транзакционное сообщение, параметр is_transactional при этом ни на что не влияет и просто игнорируется. Возможно указать от 2 до 10 вариантов ответа.

Карусель товарных карточек

Для отправки сообщения с каруселью карточек товаров нужно передать массив объектов карточек, каждый из которых содержит: заголовок, изображение, надпись и URL основной кнопки, а также текст и URL дополнительной ссылки.

В качестве изображения вы можете использовать image_url или file_id, какой-то из них должен присутствовать обязательно. Рекомендованный размер изображения 215x185 пикселей. Всего в одном сообщении карусели может быть от 2 до 5 карточек товаров, тарификация как за рекламное сообщение.

В ответ на запрос создания сообщения, сервер вернёт данные следующей структуры:

{
   "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"
   ],
   "group_ids": [
      "15",
      "23"
   ],
   "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": "Скачать счёт"
   }
}

Отправка карусели карточек товаров в Viber сообщении:

{
   "recipients": [
      "380678998668"
   ],
   "viber": {
      "sender": "Super FOOD",
      "text": "Только сегодня, в день Вашего рождения, мы дарим Вам одно из блюд, которое Вы заказывали чаще всего:",
      "carousel": [
         {
           "image_url": "https://www.willcookforsmiles.com/wp-content/uploads/2025/02/Avocado-salmon-rice-bowl-in-a-bowl.jpg",
           "title": "Боул с авокадо и лососем",
           "button_caption": "Хочу!",
           "button_url": "https://super-food.com/order/birthday/bowl-avocado-salmon.html",
           "link_caption": "Подробнее",
           "link_url": "https://super-food.com/bowls/bowl-avocado-salmon.html"
         },
         {
           "file_id": 123456,
           "title": "Овощи темпура с креветками",
           "button_caption": "Лучше это!",
           "button_url": "https://super-food.com/order/birthday/tempura-vegetables-shrimps.html",
           "link_caption": "Подробнее",
           "link_url": "https://super-food.com/tempura/tempura-vegetables-shrimps.html"
         },
         {
           "file_id": 234567,
           "title": "Сет драконьих роллов",
           "button_caption": "Однозначно",
           "button_url": "https://super-food.com/order/birthday/set-dragon-rolls.html",
           "link_caption": "Подробнее",
           "link_url": "https://super-food.com/sets/set-dragon-rolls.html"
         }
      ]
   }
}

Отправка Viber сообщения с опросом:

{
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ],
   "group_ids": [
      "15",
      "23"
   ],
   "viber": {
      "sender": "Super Shop",
      "text": "Понравился ли Вам товар, отправленный в последнем заказе?",
      "survey": [
         "😍 Однозначно да",
         "😊 Скорее да, чем нет",
         "🙄 Скорее нет, чем да",
         "😕 Однозначно нет",
         "🤬 Это мой последний заказ у вас!"
      ]
   }
}

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

Метод details

Пример адреcа вызова:
https://api.turbosms.ua/message/details.json

Метод позволяет получить детали созданных сообщений, для этого нужно передать список message_id в виде массива.

Общий вид тела запроса:

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

Структура ответа:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "message_id": "2d80c1c0-5e3c-78c9-134b-2fc4fcbfa0ba",
         "sms": null,
         "viber": null,
         "response_code": 414,
         "response_status": "NOT_ALLOWED_MESSAGE_ID"
      },
      {
         "message_id": "f83f8868-5e46-c6cf-e4fb-615e5a293754",
         "sms": {
            "added": "2022-01-25 12:45:32",
            "start": null,
            "sent": "2022-01-25 12:45:32",
            "updated": "2022-01-25 12:45:37",
            "sender": "TurboSMS",
            "text": "TurboSMS приветствует Вас в SMS!",
            "recipient": "380678998668",
            "status": "Delivered",
            "price": 0.34,
            "segments": 1,
            "ttl": 86400
         },
         "viber": {
            "added": "2022-01-25 12:45:31",
            "start": null,
            "sent": "2022-01-25 12:45:31",
            "updated": "2022-01-25 12:45:32",
            "sender": "TurboSMS",
            "text": "TurboSMS приветствует Вас в Viber!",
            "recipient": "380678998668",
            "message_type": "promotional",
            "status": "Rejected",
            "rejected_status": "SRVC_NOT_VIBER_USER",
            "price": 0,
            "ttl": 3600,
            "caption": "",
            "action": "",
            "file_id": 0,
            "click_time": null,
            "is_transactional": 0
         },
         "response_code": 0,
         "response_status": "OK"
      },
      {
         "message_id": "c51f4301-5e3c-78c9-134b-d1ce1e56a9ff",
         "sms": null,
         "viber": {
            "added": "2022-01-27 17:13:50",
            "start": "2022-01-28 12:00:00",
            "sent": "2022-01-28 12:00:00",
            "updated": "2022-01-28 12:00:17",
            "sender": "TurboSMS",
            "text": "Максим, поздравляем с Днём рождения!",
            "recipient": "380678998668",
            "message_type": "transactional",
            "status": "Read",
            "rejected_status": "",
            "price": 0.36,
            "ttl": 100,
            "caption": "",
            "action": "",
            "file_id": 0,
            "click_time": null,
            "is_transactional": 1
         },
         "response_code": 0,
         "response_status": "OK"
      },
      {
         "message_id": "c51f4301-5e3c-78c9-134b-d1ce1e56afd4",
         "sms": null,
         "viber": {
            "added": "2022-01-27 17:13:50",
            "start": "2022-01-28 12:00:00",
            "sent": "2022-01-28 12:00:00",
            "updated": "2022-01-28 12:00:17",
            "sender": "Super Shop",
            "recipient": "380678998668",
            "message_type": "carousel",
            "text": "Вы уже давно ничего не заказывали, мы соскучились и дарим Вам скидку 10% 🤗",
            "carousel": [
               {
                 "image_url": "https://turbosms.ua/user-files/a67/71c/91b/1545256.jpg",
                 "file_id": 13572,
                 "title": "Боул с авокадо и лососем",
                 "button_caption": "Хочу!",
                 "button_url": "https://super-shop.com/cart/add/bowl-avocado-salmon.html",
                 "button_clicks": 12,
                 "link_caption": "Подробнее",
                 "link_url": "https://super-shop.com/items/bowl-avocado-salmon.html",
                 "link_clicks": 4
               },
               {
                 "image_url": "https://turbosms.ua/user-files/4ba/fc5/91d/15223508.png",
                 "file_id": 123456,
                 "title": "Овощи темпура с креветками",
                 "button_caption": "Лучше это!",
                 "button_url": "https://super-shop.com/cart/add/birthday/tempura-vegetables-shrimps.html",
                 "button_clicks": 17,
                 "link_caption": "Подробнее",
                 "link_url": "https://super-shop.com/items/tempura-vegetables-shrimps.html",
                 "link_clicks": 9
               },
               {
                 "image_url": "https://turbosms.ua/user-files/f46/ce1/91b/123110.jpg",
                 "file_id": 234567,
                 "title": "Сет драконьих роллов",
                 "button_caption": "Однозначно",
                 "button_url": "https://super-shop.com/cart/add/birthday/set-dragon-rolls.html",
                 "button_clicks": 21,
                 "link_caption": "Подробнее",
                 "link_url": "https://super-shop.com/items/set-dragon-rolls.html",
                 "link_clicks": 5
               }
            ],
            "status": "Read",
            "rejected_status": "",
            "price": 0.36,
            "ttl": 100,
            "caption": "",
            "action": "",
            "file_id": 0,
            "click_time": null,
            "is_transactional": 0
         },
         "response_code": 0,
         "response_status": "OK"
      },
      {
         "message_id": "c51f4301-5e3c-78c9-134b-d1ce1e56a3aa",
         "sms": null,
         "viber": {
            "added": "2022-01-27 17:13:50",
            "start": "2022-01-28 12:00:00",
            "sent": "2022-01-28 12:00:00",
            "updated": "2022-01-28 12:00:17",
            "sender": "Super Shop",
            "recipient": "380678998668",
            "text": "Понравился ли Вам товар, отправленный в последнем заказе?",
            "message_type": "survey",
            "survey": [
               "😍 Однозначно да",
               "😊 Скорее да, чем нет",
               "🙄 Скорее нет, чем да",
               "😕 Однозначно нет",
               "🤬 Это мой последний заказ у вас!"
            ],
            "status": "Read",
            "rejected_status": "",
            "price": 0.36,
            "ttl": 100,
            "caption": "",
            "action": "",
            "file_id": 0,
            "click_time": null,
            "is_transactional": 0
         },
         "response_code": 0,
         "response_status": "OK"
      }
   ]
}

В ответе вы получите два объекта: sms и viber, или null, если соответствующий объект не найден. Параметры этих объектов соответствуют параметрам методов message/send и message/status. В параметре start содержится время запланированной отправки, если оно было указано. В параметре segments указано количество сегментов sms, которое влияет на конечную стоимость сообщения.

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

Структура ответа:

{
   "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 сообщение невозможно отправить, в этом поле будет содержаться причина. При успешной отправке в значении будет пустая строка.

Модуль groups

Модуль предусматривает работу с группами номеров получателей, на которые можно отправлять массовые рассылки.

Метод create

Пример адреcа вызова:
https://api.turbosms.ua/groups/create.json

Данный метод создает новую группу номеров получателей. В запросе нужно обязательно указать название группы (до 100 символов). В ответ вы получите id группы, который нужно использовать при дальнейшей работе.

Пример запроса:

{
   "name": "Клиенты Киев"
}

Пример ответа:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": {
      "id": 15,
      "name": "Клиенты Киев",
      "phones_count": 0,
      "added": "2026-02-26 12:00:00",
      "updated": "2026-02-26 12:00:00"
   }
}

Описание значений параметров ответа

Метод update

Пример адреcа вызова:
https://api.turbosms.ua/groups/update.json

Данный метод обновляет параметры существующей группы. Параметр group_id является обязательным, сейчас можно изменить только название группы.

Пример запроса:

{
   "group_id": 15,
   "name": "VIP клиенты"
}

Пример ответа:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": null
}

Метод delete

Пример адреcа вызова:
https://api.turbosms.ua/groups/delete.json

Данный метод удаляет группу получателей. В параметре group_id нужно передать id группы, полученный при вызове метода groups/create.

Пример запроса:

{
   "group_id": 15
}

Пример ответа:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": null
}

Метод list

Пример адреcа вызова:
https://api.turbosms.ua/groups/list.json

Данный метод возвращает массив объектов с данными групп пользователя. Если тело запроса пустое, то будут возвращены данные всех имеющихся групп. Если передать id группы в group_id или её название в параметре name, то будут возвращены данные только переданной группы. Обратите внимание, что данный метод не поддерживает параметры пагинации. Структура объектов в ответе идентична структуре ответа метода groups/create. Если в запросе передать параметр with_phones, то в объектах групп вы также получите массив телефонных номеров.

Примеры запроса:

{
   "group_id": 15
}

{
   "name": "Клиенты Одесса",
   "with_phones": 1
}

Пример ответа:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 23,
         "name": "Клиенты Одесса",
         "phones_count": 3,
         "added": "2026-02-27 13:24:41",
         "updated": "2026-02-29 19:32:28",
         "phones": [
            "380931234567",
            "380961234567",
            "380971234567"
         ]
      }
   ]
}

Пример ответа (список групп):

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 15,
         "name": "VIP клиенты",
         "phones_count": 120,
         "added": "2026-02-26 12:00:00",
         "updated": "2026-02-27 09:40:00"
      },
      {
         "id": 23,
         "name": "Клиенты Одесса",
         "phones_count": 3,
         "added": "2026-02-27 13:24:41",
         "updated": "2026-02-29 19:32:28"
      },
      {
         "id": 27,
         "name": "Клиенты Харьков",
         "phones_count": 83,
         "added": "2026-02-28 10:12:54",
         "updated": "2026-03-01 17:51:14"
      }
   ]
}

Метод addPhones

Пример адреcа вызова:
https://api.turbosms.ua/groups/addPhones.json

Данный метод добавляет переданные в виде массива телефонные номера в группу, указанную в параметре group_id. В ответ вы получите краткий итог в параметре summary, где будут счётчики количества всего, успешно и не успешно обработанных телефонных номеров, а также массив объектов с описанием ошибок в параметре errors. Если все номера успешно обработаны, то в failed будет ноль, а в errors пустой массив. Код ответа на запрос будет SUCCESS_PROCESSED или SUCCESS_PARTIAL_PROCESSED, в зависимости от того, все ли переданные номера были успешно обработаны.

Пример запроса:

{
   "group_id": 15,
   "phones": [
      "380000000000",
      "380501234567",
      "380661234567",
      "380671234567",
      "380751234567",
      "380771234567",
      "380931234567",
      "380961234567",
      "380971234567",
      "380991234567"
   ]
}

Пример ответа:

{
   "response_code": 805,
   "response_status": "SUCCESS_PARTIAL_PROCESSED",
   "response_result": {
      "summary": {
         "group_id": 15,
         "processed": 10,
         "added": 8,
         "failed": 2
      },
      "errors": [
         {
            "phone": "380000000000",
            "response_code": 305,
            "response_status": "INVALID_PHONE"
         },
         {
            "phone": "380961234567",
            "response_code": 433,
            "response_status": "NOT_ALLOWED_GROUP_PHONE_DUPLICATE"
         }
      ]
   }
}

Метод removePhones

Пример адреcа вызова:
https://api.turbosms.ua/groups/removePhones.json

Данный метод удаляет переданные в виде массива телефонные номера из группы, указанной в параметре group_id. Ответ идентичен ответу метода groups/addPhones.

Пример запроса:

{
   "group_id": 15,
   "phones": [
      "380000000000",
      "380661234567",
      "380638998668",
      "380991234567"
   ]
}

Пример ответа:

{
   "response_code": 805,
   "response_status": "SUCCESS_PARTIAL_PROCESSED",
   "response_result": {
      "summary": {
         "group_id": 15,
         "processed": 4,
         "removed": 2,
         "failed": 2
      },
      "errors": [
         {
            "phone": "380000000000",
            "response_code": 305,
            "response_status": "INVALID_PHONE"
         },
         {
            "phone": "380638998668",
            "response_code": 432,
            "response_status": "NOT_ALLOWED_GROUP_PHONE"
         }
      ]
   }
}

Модуль chat

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

Метод senders

Пример адреcа вызова:
https://api.turbosms.ua/chat/senders.json

Данный метод возвращает массив объектов с данными отправителей пользователя. Если тело запроса пустое, то будут возвращены данные всех когда-либо активных отправителей. Если передать id отправителя в sender_id или его название в sender, то будут возвращены данные только переданного отправителя.

Структура ответа:

{
   "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 за запрос. Вы также можете передать массив получателей, данные которых хотите получить, в параметре recipients. Если этот параметр отсутствует, то будут возвращены все получатели переданного отправителя.

Примеры запросов:

{
   "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, вы можете использовать параметры sender_id или sender для идентификации отправителя, а также массив получателей recipients, для которых хотите получить данные. Метод также поддерживает параметры пагинации.

Примеры запроса:

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

{
   "session_id": 123321
}

{
   "sender": "TurboSMS",
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ]
}

Пример ответа:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 123456,
         "sender_id": 1,
         "sender": "TurboSMS",
         "recipient": 380678998668,
         "chat_id": 1234,
         "price": 0.88,
         "started": "2022-10-04 11:51:29",
         "ended": null,
         "sent_messages": 16,
         "unreplied_messages": 2
      },
      {
         "id": 123321,
         "sender_id": 1,
         "sender": "TurboSMS",
         "recipient": 380678998668,
         "chat_id": 1234,
         "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, либо использовать альтернативные параметры sender_id или sender для идентификации отправителя, а также массив получателей recipients, для которых хотите получить данные. Этот метод также поддерживает возможность ограничивать количество данных в ответе с пагинацией, сообщения возвращаются отсортированные по времени добавления, от новых к старым. Если указать параметр new_only, то будут возвращены только непрочитанные сообщения, при этом параметры пагинации игнорируются и метод вернёт все новые сообщения указанного чата. Обратите внимание, что все непрочитанные сообщения, которые будут возвращены данным методом, автоматически будут отмечены системой, как прочитанные. Если такое поведение нежелательно, передайте необязательный параметр keep_unread со значением 1 — тогда возвращённые сообщения останутся непрочитанными. Вы можете также передать id сообщения в параметре last_message_id, тогда будет возвращён массив сообщений, которые следуют после указанного, отсортированный от старых к новым.

Примеры запросов:

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

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

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

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

{
   "sender": "TurboSMS",
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ]
}

Пример ответа:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 1462,
         "sender_id": 1,
         "sender": "Super Shop",
         "recipient": 380678998668,
         "chat_id": 1234,
         "added": "2022-10-09 17:52:29",
         "type": "Inbox",
         "message_id": "",
         "message": "😍 Однозначно да",
         "message_type": "session",
         "status": "Read",
         "file_id": 0,
         "file_url": "",
         "file_name": "",
         "button_caption": "",
         "button_action": "",
         "replied_message_id": 1391,
         "replied_message": "Понравился ли Вам товар, отправленный в последнем заказе?",
         "session_id": 123678
      },
      {
         "id": 1391,
         "sender_id": 1,
         "sender": "Super Shop",
         "recipient": 380678998668,
         "chat_id": 1234,
         "added": "2022-10-08 12:11:31",
         "type": "Outbox",
         "message_id": "50064123-6817-940a-892d-00c54b2bbac9",
         "message": "Понравился ли Вам товар, отправленный в последнем заказе?",
         "message_type": "survey",
         "survey": [
            "😍 Однозначно да",
            "😊 Скорее да, чем нет",
            "🙄 Скорее нет, чем да",
            "😕 Однозначно нет",
            "🤬 Это мой последний заказ у вас!"
         ],
         "status": "Read",
         "file_id": 0,
         "file_url": "",
         "file_name": "",
         "button_caption": "",
         "button_action": "",
         "replied_message_id": 0,
         "replied_message": "",
         "session_id": 0
      },
      {
         "id": 1373,
         "sender_id": 1,
         "sender": "Super Shop",
         "recipient": 380678998668,
         "chat_id": 1234,
         "added": "2022-10-03 09:18:52",
         "type": "Outbox",
         "message_id": "50064123-6817-940a-892d-ffc54b2bba51",
         "message": "Ваш заказ отправлен, ТТН 1234567890",
         "message_type": "transactional",
         "status": "Read",
         "file_id": 0,
         "file_url": "",
         "file_name": "",
         "button_caption": "",
         "button_action": "",
         "replied_message_id": 0,
         "replied_message": "",
         "session_id": 123456
      },
      {
         "id": 1248,
         "sender_id": 1,
         "sender": "Super Shop",
         "recipient": 380678998668,
         "chat_id": 1234,
         "added": "2022-10-02 18:51:38",
         "type": "Inbox",
         "message_id": "",
         "message": "",
         "message_type": "session",
         "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": "",
         "replied_message_id": 1234,
         "replied_message": "Товар зарезервирован, скачайте счёт и отправьте скан его оплаты",
         "session_id": 123456
      },
      {
         "id": 1234,
         "sender_id": 1,
         "sender": "Super Shop",
         "recipient": 380678998668,
         "chat_id": 1234,
         "added": "2022-10-02 18:37:12",
         "type": "Outbox",
         "message_id": "50064123-6817-940a-892d-00c54b2bbac9",
         "message": "Товар зарезервирован, скачайте счёт и отправьте скан его оплаты",
         "message_type": "promotional",
         "status": "Read",
         "file_id": 0,
         "file_url": "",
         "file_name": "",
         "button_caption": "Скачать счёт",
         "button_action": "https://turbosms.ua/user-files/f46/ce1/91b/123110.pdf",
         "replied_message_id": 0,
         "replied_message": "",
         "session_id": 0
      },
      {
         "id": 1234,
         "sender_id": 1,
         "sender": "Super Shop",
         "recipient": 380678998668,
         "chat_id": 1234,
         "added": "2022-10-01 11:57:49",
         "type": "Outbox",
         "message_id": "44064ac3-6817-940a-a97d-16c54b2b8a0f",
         "message_type": "carousel",
         "message": "Вы уже давно ничего не заказывали, мы соскучились и дарим Вам скидку 10% 🤗",
         "carousel": [
            {
              "image_url": "https://turbosms.ua/user-files/a67/71c/91b/1545256.jpg",
              "file_id": 13572,
              "title": "Боул с авокадо и лососем",
              "button_caption": "Хочу!",
              "button_url": "https://super-shop.com/cart/add/bowl-avocado-salmon.html",
              "button_clicks": 12,
              "link_caption": "Подробнее",
              "link_url": "https://super-shop.com/items/bowl-avocado-salmon.html",
              "link_clicks": 4
            },
            {
              "image_url": "https://turbosms.ua/user-files/4ba/fc5/91d/15223508.png",
              "file_id": 123456,
              "title": "Овощи темпура с креветками",
              "button_caption": "Лучше это!",
              "button_url": "https://super-shop.com/cart/add/birthday/tempura-vegetables-shrimps.html",
              "button_clicks": 17,
              "link_caption": "Подробнее",
              "link_url": "https://super-shop.com/items/tempura-vegetables-shrimps.html",
              "link_clicks": 9
            },
            {
              "image_url": "https://turbosms.ua/user-files/f46/ce1/91b/123110.jpg",
              "file_id": 234567,
              "title": "Сет драконьих роллов",
              "button_caption": "Однозначно",
              "button_url": "https://super-shop.com/cart/add/birthday/set-dragon-rolls.html",
              "button_clicks": 21,
              "link_caption": "Подробнее",
              "link_url": "https://super-shop.com/items/set-dragon-rolls.html",
              "link_clicks": 5
            }
         ],
         "status": "Read",
         "file_id": 0,
         "file_url": "",
         "file_name": "",
         "button_caption": "",
         "button_action": "",
         "replied_message_id": 0,
         "replied_message": "",
         "session_id": 0
      }
   ]
}

Описание значений параметров ответа

Метод send

Пример адреcа вызова:
https://api.turbosms.ua/chat/send.json

Метод отправки сессионного сообщения для чата, переданного в параметре chat_id. Как альтернативу параметру chat_id, вы можете использовать параметры sender_id или sender для идентификации отправителя, а также номер телефона получателя в recipient, которому хотите отправить сообщение. Сообщения могут содержать либо текст в параметре 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/png;base64,iVBORw0KGgoAAAANSUhEUgAAABIAAAASCAYAAABWzo5XAAAAwElEQVR4AayPMQ7CMBAET/keHSV1HkWRmgegUOZHlEgUkRU8ltY6WRjkxJE2d7f2Ti7D9TZvPTRYfC7nkx1RRFgC0RxVX9B7NXu+1l0iy9/03QhiqWmaDHmfGXlP/d+NFFRVsKxV0DiO+a6HeD9fiE0VFM+sDJUzd6SfIL8JgXLGk6ogH/KbeF8QahXEIRJEFe+bqiCCyIeYkffUJ1DYNLZXZROIeAiBYq01heIrg2LfDNFHySbQfX7Ysiy7RBbQBwAA//8FpsY7AAAABklEQVQDAFVE4hfSuaVLAAAAAElFTkSuQmCC"
}

Структура ответа:

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

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

Стоит отметить, что при добавлении файла он проверяется на предмет существования, и если такой уже был добавлен ранее, то будут возвращены детали этого файла.

Метод details

Пример адреcа вызова:
https://api.turbosms.ua/file/details.json

Метод возвращает детали файла по переданному id.

Пример запроса:

{
   "id": 32895
}

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

Описание кодов результата обработки запросов