ua

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

.

Для того, чтобы работать с нашим 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.

Важно! Все примеры 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, который будет содержать ваш уникальный идентификатор запроса. Данный параметр может содержать до 32 любых символов. Если за последние 14 дней уже выполнялся запрос с таким же идентификатором, то будут возвращены результаты его выполнения, повторно запрос выполняться не будет, а код ответа будет 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",
      ...
      "получатель_Х"
   ],
   "viber": {
      "локальный_viber_параметр_1": "значение",
      "локальный_viber_параметр_2": "значение",
      ...
      "локальный_viber_параметр_Х": "значение"
   },
   "sms": {
      "локальный_sms_параметр_1": "значение",
      "локальный_sms_параметр_2": "значение",
      ...
      "локальный_sms_параметр_Х": "значение"
   }
}

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

Обратите внимание!

Не устанавливайте таймаут на HTTP запросы отправки сообщений, потому что наш сервер при получении от вас запроса обязательно его обработает полностью, но вы не получите ответа с id сообщений и вероятно будете пытаться отправить сообщение повторно, из-за чего будут создаваться дубликаты уже отправленных сообщений.


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

Параметр Использование Тип данных Обязательное Назначение
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 кириллических. Параметры текста, кнопки и изображения должны отсутствовать.
Поддерживаются файлы следующих форматов: .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, то файл будет отправлен в виде ссылки на кнопке. Такие сообщения тарифицируются как рекламные

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

{
   "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.

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

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

{
   "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",
            "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",
            "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"
      }
   ]
}

В ответе вы получите два объекта: 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

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.

Обратите внимание!

Не устанавливайте таймаут на HTTP запросы отправки сообщений, потому что наш сервер при получении от вас запроса обязательно его обработает полностью, но вы не получите ответа с id сообщений и вероятно будете пытаться отправить сообщение повторно, из-за чего будут создаваться дубликаты уже отправленных сообщений.

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

{
   "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 Аутентификация не пройдена, не верный токен. 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
NOT_ALLOWED_PERMISSION 424 Попытка оправить Viber сообщение в чужой чат. 24.03.2023
NOT_ALLOWED_TEST_NUMBER 425 Viber сообщение от тестового отправителя может быть отправлено только на номер, привязанный к профилю пользователя. 24.08.2024
NOT_ALLOWED_TEST_MESSAGES_LIMIT 426 Достигнут лимит отправленных Viber сообщений от тестового отправителя. 24.08.2024
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
FAILED_DUPLICATE_REQUEST 507 Дублирующий запрос, возвращены результаты предыдущего запроса. 15.09.2024
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

Ошибка