HTTP API для SMS и Viber-рассылок
Для того, чтобы работать с нашим API, вы должны в разделе настроек 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 адрес, куда перейдёт получатель сообщения при нажатии на кнопку. |
| count_clicks | viber | boolean | ![]() |
Флаг статистики переходов (1 - будет вестись статистика, любые другие значения или отсутствие данного параметра - нет). |
| 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!"
}
}
Отправка SMS в указанное время:
{
"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",
"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 получателя не поддерживает приём бизнес сообщений |
Модуль user
Модуль предусматривает работу с данными аккаунта пользователя.
Метод balance
Пример адреcа вызова: https://api.turbosms.ua/user/balance.json
Данный метод возвращает остаток кредитов на балансе пользователя. Тело запроса пустое.
Структура ответа:
{
"response_code": 0,
"response_status": "OK",
"response_result":{
"balance": 12345.67,
}
]
}
Описание кодов обработки запросов
| 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_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 |
| 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 |
| 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 |
| 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 |