Вложения сценариев IVR (attachments)

Обзор

Предоставляет доступ к файлам в каталоге вложений конкретного сценария IVR (по коду/идентификатору).

Каталог располагается в категории автоматически синхронизирующихся каталогов :SYNC, принадлежит домену, синхронизируется между серверами на всех сайтах, обслуживающими домен.

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

При заливке вложений архивом (метод UPLOADZIP) архив, содержащий записи с сегментами "..", абсолютные пути или символические ссылки за пределы архива, отвергается целиком с кодом 422: не размещается ни один файл из него. Подробно: требования к содержимому архива.

Доступно только в рабочих доменах.

Запросы

HTTP verb Endpoint Описание

POST

/rest/v1/uc/ivrscripts/<id>/attachments

Заливка группы файлов

GET

/rest/v1/uc/ivrscripts/<id>/attachments

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

GET

/rest/v1/uc/ivrscripts/<id>/attachments/<filename>

Скачивание файла

PUT

/rest/v1/uc/ivrscripts/<id>/attachments/<filename>

Перезаливка существующего файла

DELETE

/rest/v1/uc/ivrscripts/<id>/attachments/<filename>

Удаление файла

HEAD

/rest/v1/uc/ivrscripts/<id>/attachments/<filename>

Получение мета-информации о файле

METADATA

/rest/v1/uc/ivrscripts/<id>/attachments/<filename>

Получение мета-информации о файле (METADATA)

Заливка группы файлов

Загрузка в коллекцию производится с помощью Content-Type: multipart/formdata.

В запросе может быть один или несколько файлов. Файлы размещаются под именами, указанными в заголовках Content-Disposition каждой части.

Если файл с указанным именем уже существует, то он не сохраняется и возвращает ошибку. В зависимости от Content-Type и наличия успешно размещенных файлов в запросе может быть возвращен неудачный HTTP-ответ, либо информация о неудаче в теле HTTP-ответа 200 OK.

Запрос

Пример запроса
POST /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments HTTP/1.1
Content-Type: multipart/form-data; boundary=-----------boundary_69df8120352a996e

-----------boundary_69df8120352a996e
Content-Type: application/octet-stream
Content-Disposition: form-data; name="filename"; filename="sound12.mp3"
Content-Transfer-Encoding: binary

BINARY BODY OF 'sound12.mp3'
-----------boundary_69df8120352a996e--

Ответ

Пример ответа
[
  {
    "name": "sound12.mp3",
    "size": 160042,
    "status": "ok"
  }
]

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

Запрос

Table 1. Параметры запроса
Имя Тип Описание

filter

object

Фильтр по значениям полей.

mask

str

Список полей для вывода. Доступные поля для выдачи: name, size, last_modified.

offset

int

Смещение в списке файлов, подлежащих выдаче.

limit

int

Максимальное количество файлов в списке.

order

array<object|str>

Порядок сортировки файлов в списке.

countonly

bool

При значении true возвращается только количество файлов.

Считается после применения фильтра: с параметром filter возвращается количество подходящих под фильтр файлов, а не общее количество файлов в каталоге.

Подробно про формат параметров GET-запроса

Пример запроса
GET /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments HTTP/1.1

Ответ

Время в поле last_modified возвращается в UTC.

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "name": "sound11.wav",
    "size": 621692,
    "last_modified": "2019-09-19 12:53:11"
  },
  {
    "name": "sound12.wav",
    "size": 160042,
    "last_modified": "2019-09-19 12:53:11"
  }
]

Скачивание файла

Запрос

Table 2. Параметры запроса
Имя Тип Описание

attachment

bool

Тип выдачи. По умолчанию false.

true – выдаётся с заголовком Content-Disposition: attachment; filename=filename.ext либо Content-Disposition: attachment; filename*=UTF-8''%d1%84%d0%b0%d0%b9%d0%bb.ext, где файл.ext – имя файла в кодировке UTF-8 и URLencoded.

false – выдается без заголовка Content-Disposition.
Пример запроса
GET /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments/sound12.mp3?attachment=true HTTP/1.1

Ответ

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/octet-stream; charset=utf-8
Content-Disposition: attachment; filename*=UTF-8''sound%2012.mp3

BINARY BODY OF 'sound 12.mp3'

Перезаливка существующего файла

Производит замену файла.

Загрузка одного файла производится либо с помощью Content-Type: multipart/formdata, либо с произвольным Content-Type не являющимся мультипартом.

Если загрузка происходит с Content-Type: multipart/formdata, то будет сохранён только первый файл (первая часть имеющая поле filename в заголовке Content-Disposition), а само название файла будет проигнорировано.

Запрос

Пример запроса (octet-stream)
PUT /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments/sound12.mp3 HTTP/1.1
Content-Type: application/octet-stream

BINARY BODY OF 'sound12.mp3'
Пример запроса (multipart)
PUT /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments/sound12.mp3 HTTP/1.1
Content-Type: multipart/form-data; boundary=-----------boundary_69df8120352a996e

-----------boundary_69df8120352a996e
Content-Type: application/octet-stream
Content-Disposition: form-data; name="sound12.mp3"; filename="sound12.mp3"
Content-Transfer-Encoding: binary

BINARY BODY OF 'sound12.mp3'
-----------boundary_69df8120352a996e--

Ответ

Пример ответа
HTTP/1.1 204 No Content

Удаление файла

Запрос

Пример запроса
DELETE /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments/sound12.mp3 HTTP/1.1

Ответ

Пример ответа
HTTP/1.1 204 No Content

Получение мета-информации о файле

Возвращает мета-информацию о файле, содержащую в том числе размер в заголовке Content-Length.

Особенности

  • HTTP-ответ не содержит тела, несмотря на наличие заголовка Content-Length.

Запрос

Table 3. Параметры запроса
Имя Тип Описание

attachment

bool

Тип выдачи. По умолчанию false.

true – выдаётся с заголовком Content-Disposition: attachment; filename=filename.ext либо Content-Disposition: attachment; filename*=UTF-8''%d1%84%d0%b0%d0%b9%d0%bb.ext, где файл.ext – имя файла в кодировке UTF-8 и URLencoded.

false – выдается без заголовка Content-Disposition.
Пример запроса
HEAD /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments/sound12.mp3?attachment=true HTTP/1.1

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
Content-Type: audio/x-wav
Last-Modified: Thu, 19 Sep 2019 12:53:11 GMT
Content-Disposition: attachment; filename=sound12.mp3
Content-Length: 160042
Пример неуспешного ответа
HTTP/1.1 404 Not Found

Получение мета-информации о файле (METADATA)

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

Метод нестандартный и принимается в двух равнозначных формах: собственно методом (METADATA /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments/sound12.mp3) и методом POST по пути с суффиксом (POST /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments/sound12.mp3!metadata). Подробно — Нестандартные методы в пути.

Запрос не должен содержать тела ни в одной из форм: запрос с телом трактуется как заливка файла.

Особенности

  • Время в поле mtime возвращается в UTC в формате RFC 3339.

  • Контрольная сумма содержимого возвращается только по запросу с параметром hasha=true. Без параметра содержимое файла не читается, поэтому запрос дёшев независимо от размера файла.

Запрос

Table 4. Параметры запроса
Имя Тип Описание

hasha

bool

Добавить в ответ контрольную сумму содержимого. По умолчанию false.

Вычисление требует чтения файла целиком, поэтому на больших файлах параметр следует указывать только по явной необходимости.
Пример запроса
POST /rest/v1/uc/ivrscripts/0190f5a2-7c3e-7b41-9d2a-5e8c4f1b6a37/attachments/sound12.mp3!metadata HTTP/1.1

Ответ

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z"
}
Пример ответа с параметром hasha=true
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z",
  "hasha" : "md5;9f86d081884c7d659a2feaa0c55ad015"
}

Подробно: Мета-информация о файлах, каталогах и разделах.

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт