Для того, чтобы работать с нашим API, вы должны в разделе настроек API отметить пункт "HTTP API" в блоке «Способы подключения». После этого будет создан уникальный ключ аутентификации, который можно сменить в любое время.
Все запросы необходимо отправлять на URL вида https://api.turbosms.ua/модуль/метод.формат, где модуль/метод соответствует доступной для вызова команде API, а формат указывает на тип возвращаемых данных. На данный момент ответ поддерживается только в формате JSON, если вам нужен ответ в виде XML документа или любого другого формата данных, обратитесь в нашу службу поддержки, мы добавим его поддержку. Указание формата является не обязательным, но рекомендуем всегда его указывать, чтобы в будущем не возникало проблем из-за смены нами формата по умолчанию. Сейчас форматом по умолчанию является JSON.
С каждым запросом нужно обязательно передавать ключ аутентификации. Его можно передавать несколькими способами:
Данные также, могут быть переданы несколькими способами:
Обратите внимание, в одном запросе данные можно передавать только одним способом. Например, нельзя передавать часть данных GET параметрами, а другую - в виде JSON.
Важно! Все примеры JSON в этой документации разбиты на строки для наглядности, но при реальной работе с API все JSON данные должны быть представлены в виде одной строки. Если в каком-то значении нужно вставить перевод строки, используйте комбинацию символов \n.
На любой корректный HTTP запрос API всегда возвращает HTTP код 200. Общий формат ответа следующий:
{
"response_code": 0,
"response_status": "OK",
"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.
Модуль предусматривает работу с сообщениями, такую как создание рассылок, их отправка и проверка статусов доставки. Функционал будет расширяться.
Пример адре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": "Скачать счёт"
}
}
Пример адре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.
Пример адре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, которое влияет на конечную стоимость сообщения.
Пример адре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 | Описание |
---|---|
Queued | Сообщение принято в обработку и будет отправлено |
Accepted | Сообщение отправлено в мобильную сеть, но ещё не обработан ответ от оператора |
Sent | Сообщение отправлено и ожидается его доставка |
Delivered | Сообщение доставлено получателю |
Read | Сообщение прочитано получателем |
Expired | Истек срок сообщения, за который оно должно было доставиться |
Undelivered | Не доставлено |
Rejected | Сообщение отклонено |
Unknown | Неизвестный статус |
Failed | Невозможно отправить сообщение |
Cancelled | Отправка отменена и средства возвращены на баланс |
Если Viber сообщение невозможно отправить, в этом поле будет содержаться причина. При успешной отправке в значении будет пустая строка.
rejected_status | Описание |
---|---|
SRVC_NOT_VIBER_USER | Получатель не зарегистрирован в Viber |
SRVC_USER_BLOCKED | Получатель заблокировал отправителя, от имени которого было отправлено сообщение, либо абсолютно все бизнес сообщения |
SRVC_NO_SUITABLE_DEVICE | Viber получателя не поддерживает приём бизнес сообщений |
Модуль предусматривает работу с Viber чатами.
Пример адре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 отправителей) |
Пример адре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 | Дата и время последнего сообщения в чате |
Пример адре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, значит она ещё не завершилась и в ней можно отправлять сесионные сообщения.
Пример адре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, если сообщение не сессионное |
Пример адре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
}
}
Модуль предусматривает работу с данными аккаунта пользователя.
Пример адреcа вызова:
https://api.turbosms.ua/user/balance.json
Данный метод возвращает остаток средств на балансе пользователя. Тело запроса пустое.
Структура ответа:
{
"response_code": 0,
"response_status": "OK",
"response_result": {
"balance": 12345.67,
}
}
Модуль предусматривает работу с файлами пользователя.
Пример адре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Мб.
Пример адре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 |
NOT_ALLOWED_MESSAGE_DUPLICATE | 427 | Попытка создать сообщение, которое уже было создано в течение последних 90 секунд. | 12.12.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 |