Звуковые Файлы (/sound/)

Мы обновили документацию, актуальная версия страницы доступна по ссылке: Звуковые файлы (/sound/)

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

Загрузка звуковых файлов

Поддерживаются звуковые файлы в форматах wav и mp3. Максимальный размер файла – 10 мегабайт.

Content-Type при загрузке файлов

При загрузке файлов через метод POST следует установить заголовок Content-Type в значение multipart/form-data с указанием параметра boundary, который содержит последовательность символов, разделяющую части тела запроса. Параметры звукового файла и сам файл передаются как поля формы. Во всех остальных методах, в том числе и обновлении информации о звуковом файле, следует использовать обычный Content-Type: application/json и передавать информацию в JSON-формате.

Стоит отметить, что в большинстве случаев различные библиотеки для работы с веб-ресурсами генерируют тело запроса и заголовок Content-Type с параметром boundary автоматически.

Описание полей

Параметр
Тип
Обязательный
Значение по умолчанию
Описание
title

string

да
Название звукового файла
filefileда

Звуковой файл в формате wav или mp3. Максимальный размер файла – 10 мегабайт. Не поддерживаются wav-файлы с кодированием типа FloatНе поддерживаются wav-файлы, в которых нет информации о формате: кодировании, количестве каналов, битрейте, частоте и т.д.

В случае успешной загрузки файла, возвращается ресурс "Звуковой файл", содежащий в том числе идентификатор звукового файла (поле id), который используется для указания звука в ресурсах очереди, голосового приветствия и т.п.

Пример HTTP-запроса

Пример HTTP-запроса, загружающего звуковой файл test_sound.wav c именем Файл приветствия .

Request URL: https://hostname.domain/api/ver1.0/client/@me/sound/
Request Method: POST
Authorization: Bearer token
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryRJjeZXUAAoerF744
Host: hostname.domain
------WebKitFormBoundaryRJjeZXUAAoerF744
Content-Disposition: form-data; name="file"; filename="test_sound.wav"
Content-Type: audio/wav


------WebKitFormBoundaryRJjeZXUAAoerF744
Content-Disposition: form-data; name="title"

Файл приветствия
------WebKitFormBoundaryRJjeZXUAAoerF744--

Пример загрузки файла с помощью cURL

Загрузка звука через cURL
user@host$ curl -i -X POST -F file=@hello.wav -F"title=мой файл приветствия" -H"Authorization: Bearer TSyAxXtAsbE9Kl0iAVGG6LmnfEte8X" https://host.domain/api/ver1.0/client/@me/sound/
HTTP/1.1 100 Continue
HTTP/1.1 201 CREATED
Server: nginx/1.8.0
Date: Tue, 11 Aug 2015 09:50:41 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, OPTIONS
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
{"id": 51, "client_id": 12, "title": "мой файл приветствия", "dealer_id": null, "filename": "84594e4f-e1a8-4b48-a613-38264fe60201.wav"}

Пример загрузки файла на языке Python

Загрузка звукового файла
#!/usr/bin/python
# -*- coding: utf-8 -*-

import requests
import json

# Установка параметров
API_HOST = "https://hostname.domain"
APP_ID = "APP_ID"
APP_SECRET = "APP_SECRET"
REDIRECT_URI = ""

# Получение авторизации
body = {
    'grant_type': 'client_credentials',
    'client_id': APP_ID,
    'client_secret': APP_SECRET,
}

request_url = "{host}/oauth/token".format(host=API_HOST)
response = requests.post(request_url, data=body, verify=False)

if response.status_code == 200:
    # Получение токена доступа
    access_token = response.json()['access_token']
elif response.status_code == 401:
    print 'Ошибка авторизации: {error}'.format(error=response.json()['error'])
    exit(1)
else:
    print 'Неизвестная ошибка'
    exit(2)

# Установка заголовка авторизации
headers = {
    'Authorization': 'Bearer {access_token}'.format(access_token=access_token)  # Заголовок авторизации
}

files = {'file': open('test_file.wav', 'rb')}
data = {'title': 'Файл приветствия'}

request_url = "{host}/api/ver1.0/client/@me/sound/".format(host=API_HOST)
response = requests.post(request_url, files=files, data=data, headers=headers)
if response.status_code == 201:
    file_info = response.json()
    print file_info
else:
    print response.text

Получение списка звуковых файлов

Получение всех доступных для использования клиенту или добавочному звуков осуществляется через соответствующий ресурс.

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

Описание полей

Параметр
Тип
Описание
id

integer

Идентификатор звукового файла
title

string

Название звукового файла
client_idinteger

Идентификатор клиента, владеющего звуковым файлом. Может иметь значение null, если звук не принадлежит клиенту.

dealer_idinteger

Идентификатор дилера, владеющего звуковым файлом. Может иметь значение null, если звук не принадлежит дилеру клиента.

filenamestring

Системное имя файла, которое может быть использовано, в частности, для проигрывания звука через функцию IVR Call Interactive.


Ресурсы раздела "Клиент"

POST /client/{client_id}/sound/

Добавить звуковой файл

Параметры URL

Имя

Тип

client_id

string

Поля ответа

Имя

Тип

dealer_id

integer

id

integer

client_id

integer

title

string

filename

string

GET /client/{client_id}/sound/

Получить список доступных клиенту звуковых файлов

Параметры запроса

Имя

Тип

id

array [integer]

own_only

boolean

title

array [string]

Поля ответа

Имя

Тип

dealer_id

integer

id

integer

client_id

integer

title

string

filename

string


PUT /client/{client_id}/sound/{sound_id}

Обновить информацию о звуковом файле

Параметры URL

Имя

Тип

client_id

string

sound_id

integer

Параметры JSON

Имя

Тип

Обязательный

title

string

нет

Поля ответа

Имя

Тип

dealer_id

integer

id

integer

client_id

integer

title

string

filename

string

GET /client/{client_id}/sound/{sound_id}

Получить информацию о звуковом файле

Параметры URL

Имя

Тип

client_id

string

sound_id

integer

Поля ответа

Имя

Тип

dealer_id

integer

id

integer

client_id

integer

title

string

filename

string

DELETE /client/{client_id}/sound/{sound_id}

Удалить звуковой файл

Параметры URL

Имя

Тип

client_id

string

sound_id

integer


GET /client/{client_id}/sound/{sound_id}/download/

Получить звуковой файл

Параметры URL

Имя

Тип

client_id

string

sound_id

integer

Ресурсы раздела "Добавочный"

GET /extension/{extension_id}/sound/

Получить список доступных добавочному звуковых файлов

Параметры URL

Имя

Тип

extension_id

string

Параметры запроса

Имя

Тип

title

array [string]

id

array [integer]

Поля ответа

Имя

Тип

dealer_id

integer

id

integer

client_id

integer

title

string

filename

string


GET /extension/{extension_id}/sound/{sound_id}/download/

Получить звуковой файл

Параметры URL

Имя

Тип

extension_id

string

sound_id

integer