Platform API

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

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

Авторизация

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

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

Например заголовком:

POST /apps/activate HTTP/1.1
Host: api.unibell.ru
X-Authorization: AccessKey d8ac9959r12b43545XXXXX

X-Authorization передается в зависимости от настроек HTTP-подключения:

AccessKey d8ac9959r12b43545XXXXX — по умолчанию

Basic d8ac9959r12b43545XXXXX (или Basic base64encoded(username:password))

Bearer d8ac9959r12b43545XXXXX

либо параметром:

POST https://api.unibell.ru/apps/activate?X-Authorization=AccessKey d8ac9959r12b43545XXXXX

Пример запроса с использованием CURL:

curl --location --request POST 'https://api.unibell.ru/apps/activate' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX'

curl --location --request POST 'https://api.unibell.ru/apps/activate?X-Authorization=AccessKey%20d8ac9959r12b43545XXXXX'

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

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

Пример запроса с использованием CURL:

curl --location 'https://api.unibell.ru/media?page=1&per_page=10' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX'

curl --location --request POST 'https://api.unibell.ru/media?page=1&per_page=10%3FX-Authorization%3DAccessKey%20d8ac9959r12b43545XXXXX'

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

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

где:

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

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

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

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

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

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

Запрос:

GET https://api.unibell.ru/media

Пример запросов с использованием CURL:

curl --location 'https://api.unibell.ru/media?X-Authorization=AccessKey%20d8ac9959r12b43545XXXXX'

curl --location 'https://api.unibell.ru/media' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX'

Ответ:

{
        "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 https://api.unibell.ru/media/id

где id — уникальный идентификатор медиаресурса

Пример запросов с использованием CURL:

curl --location 'https://api.unibell.ru/media/id?X-Authorization=AccessKey%20d8ac9959r12b43545XXXXX'

curl --location 'https://api.unibell.ru/media/id' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX'

Ответ:

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

{
        "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 https://api.unibell.ru/media

Тело запроса:

{
   "name": "asdasd"
}

Пример запросов с использованием CURL:

curl --location 'https://api.unibell.ru/media' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX' \
--header 'Content-Type: application/json' \
--data '{
   "name": "Папка1"
}'

curl --location 'https://api.unibell.ru/media?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX' \
--header 'Content-Type: application/json' \
--data '{
   "name": "Папка1"
}'

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

Ответ:

{
    "status": "ok",
     "media": {
      "name": "asdasd",
      "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

Пример запросов с использованием CURL:

Поместить файл в корневую папку:

curl --location 'https://api.unibell.ru/media?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX' \
--form '=@"/home/Загрузки/les.mp3"'

curl --location 'https://api.unibell.ru/media' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX' \
--form '=@"/home/Загрузки/les.mp3"'

Поместить файл в указанную папку:

curl --location 'https://api.unibell.ru/media/12826?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX' \
--form '=@"/home/Загрузки/les.mp3"'

curl --location 'https://api.unibell.ru/media/12826' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX' \
--form '=@"/home/Загрузки/les.mp3"'

Ответ:

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

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

Запрос:

PUT https://api.unibell.ru/media/id

где id — уникальный идентификатор медиаресурса

Тело запроса:

{
   "name": "Test"
}

Пример запросов с использованием CURL:

curl --location --request PUT 'https://api.unibell.ru/media/12826' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX' \
--header 'Content-Type: application/json' \
--data '{
   "name": "Test"
}'

curl --location --request PUT 'https://api.unibell.ru/media/12826?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX' \
--header 'Content-Type: application/json' \
--data '{
   "name": "Test"
}'

Ответ:

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

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

Запрос:

DELETE api.unibell.ru/media/id

где id — уникальный идентификатор медиаресурса

Пример запросов с использованием CURL:

curl --location --request DELETE 'https://api.unibell.ru/media/12826' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX'

curl --location --request DELETE 'https://api.unibell.ru/media/12826?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX'

Ответ:

{
    "status": "ok"
}

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

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

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

Запрос:

POST https://api.unibell.ru/apps/activate

Тело запроса:

{
   "reference": "123456789",
   "sourceAddr": "7XXXXXXXXXX",
   "destAddr": "7XXXXXXXXXX",
   "scenarioData": "text=Иван Иванович",
   "language": "ru-RU",
   "sex": 1,
   "volume": 2,
   "rate": 4
}

Пример запросов с использованием CURL:

curl --location 'https://api.unibell.ru/apps/activate?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX' \
--header 'Content-Type: application/json' \
--data '{
   "reference": "123456789",
   "sourceAddr": "7XXXXXXXXXX",
   "destAddr": "7XXXXXXXXXX",
   "scenarioData": "text=Иван Иванович",
   "language": "ru-RU",
   "sex": 1,
   "volume": 2,
   "rate": 4
}'

curl --location 'https://api.unibell.ru/apps/activate' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX' \
--header 'Content-Type: application/json' \
--data '{
   "reference": "123456789",
   "sourceAddr": "7XXXXXXXXXX",
   "destAddr": "7XXXXXXXXXX",
   "scenarioData": "text=Иван Иванович",
   "language": "ru-RU",
   "sex": 1,
   "volume": 2,
   "rate": 4
}'

Параметр	Тип	Описание
reference (необязательный)	string	Пользовательский параметр с которым будет вызван callback по результатам выполнения приложения ^{Используется если необходимо скачать запись разговора}
sourceAddr	string	Исходящий номер *Поле не должно содержать кириллицы*
destAddr	string	Номер телефона получателя
scenarioData (необязательный)	string	Переменные сценария для данного приложения. Представляет из себя набор пар параметр=значение, разделенных знаком — &.
sex (необязательный)	int	Пол. 0 — женщины, 1 — мужчина
language (необязательный)	string	ru-RU – Русский
volume (необязательный)	int	Громкость голоса (0-2)
rate (необязательный)	int	Скорость произнесения текста (0-4). (0 — самая медленная)

Ответ:

{
    "status": "ok"
}

При ошибке в sourceAddr:

{
    "status": "invalidDataError",
    "error": "Field sourceAddr must not contain Cyrillic"
}

Параметр	Тип	Описание
status	string	Статус запроса
error	string	Поле sourceAddr не должно содержать кириллицы

Пример сценария с переменной, которая задается в запросе:

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

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

Пример:

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

Запрос:

POST api.unibell.ru/apps/activate

Тело запроса:

{
   "reference": "123456789",
   "sourceAddr": "7XXXXXXXXXX",
   "destAddr": "7XXXXXXXXXX",

   "scenarioData": "text=Привет, как дела?",
  
   "isRepeat": 1,
   "repeatBusy": 1,
   "repeatBusyCount": 10,
   "repeatBusyInt": 30,
   "repeatAnswered": 1,
   "repeatAnsweredCount": 10,
   "repeatAnsweredInt": 35,
   "repeatFailed": 1,
   "repeatFailedCount": 1,
   "repeatFailedInt": 1,
   "repeatNoAnswer": 1,
   "repeatNoAnswerCount": 10,
   "repeatNoAnswerInt": 150
}

Пример запросов с использованием CURL:

curl --location 'https://api.unibell.ru/apps/activate' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX' \
--header 'Content-Type: application/json' \
--data '{
   "reference": "123456789",
   "sourceAddr": "7XXXXXXXXXX",
   "destAddr": "7XXXXXXXXXX",
   "scenarioData": "text=Привет, как дела?",
   "isRepeat": 1,
   "repeatBusy": 1,
   "repeatBusyCount": 10,
   "repeatBusyInt": 30,
   "repeatAnswered": 1,
   "repeatAnsweredCount": 10,
   "repeatAnsweredInt": 35,
   "repeatFailed": 1,
   "repeatFailedCount": 1,
   "repeatFailedInt": 1,
   "repeatNoAnswer": 1,
   "repeatNoAnswerCount": 10,
   "repeatNoAnswerInt": 150
}'

curl --location 'https://api.unibell.ru/apps/activate?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX' \
--header 'Content-Type: application/json' \
--data '{
   "reference": "123456789",
   "sourceAddr": "7XXXXXXXXXX",
   "destAddr": "7XXXXXXXXXX",

   "scenarioData": "text=Привет, как дела?",
  
   "isRepeat": 1,
   "repeatBusy": 1,
   "repeatBusyCount": 10,
   "repeatBusyInt": 30,
   "repeatAnswered": 1,
   "repeatAnsweredCount": 10,
   "repeatAnsweredInt": 35,
   "repeatFailed": 1,
   "repeatFailedCount": 1,
   "repeatFailedInt": 1,
   "repeatNoAnswer": 1,
   "repeatNoAnswerCount": 10,
   "repeatNoAnswerInt": 150
}'

Параметры	Тип	Описание
reference (необязательный)	string	Пользовательский параметр с которым будет вызван callback по результатам выполнения приложения
sourceAddr	string	Исходящий номер *Поле не должно содержать кириллицы*
destAddr	string	Номер телефона получателя
scenarioData (необязательный)	string	Переменные сценария для данного приложения. Представляет из себя набор пар параметр=значение, разделенных знаком — &.
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"
}

При ошибке в sourceAddr:

{
    "status": "invalidDataError",
    "error": "Field sourceAddr must not contain Cyrillic"
}

Параметр	Тип	Описание
status	string	Статус запроса
error	string	Поле sourceAddr не должно содержать кириллицы

При исполнении приложения могут быть настроены 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 api.unibell.ru/dialogs?source_addr=7XXXXXXXXXX&direction=0&duration_more=0&duration_less=50&size=100000&filter_date_start=2025-04-01 00:00:00&filter_date_end=2025-04-11 00:00:00

Пример запросов с использованием CURL:

curl --location 'https://api.unibell.ru/dialogs?source_addr=7XXXXXXXXXX&direction=0&duration_more=0&duration_less=50&size=100000&filter_date_start=2025-04-01%2000%3A00%3A00&filter_date_end=2025-04-11%2000%3A00%3A00' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX'

curl --location 'https://api.unibell.ru/dialogs?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX&source_addr=7XXXXXXXXXX&direction=0&duration_more=0&duration_less=50&size=100000&filter_date_start=2025-04-01%2000%3A00%3A00&filter_date_end=2025-04-11%2000%3A00%3A00'

Параметр	Описание
Обязательный заголовок:
X-Authorization	Ключ приложения
Необязательные параметры:
source_addr	Фильтр по номеру телефона, с которого был звонок *Поле не должно содержать кириллицы*
dest_addr	Фильтр по номеру телефона, на который был звонок
direction	Фильтр по типу звонка: входящий или исходящий ^{(0 — исходящий, 1 — входящий)}
duration	Точная длительность звонка (в секундах)
duration_more	Звонки с длительностью больше указанного значения (в секундах)
duration_less	Звонки с длительностью меньше указанного значения (в секундах)
vars	Фильтр по переменным
size	Размер выборки ^{(если параметр не указан или задано значение больше 10000, используется значение 10000)}
filter_date_start	Дата начала периода для выборки звонков
filter_date_end	Дата окончания периода
_{Примечание: filter_date_start и filter_date_end работают вместе, передаются в формате:} _{YYYY-MM-DD HH:MM:SS} _{пример: 2025-03-17 00:00:00}

Заголовки:

X-Authorization: AccessKey d8ac9959r12b43545XXXXX
или
Authorization: Basic d8ac9959r12b43545XXXXX (или Basic base64encoded(username:password))
а также
Authorization: Bearer d8ac9959r12b43545XXXXX

Ответ:

[
    {
        "appId": XX,
        "callId": "209-1744260245.10340",
        "cause": 0,
        "causeTxt": "",
        "createdDateTime": "2025-04-10 04:44:05",
        "destAddr": "7XXXXXXXXXX",
        "direction": 0,
        "duration": 4,
        "hangupFromScenario": 1,
        "id": "jt8FHpYBWcA8WrrK5Fmb",
        "sourceAddr": "7XXXXXXXXXX",
        "state": 2,
        "vars": "destAddr=7XXXXXXXXXX&sourceAddr=7XXXXXXXXXX"
    },
    {
        "appId": XX,
        "callId": "209-1743773461.6182",
        "cause": 0,
        "causeTxt": "",
        "createdDateTime": "2025-04-04 13:31:01",
        "destAddr": "7XXXXXXXXXX",
        "direction": 0,
        "duration": 6,
        "hangupFromScenario": 1,
        "id": "V_0CAZYBWcA8WrrKHnWx",
        "sourceAddr": "7XXXXXXXXXX",
        "state": 2,
        "vars": "destAddr=7XXXXXXXXXX&sourceAddr=7XXXXXXXXXX"
    }
]

Параметры	Описание
appId	ID приложения
callId	ID звонка
cause	Причина отбоя
causeTxt	Причина отбоя в текстовом виде
createdDateTime	Дата и время звонка
destAddr	Номер телефона получателя
direction	Информация о типе звонка
duration	Вид звонка (входящий/исходящий)
hangupFromScenario	Флак, указывающий отбой со стороны сценария по завершению
id	Уникальный идентификатор диалога
sourceAddr	Исходящий номер
state	Результат выполнения приложения
vars	Переменные, используемые в сценарии

Скачивание файла записи разговора

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

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

Пример запросов с использованием CURL:

curl --location 'https://api.unibell.ru/dialog_record_by_reference?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX&reference=987654'

curl --location 'https://api.unibell.ru/dialog_record_by_reference?reference=987654' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX'

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

Заголовки:

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

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

{
    "status": "invalidAccessKeyError"
}

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

{
    "errorReason": "No records found"
}

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

Запрос:

GET api.unibell.ru/balance

Пример запросов с использованием CURL:

curl --location 'https://api.unibell.ru/balance?X-Authorization=AccessKey%20d0a72c04168758df39XXXXX'

curl --location 'https://api.unibell.ru/balance' \
--header 'X-Authorization: AccessKey d0a72c04168758df39XXXXX'

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

Ответ:

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

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