Platform HTTP API

Формат взаимодействия

Запросы к API выполняются по протоколу HTTP. Входные и выходные структуры данных передаются в теле запроса и ответа в формате JSON.

Авторизация

Большинство вызовов HTTP API требуют процедур аутентификации и авторизации, которые связывают вызовы API с необходимыми приложениями в Вашей учетной записи.

Для этого каждый запрос должен содержать заголовок, либо аргумент X-Authorization с токеном соединения в формате AccessKey token,

Например заголовком:
POST /apps/activate HTTP/1.1
Host: api.unibell.ru
X-Authorization: AccessKey d8ac9959r12b43545da9034
или
Authorization: Basic d8ac9959r12b43545da9034

либо параметром:
POST api.unibell.ru/apps/activate?X-Authorization=AccessKey d8ac9959r12b43545da9034

Формат ответов

JSON схема любого ответа содержит параметр status типа string со следующими значениями:

Значение status	Описание
ok	Без ошибок
invalidAccessKeyError	Неверный AccessKey
requiredJsonError	В теле запроса требуется JSON
invalidSchemeError	Неверная схема JSON
invalidDataError	Ошибочные входные данные
prohibitedForAppError	Запрещено для данного приложения
prohibitedForServiceError	Запрещено для данной услуги
rpcError	Коммуникационная ошибка

Например:

    {
        …
        “status”: “ok”
        ....
    }

Некоторые GET запросы поддерживают постраничный вывод. Для управления постраничным выводом используются следующие параметры:

Параметр	Описание
page	Запрашиваемый номер страницы
per_page	Количество элементов на странице
disable_pagination	Отключить постраничный вывод

Например,

GET api.unibell.ru/media?page=1&per_page=10

В ответе на такой запрос будет содержаться json объект pagination:

    {
        …
        "pagination": {
            "totalItems": 2,
            "currentPage": 1,
            "totalPages": 1
        }
        ....
    }

где:

Параметр	Описание
totalItems	Общее количество элементов
currentPage	Порядковый номер страницы
totalPages	Общее количество страниц

Формат запросов

Управление медиатекой

Медиатека — иерархическое хранилище различных файлов пользователя, напоминающее файловую систему. Объектами хранения медиатеки являются файлы и папки. Файлы могут быть разбиты по папкам. Доступ к медиатеке осуществляется с помощью ЛК или данного API.

Параметр	Описание
totalItems	Общее количество элементов
currentPage	Порядковый номер страницы
totalPages	Общее количество страниц

Получение списка всех объектов

Запрос

GET api.unibell.ru/media

Ответ

    {
        "status":  "ok",
        "pagination": {
            "totalItems":  2,
            "currentPage":  1,
            "totalPages":  1
        },
        "media": [
            {
                "createdDateTime":  "2020-02-12 18:09:10",
                "id":  65,
                "name":  "Гимны",
                "isFolder":  1
            },
            {
                "createdDateTime":  "2020-03-04 13:17:47",
                "id":  74,
                "name":  такой молодой.mp3",
                "isFolder":  0
            }
        ]
    }

media — массив объектов медиатеки содержащие следующие параметры:

Параметр	Описание
id	Уникальный идентификатор медиаресурса
name	Наименование
createdDateTime	Дата\время загрузки
isFolder	Признак того, что данный объект является папкой. 1 — да, 0 — нет

Получение конкретного объекта

Запрос

GET api.unibell.ru/media/id, где id — уникальный идентификатор медиаресурса

Ответ

Для папок возвращается список вложенных файлов:

    {
        "status": "ok",
        "pagination": {
            "totalPages": 1,
            "totalItems": 2,
            "currentPage": 1
        },
        "media": [
            {
                "isFolder": 0,
                "name": "Гимн пионэров.mp3",
                "createdDateTime": "2020-02-12 18:19:05",
                "id": 67
            },
            {
                "isFolder": 0,
                "name": "Гимн СССР.mp3",
                "createdDateTime": "2020-02-12 18:19:18",
                "id": 68
            }
        ]
    }

Для файлов возвращается запрашиваемый файл.

Создание папки

Запрос

POST api.unibell.ru/media

    {
        "name": "asdasd"
    }

Параметр	Описание
name	Наименование папки

Ответ

   {
        "status": "ok",
        "media": {
            "name": "asdasd2",
            "createdDateTime": "2020-04-06 18:44:45",
            "isFolder": 1,
            "id": 111
        }
    }

Загрузка файла

Запрос

POST api.unibell.ru/media — помещает файл в корневую папку
POST api.unibell.ru/media/folder_id — помещает файл в указанную папку

Файл передается в теле запроса посредством Content-Type: multipart/form-data

Ответ

    {
        "status": "ok",
        "media": {
            "name": "test",
            "createdDateTime": "2020-04-06 18:44:45",
            "isFolder": 0,
            "id": 112
        }
    }

Переименование объекта

Запрос

PUT api.unibell.ru/media/id, где id — уникальный идентификатор медиаресурса

    {
        "name": "asdasd"
    }

Ответ

    {
        "status": "ok",
        "media": {
            "name": "asdasd",
            "createdDateTime": "2020-04-06 18:44:45",
            "isFolder": 1,
            "id": 111
        }
    }

Удаление объекта

Запрос

DELETE api.unibell.ru/media/id, где id — уникальный идентификатор медиаресурса

Ответ

    {
        “status”: “ok”
    }

Управление приложениями

Активация приложения

Выполняет активацию заранее созданного приложения.

Запрос

POST api.unibell.ru/apps/activate

{
  "reference": "123456789",
  "sourceAddr": "XXXXXXXXXXX",
  "destAddr": "XXXXXXXXXXX",
  "scenarioData": "text=Привет, как дела?"
}

Параметр	Тип	Описание
reference	string	Пользовательский параметр с которым будет вызван callback по результатам выполнения приложения
sourceAddr	string	Исходящий номер
destAddr	string	Номер телефона получателя
scenarioData	string	Переменные сценария для данного приложения. Представляет из себя набор пар параметр=значение, разделенных знаком — &.

Ответ

    {
        “status”: “ok”
    }

Запуск приложения с повторами

Запуск приложения с повторами — это процесс инициирования вызова, при котором автоматически повторяется попытка в случае неудачного исхода, таких как занятость линии, отсутствие ответа, неудачный звонок или успешный ответ. Настройка повторов позволяет задать условия и параметры для каждого сценария.

Пример

Если звонок абоненту не удался из-за занятой линии (repeatBusy), автоматически повторяется попытка через установленный интервал (repeatBusyInt) до тех пор, пока не исчерпается количество попыток (repeatBusyCount).

Запрос

POST api.unibell.ru/apps/activate

Тело запроса

{
  "numberId": 14019763,
  "abonentListId": 13296,
  "startDateTime": "2024-10-31 09:00:00",
  "workStartTime": "2024-10-31 09:00:00",
  "workEndTime": "2024-10-31 21:00:00",
  
  "isRepeat": 1,
  "repeatBusy": 1,
  "repeatBusyCount": 10,
  "repeatBusyInt": 30,
  "repeatAnswered": 1,
  "repeatAnsweredCount": 15,
  "repeatAnsweredInt": 35,
  "repeatFailed": 1,
  "repeatFailedCount": 1,
  "repeatFailedInt": 1,
  "repeatNoAnswer": 1,
  "repeatNoAnswerCount": 150,
  "repeatNoAnswerInt": 150
}

Параметры	Тип	Описание
numberId _или numberPoolId	int	ID A-номера ID Пула-номеров
abonentListId	int	ID B-номеров
startDateTime	timedatestamp	Временная метка начала момента запуска
workStartTime	timedatestamp	Начало работы сценария
workEndTime	timedatestamp	Конец работы сценария
isRepeat	int	Разрешение повторов: _{^{0 — не совершаются 1 — совершаются}}
repeatBusy	int	Повтор при занятом номере
repeatAnswered	int	Повтор при успешном ответе
repeatFailed	int	Повтор при неудачном звонке
repeatNoAnswer	int	Повтор при отсутствии ответа
repeatBusyCount, repeatAnsweredCount, repeatFailedCount, repeatNoAnswerCount	int	Количество повторов
repeatBusyInt, repeatAnsweredInt, repeatFailedInt, repeatNoAnswerInt	int	Интервал повторного звонка (в секундах)

Ответ

{
    "status": "ok",
    "requestId": "37b873131de218352d63f980cb71b41b"
}

При исполнении приложения могут быть настроены callback по протоколу HTTP/HTTPS. Callback настраивают на два вида события — начало исполнения(Start callback) и завершение исполнения(End callback). Поддерживается Basic авторизация. Параметры передаются в URL запроса.

Например,
GET www.host.ru?type=startCallback&reference=324234

Параметры передаваемые в startCallback:

Параметр	Описание
reference	Пользовательский параметр переданный в запросе активации
type	Тип callback запроса, в данном случае — startCallback

Параметры передаваемые в endCallback:

Параметр	Описание
reference	Пользовательский параметр переданный в запросе активации
type	Тип callback запроса, в данном случае — endCallback
state	Результат выполнения приложения
error	Код ошибки, либо 0 — в случае успешного выполнения
duration	Длительность вызова
appKey	API ключ приложения

где, state — результат выполнения сценария:

state	Значение	Описание
STATE_OK	2	Приложение выполнено успешно
STATE_ERR	5	Ошибка в результате выполнения

error — код ошибки:

error	Значение	Описание
ERR_NO_ANSWER	16	Абонент не взял трубку, попытки дозвона исчерпаны
ERR_BUSY	17	Абонент занят, попытки дозвона исчерпаны
ERR_ALERTING	19	Абонент не доступен
ERR_CONGESTION	34	Перегрузка каналов связи
ERR_PLAY	1001	Ошибка воспроизведения файла, файл не найден, неверный формат
ERR_TTS	1002, 1017	Ошибка TTS преобразования
ERR_ASR	1003	Ошибка ASR преобразования

Скачивание диалога

Для получения записи разговора, необходимо отправить запрос по следующему адресу:

GET https://api.unibell.ru/dialog_record_by_reference?reference=987654

Где:

reference — пользовательский параметр, полученный в endCallback.

Заголовки:

X-Authorization: AccessKey d8ac9959r12b43545da9034
или
Authorization: Basic d8ac9959r12b43545da9034

Если неверный AccessKey:

{
    "status": "invalidAccessKeyError"
}

Если запись по какой-либо причине не будет найдена, придёт ответ с кодом 404 NOT FOUND и телом ответа:

{
    "errorReason": "No records found"
}

Проверка баланса

Запрос

GET api.unibell.ru/balance

Выводит в формате JSON лицевой счет и его баланс. Лицевой счет отображается тот, на котором находится приложение, ключ от которого указан в авторизации запроса

Ответ

     {
        "personalAccountId": "0000000000",
        "balance": "100.0"
     }

На этой странице