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

Пример адреcа вызова:
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.

С помощью параметра 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 — дата его сохранения на нашем сервере.

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

Метод details

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

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

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

{
   "id": 32895
}

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

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