Пользовательские мелодии удержания, заменяющие стандартные (waitonholdcustom)

Обзор

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

Состав файлов произволен. Достаточно одного файла, чтобы каталог waitonhold перестал использоваться для воспроизведения. При постановке на удержание воспроизводится случайный файл из каталога (а если каталог пуст, то из хранилища waitonhold).

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

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

Доступ к каталогу из сценариев происходит с помощью префикса категории каталогов ":SYNC_COMMON/wait/hold".

Доступно только в мастер-домене.

Запросы

HTTP verb Endpoint Описание

POST

/rest/v1/fs/targets/waitonholdcustom

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

GET

/rest/v1/fs/targets/waitonholdcustom

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

GET

/rest/v1/fs/targets/waitonholdcustom/<filename>

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

PUT

/rest/v1/fs/targets/waitonholdcustom/<filename>

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

DELETE

/rest/v1/fs/targets/waitonholdcustom/<filename>

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

HEAD

/rest/v1/fs/targets/waitonholdcustom/<filename>

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

METADATA

/rest/v1/fs/targets/waitonholdcustom/<filename>

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

PUT

/rest/v1/fs/targets/waitonholdcustom/<filename>

Перемещение и переименование файла

METADATA

/rest/v1/fs/targets/waitonholdcustom

Операции над корнем раздела

CLEAR

/rest/v1/fs/targets/waitonholdcustom

Операции над корнем раздела

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

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

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

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

Запрос

Пример запроса
POST /rest/v1/fs/targets/waitonholdcustom 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="hold_music.wav"
Content-Transfer-Encoding: binary

BINARY BODY OF 'hold_music.wav'
-----------boundary_69df8120352a996e--

Ответ

Пример ответа
[
  {
    "name": "01.mp3",
    "size": 70985,
    "status": "ok"
  },
  {
    "name": "hold_music.wav",
    "size": 1596292,
    "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/fs/targets/waitonholdcustom HTTP/1.1

Ответ

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

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

[
  {
    "name": "F.zip",
    "size": 8411,
    "last_modified": "2019-09-20 10:30:43"
  },
  {
    "name": "Package.bin",
    "size": 12268,
    "last_modified": "2019-09-20 10:30:43"
  }
]

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

Запрос

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/fs/targets/waitonholdcustom/hold_music.wav?attachment=true HTTP/1.1

Ответ

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

BINARY BODY OF 'hold_music.wav'

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

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

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

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

Имя файла всегда берётся из URL.

Запрос с Content-Type: application/octet-stream и нулевой длиной тела создаёт пустой файл. Запрос без тела, без Content-Type и без заголовка X-Era-Source отвергается с кодом 400: по такому запросу невозможно определить намерение.

Метод PUT имеет ещё одно значение, отличающееся формой запроса: Перемещение и переименование файла.

Запрос

Пример запроса (octet-stream)
PUT /rest/v1/fs/targets/waitonholdcustom/hold_music.wav HTTP/1.1
Content-Type: application/octet-stream

BINARY BODY OF 'hold_music.wav'
Пример запроса (multipart)
PUT /rest/v1/fs/targets/waitonholdcustom/hold_music.wav HTTP/1.1
Content-Type: multipart/form-data; boundary=-----------boundary_69df8120352a996e

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

BINARY BODY OF 'hold_music.wav'
-----------boundary_69df8120352a996e--

Ответ

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

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

Запрос

Пример запроса
DELETE /rest/v1/fs/targets/waitonholdcustom/hold_music.wav 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/fs/targets/waitonholdcustom/hold_music.wav?attachment=true HTTP/1.1

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
content-type: audio/x-wav
last-modified: Fri, 20 Sep 2019 09:26:44 GMT
content-disposition: attachment; filename=hold_music.wav
content-length: 1596292
Пример неуспешного ответа
HTTP/1.1 404 Not Found

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

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

Метод нестандартный и принимается в двух равнозначных формах: собственно методом (METADATA /rest/v1/fs/targets/waitonholdcustom/hold_music.wav) и методом POST по пути с суффиксом (POST /rest/v1/fs/targets/waitonholdcustom/hold_music.wav!metadata). Подробно — Нестандартные методы в пути.

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

Особенности

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

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

Запрос

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

hasha

bool

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

Вычисление требует чтения файла целиком, поэтому на больших файлах параметр следует указывать только по явной необходимости.
Пример запроса
POST /rest/v1/fs/targets/waitonholdcustom/hold_music.wav!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"
}

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

Перемещение и переименование файла

Перемещает или переименовывает файл в пределах раздела, не передавая его содержимое.

Выполняется методом PUT по пути назначения с заголовком X-Era-Source и пустым телом. В заголовке указывается путь источника относительно корня раздела.

Запрос

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

overwrite

bool

Разрешить перезапись занятого пути назначения. По умолчанию false.
Пример запроса
PUT /rest/v1/fs/targets/waitonholdcustom/<filename> HTTP/1.1
X-Era-Source: inbox/hold_music.wav
Content-Length: 0

Ответ

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

Подробно: Перемещение и переименование файла.

Операции над корнем раздела

Помимо перечисления и заливки файлов, корень раздела поддерживает два метода.

Запрос Действие

METADATA /rest/v1/fs/targets/waitonholdcustom

Описание раздела и сведения о его корне: поддерживаемые операции, ограничения, число элементов верхнего уровня.

CLEAR /rest/v1/fs/targets/waitonholdcustom

Очистка раздела: удаляется всё содержимое, сам раздел остаётся. Операция рекурсивна и требует подтверждения ключом.

Удалить раздел нельзя: DELETE по пути корня всегда возвращает 405.

Подробно: Мета-информация и Операции над каталогами.

См. также

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