Media API

Media API — программный интерфейс, который позволяет пользователям управлять аудиофайлами в Личном кабинете: загружать, удалять, скачивать и т.д. Файлы используются для проигрывания аудиосообщений абонентам во время звонков.

Media API Exolve предлагает пользователям следующие методы для управления аудиофайлами:

  • Upload - загружает аудиофайл в Личный кабинет;

  • GetList - получает информацию обо всех загруженных в Личный кабинет аудиофайлах, соответствующих определённым параметрам;

  • GetInfo - получает информацию об указанных в запросе аудиофайлах;

  • Download - получает указанный в запросе аудиофайл;

  • Update - изменяет название и описание загруженного аудиофайла в Личном кабинете;

  • Delete - удаляет аудиофайл из Личного кабинета.

Решения, где используется Media API

Метод Upload

Примените этот метод для загрузки аудиофайла к приложению. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/Upload

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
file bytes (Base64) аудиофайл (максимальный размер 5MB)
full_name string имя файла
file_type enum FileType тип аудиофайла

Примечание

Загружаемый аудиофайл не должен превышать размер в 5MB и название файла должно быть в формате MP3 или WAV.

FileType

Параметр Тип Описание
FILE_TYPE_IVR enum IVR (интерактивное голосовое меню)
FILE_TYPE_PREMEDIA enum премедиа (аудиосообщение, которое воспроизводится клиенту до ответа оператора)

Выходные параметры

Параметр Тип Описание
file_id uint64 внутренний ID аудиофайла
resource_id uint64 уникальный идентификатор ресурса загруженного аудиофайла
size uint64 размер аудиофайла в байтах (не более 5MB)
duration uint32 длительность аудиофайла в секундах
name string имя файла
extension string расширение aудиофайла (WAV или MP3)
description string описание к аудиофайлу
application_uuid string уникальный идентификатор приложения, к которому загружен аудиофайл
file_type enum FileType тип аудиофайла
date_upload string дата загрузки аудиофайла в формате RFC-3339 / ISO-8601

FileType

Параметр Тип Описание
200 enum IVR (интерактивное голосовое меню)
201 enum премедиа (аудиосообщение, которое воспроизводится клиенту до ответа оператора)

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found неверный URL запроса
400 Bad Request failed to parse token невалидный API-ключ
403 Forbidden invalid token невалидный API-ключ
400 Bad Request error Save media service: fileName is exist медиа файл с таким именем уже существует
400 Bad Request invalid value for enum type: [value] невалидное значение в поле FileType
400 Bad Request unexpected token одно из обязательных полей пустое
400 Bad Request invalid UploadRequest.File: value length must be at least 1 bytes не задано значение поля file
400 Bad Request invalid UploadRequest.FullName: value length must be between 1 and 128 runes, inclusive некорректно введено имя файла, поле full_name должно иметь от 1 до 128 символов
400 Bad Request invalid value for string type: [value] отсутствует значение поля full_name

Примеры

Входные параметры:

{
    "file": "SUQzAwAAAAAfdlRZRVIAAAAFAAAAMjAyMVRJVDIAAABHAAAB//4TBDgEQgQwBEAEMAQgADwENQQ7BD4ENAQ4BE8EIABABD4EO",
    "file_type": "FILE_TYPE_PREMEDIA",
    "full_name": "test.mp3"
}

Выходные параметры:

{
    "file_id": "1931072746905665536",
    "resource_id": "152817",
    "size": "121087",
    "duration": 5,
    "name": "test",
    "extension": "mp3",
    "description": "",
    "application_uuid": "178ec145-6898-4b06-a92a-75f63cb57046",
    "file_type": 201,
    "date_upload": "2023-06-14T16:53:40.459734572Z"
}

Метод GetList

Примените этот метод для получения информации о загруженных к приложению аудиофайлах по заданным входным параметрам. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/GetList

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON формате.

Параметр Тип Описание
resource_id uint64 уникальный идентификатор ресурса загруженного аудиофайла
name string имя файла
application_uuid string уникальный идентификатор приложения, к которому загружен аудиофайл
date_from string дата загрузки аудиофайла в формате RFC-3339 / ISO-8601, от которой начинать выборку
date_to string дата загрузки аудиофайла в формате RFC-3339 / ISO-8601, до которой продолжать выборку
order_list OrderList параметры сортировки выходных данных
limit uint32 лимит выводимых строк
offset uint64 номер строки, с которой начинать выборку (начинается с 0)

OrderList

Параметр Тип Описание
order_field enum OrderField тип сортировки выходных данных
order_direction enum OrderDirection порядок сортировки выходных данных

OrderField

Значение ID Описание
ORDER_FIELD_UNSPECIFIED 0 тип сортировки не определен
ORDER_FIELD_DATE 1 сортировка по дате загрузки аудиофайла
ORDER_FIELD_SIZE 2 сортировка по размеру аудиофайла
ORDER_FIELD_DURATION 3 сортировка по продолжительности аудиофайла

OrderDirection

Значение ID Описание
ORDER_DIRECTION_UNSPECIFIED 0 тип сортировки не определен
ORDER_DIRECTION_ASC 1 сортировка в порядке возрастания
ORDER_DIRECTION_DESC 2 сортировка в порядке убывания

Выходные параметры

Параметр Тип Описание
media_records array список с информацией об аудиофайлах
file_id uint64 внутренний ID аудиофайла
resource_id uint64 уникальный идентификатор ресурса загруженного аудиофайла
size uint64 размер аудиофайла в байтах
duration uint32 длительность аудиофайла в секундах
name string имя файла
extension string расширение aудиофайла
description string описание к аудиофайлу
application_uuid string уникальный идентификатор приложения, к которому загружен аудиофайл
file_type enum FileType тип аудиофайла
date_upload string дата загрузки аудиофайла в формате RFC-3339 / ISO-8601

FileType

Значение ID Описание
FILE_TYPE_IVR 200 IVR (интерактивное голосовое меню)
FILE_TYPE_PREMEDIA 201 премедиа (аудиосообщение, которое воспроизводится клиенту до ответа оператора)

Возможные ошибки

Код Статус Пример сообщения Описание
401 Unauthorized malformed token не указан / не правильно указан API-ключ приложения

Примеры

Входные параметры:

{
     
   "date_from": "2022-12-12T01:30:15.01Z",
    "date_to": "2024-01-15T01:30:15.477425Z",
    "order_list": {
        "order_direction": 1,
        "order_field": "ORDER_FIELD_DATE"
    },
    "limit": 2,
    "offset": "0"
}

Выходные параметры:

{
    "media_records": [
        {
            "file_id": "1931072746905665536",
            "resource_id": "152817",
            "size": "121087",
            "duration": 5,
            "name": "Test1",
            "extension": "mp3",
            "description": "",
            "application_uuid": "178ec145-6898-4b06-a92a-75f63cb57046",
            "application_name": "Test",
            "file_type": 201,
            "date_upload": "2023-06-14T16:53:40.459735Z"
        },
        {
            "file_id": "1885716233567862784",
            "resource_id": "138517",
            "size": "26375",
            "duration": 3,
            "name": "Test audio",
            "extension": "mp3",
            "description": "Тестовый аудиофайл",
            "application_uuid": "178ec145-6898-4b06-a92a-75f63cb57046",
            "application_name": "Test",
            "file_type": 201,
            "date_upload": "2023-02-09T13:03:04.996514Z"
        }
    ]
}

Метод GetInfo

Примените этот метод для получения атрибутов определенных аудиофайлов. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/GetInfo

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
resource_ids Array of uint64 уникальные идентификаторы загруженных аудиофайлов

Выходные параметры

Параметр Тип Описание
media_records array список с информацией об аудиофайлах
file_id uint64 внутренний ID аудиофайла
resource_id uint64 уникальный идентификатор загруженного аудиофайла
size uint64 размер аудиофайла в байтах
duration uint32 длительность аудиофайла в секундах
name string имя файла
extension string расширение aудиофайла
description string описание к аудиофайлу
application_uuid string уникальный идентификатор приложения, к которому загружен аудиофайл
file_type enum FileType тип аудиофайла
date_upload string дата загрузки аудиофайла в формате RFC-3339 / ISO-8601

FileType

Значение ID Описание
FILE_TYPE_IVR 200 IVR (интерактивное голосовое меню)
FILE_TYPE_PREMEDIA 201 премедиа (аудиосообщение, которое воспроизводится клиенту до ответа оператора)

Возможные ошибки

Код Статус Пример сообщения Описание
401 Unauthorized malformed token не указан / не правильно указан API-ключ приложения
400 Bad Request proto: syntax error (line 3:9): invalid character ‘\r’ in string синтаксическая ошибка

Примеры

Входные параметры:

{
    "resource_ids": [
        "138517",
        "152817"
    ]
}

Выходные параметры:

{
    "media_records": [
        {
            "file_id": "1885716233567862784",
            "resource_id": "138517",
            "size": "26375",
            "duration": 3,
            "name": "Test audio",
            "extension": "mp3",
            "description": "Тестовый аудиофайл",
            "application_uuid": "178ec145-6898-4b06-a92a-75f63cb57046",
            "application_name": "Test",
            "file_type": 201,
            "date_upload": "2023-02-09T13:03:04.996514Z"
        },
        {
            "file_id": "1931072746905665536",
            "resource_id": "152817",
            "size": "121087",
            "duration": 5,
            "name": "test5",
            "extension": "mp3",
            "description": "",
            "application_uuid": "178ec145-6898-4b06-a92a-75f63cb57046",
            "application_name": "Test",
            "file_type": 201,
            "date_upload": "2023-06-14T16:53:40.459735Z"
        }
    ]
}

Метод Download

Примените этот метод для получения загруженного файла по идентификатору ресурса. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/Download

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
resource_id uint64 уникальный идентификатор ресурса загруженного аудиофайла

Выходные параметры

Параметр Тип Описание
file bytes аудиофайл
full_name string полное имя аудиофайла
resource_id uint64 уникальный идентификатор ресурса загруженного аудиофайла
file_type enum FileType тип аудиофайла

FileType

Значение ID Описание
FILE_TYPE_IVR 200 IVR (интерактивное голосовое меню)
FILE_TYPE_PREMEDIA 201 премедиа (аудиосообщение, которое воспроизводится клиенту до ответа оператора)

Возможные ошибки

Код Статус Пример сообщения Описание
401 Unauthorized malformed token не указан / не правильно указан API-ключ приложения
500 Internal Server Error Application [ID] does not own resource [661352] файл принадлежит другому приложению

Примеры

Входные параметры:

{
    "resource_id": "6088"
}

Выходные параметры:


{
    "file": "SUQzAwAAAAAfdlRZRVIAAAAFAAAAMjAyMVRJVDIAAABHAAAB//4TB",
    "full_name": "19999tgb.mp3",
    "resource_id": "6088",
    "file_type": 201
}

Метод Update

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

Точка подключения:

POST: https://api.exolve.ru/media/v1/Update

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
resource_id uint64 уникальный идентификатор загруженного аудиофайла
name string новое наименование аудиофайла
description string новое описание к аудиофайлу

Выходные параметры

Пустой JSON с 200 OK статусом

Возможные ошибки

Код Статус Пример сообщения Описание
401 Unauthorized malformed token не указан / не правильно указан API-ключ приложения
400 Bad Request proto: syntax error (line 3:9): invalid character ‘\r’ in string синтаксическая ошибка
400 Bad Request invalid UpdateRequest.Name: value length must be at most 128 runes некорректное количество символов в поле numbers
400 Bad Request invalid UpdateRequest.Description: value length must be at most 512 runes некорректное количество символов в поле numbers

Примеры

Входные параметры:

{
    "resource_id": "152817",
    "name": "Update Test",
    "description": "Тест обновления аудиофайла"  
}

Выходные параметры:

{}

Метод Delete

Примените этот метод для удаления загруженных к приложению аудиофайлов. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/Delete

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
resource_ids Array of uint64 уникальные идентификаторы загруженных аудиофайлов

Выходные параметры

Пустой JSON с 200 OK статусом.

Возможные ошибки

Код Статус Пример сообщения Описание
401 Unauthorized malformed token не указан / не правильно указан API-ключ приложения
400 Bad Request proto: syntax error (line 3:9): invalid character ‘\r’ in string синтаксическая ошибка

Примеры

Входные параметры:

{
    "resource_ids": [
        "138231"
    ]
}

Выходные параметры:

{}