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

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

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

Все запросы необходимо отправлять на URL вида https://api.turbosms.ua/модуль/метод.формат, где модуль/метод соответствует доступной для вызова команде API, а формат указывает на тип возвращаемых данных. На данный момент ответ поддерживается только в формате JSON, если вам нужен ответ в виде XML документа или любого другого формата данных, обратитесь в нашу службу поддержки, мы добавим его поддержку. Указание формата является не обязательным, но рекомендуем всегда его указывать, чтобы в будущем не возникало проблем из-за смены нами формата по умолчанию. Сейчас форматом по умолчанию является JSON.

С каждым запросом нужно обязательно передавать ключ аутентификации. Его можно передавать несколькими способами:

  • GET-параметром token=AUTH_TOKEN;
  • POST-параметром token=AUTH_TOKEN при наличии заголовка Content-Type: application/x-www-form-urlencoded;
  • HTTP-заголовком Authorization: Basic AUTH_TOKEN;
  • HTTP-заголовком Authorization: Bearer AUTH_TOKEN.

Данные также, могут быть переданы несколькими способами:

  • GET-параметрами (общая длина URL не может быть более 2000 символов);
  • POST-параметрами при наличии заголовка Content-Type: application/x-www-form-urlencoded;
  • POST-запросом, содержащим JSON данные и заголовок Content-Type: application/json;

Обратите внимание, в одном запросе данные можно передавать только одним способом. Например, нельзя передавать часть данных GET параметрами, а другую - в виде JSON.

На любой корректный HTTP запрос API всегда возвращает HTTP код 200. Общий формат ответа следующий:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": null
}
  • response_code - цифровой код результата обработки запроса, имеет значения от 0 до 999;
  • response_status - статус результата обработки запроса, представляет собой сокращённое описание результата;
  • response_result - данные ответа, если предусмотрены методом. Может быть null, объектом или массивом объектов.

Для тестирования состояния API в каждом модуле есть метод ping, который возвращает следующий ответ:

{
   "response_code": 1,
   "response_status": "PONG",
   "response_result": null
}

Если получен такой ответ, значит API работает корректно и его можно использовать.

Модуль message

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

Метод send

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


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

Параметр Использование Тип данных Обязательное Назначение
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 адрес, куда перейдёт получатель сообщения при нажатии на кнопку.
is_transactional viber boolean Флаг транзакционного сообщения (1 - да, любые другие значения или отсутствие данного параметра - нет). Отправка транзакционных сообщений от общего отправителя запрещена.

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

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

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

Отправка Viber в указанное время:

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

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


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

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

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

response_status response_code Описание
OK 0 Запрос обработан успешно.
PONG 1 Успешный результат вызова метода ping.
REQUIRED_TOKEN 103 Отсутствует токен аутентификации.
REQUIRED_CONTENT 104 Отсутствуют данные запроса.
REQUIRED_AUTH 105 Аутентификация не пройдена, не верный токен.
REQUIRED_ACTIVE_USER 106 Пользователь заблокирован, работа с API невозможна до разблокировки.
REQUIRED_MESSAGE_SENDER 200 Отсутствует или пустой параметр отправителя сообщения.
REQUIRED_MESSAGE_TEXT 201 Отсутствует или пустой параметр текста сообщения.
REQUIRED_MESSAGE_RECIPIENT 202 Отсутствует или пустой список получателей сообщения.
REQUIRED_BALANCE 203 Не достаточно кредитов на балансе для создания рассылки.
REQUIRED_MESSAGE_BUTTON 204 Отсутствуют или пустые параметры кнопки в сообщении, когда она обязательна.
REQUIRED_MESSAGE_BUTTON_CAPTION 205 Отсутствует или пустой параметр текста на кнопке в сообщении.
REQUIRED_MESSAGE_BUTTON_ACTION 206 Отсутствует или пустой параметр URL адреса, куда перейдёт получатель сообщения при нажатии на кнопку.
INVALID_REQUEST 300 Неверный запрос, проверьте его структуру и корректность данных.
INVALID_TOKEN 301 Неверный токен аутентификации.
INVALID_MESSAGE_SENDER 302 Неверный отправитель сообщения.
INVALID_START_TIME 303 Неверная дата отложенной отправки сообщения.
INVALID_MESSAGE_TEXT 304 Недопустимое значение текста сообщения. Возвращается если передано не строковое значение или кодировка символов не входит в набор UTF-8.
INVALID_PHONE 305 Недопустимый номер получателя, система не смогла распознать страну и оператора получателя.
INVALID_TTL 306 Недопустимое значение параметра ttl, значение должно быть целочисленным и не представлено в виде строки.
INVALID_MESSAGE_ID 307 Недопустимое значение параметра message_id, неверный формат.
NOT_ALLOWED_MESSAGE_SENDER 400 Не разрешённый отправитель для текущего пользователя.
NOT_ALLOWED_MESSAGE_SENDER_NOT_ACTIVE 401 Отправитель разрешён, но не активирован на данный момент (не оплачено использование в текущем месяце, не завершена регистрация и т.п.).
NOT_ALLOWED_MESSAGE_IMAGE 402 Недопустимый тип файла изображения.
NOT_ALLOWED_START_TIME 403 Недопустимая дата отложенной отправки сообщения (выходит за пределы установленных ограничений).
NOT_ALLOWED_NUMBER_STOPLIST 404 Номер получателя находится в стоплисте (для sms) или в игнорлисте (для Viber), отправка невозможна.
NOT_ALLOWED_RECIPIENTS_LIMIT 405 Недопустимое количество получателей.
NOT_ALLOWED_RECIPIENT_COUNTRY 406 Недопустимая страна получателя. У пользователя не активирована возможность отправлять сообщения получателям данной страны. Для активации такой возможности свяжитесь с нашим отделом поддержки клиентов.
NOT_ALLOWED_RECIPIENT_DUPLICATE 407 Получатель уже присутствует в рассылке, дубликаты игнорируются.
NOT_ALLOWED_MESSAGE_BUTTON_TEXT_LENGTH 408 Текст на кнопке слишком длинный, длопускается не более 30 символов.
NOT_ALLOWED_MESSAGE_TTL 409 Недопустимое значение параметра ttl (выходит за пределы установленных ограничений).
NOT_ALLOWED_MESSAGE_TRANSACTION_CONTENT 410 Недопустимый контент в транзакционном сообщении. В таких сообщениях можно отправлять только текст, а кнопка и изображения запрещены.
NOT_ALLOWED_MESSAGE_DATA 411 Какой-то из параметров имеет недопустимое значение, свяжитесь с нашим отделом поддержки клиентов для выяснения деталей.
NOT_ALLOWED_MESSAGE_TEXT 412 Текст содержит запрещённые фрагменты.
NOT_ALLOWED_MESSAGE_TEXT_LENGTH 413 Превышена допустимая длина текста сообщения.
NOT_ALLOWED_MESSAGE_ID 414 Данные сообщения с переданным message_id недоступны для текущего пользователя.
NOT_ALLOWED_MESSAGE_TRANSACTION_SENDER 415 Запрещено отправлять транзакционные сообщения от общего отправителя.
FAILED_CONVERT_RESULT2JSON 500 Не удалось сконвертировать данные результата в JSON формат, незамедлительно свяжитесь с нашим отделом поддержки клиентов для выяснения деталей.
FAILED_CONVERT_RESULT2XML 501 Не удалось сконвертировать данные результата в XML формат, незамедлительно свяжитесь с нашим отделом поддержки клиентов для выяснения деталей.
FAILED_PARSE_BODY 502 Не удалось распознать тело запроса (неверный формат).
FAILED_SMS_SEND 503 Не удалось отправить SMS сообщение.
FAILED_VIBER_SEND 504 Не удалось отправить Viber сообщение.
FAILED_SAVE_IMAGE 505 Не удалось сохранить изображение.
SUCCESS_MESSAGE_ACCEPTED 800 Сообщения успешно созданы и добавлены в очередь отправки. Некоторые сообщения могут попадать на предварительную модерацию.
SUCCESS_MESSAGE_SENT 801 Сообщения успешно отправлены.
SUCCESS_MESSAGE_PARTIAL_ACCEPTED 802 Сообщения успешно созданы и добавлены в очередь отправки, но некоторые получатели не попали в список рассылки, детали смотрите в ответе.
SUCCESS_MESSAGE_PARTIAL_SENT 803 Сообщения успешно отправлены, но некоторые получатели не попали в список рассылки, детали смотрите в ответе.
FATAL_ERROR 999 Ошибка выполнения запроса, свяжитесь с отделом поддержки для выяснения деталей.


Ошибка