Голосовое меню (/ivr/)
- Dmitri Savolainen
- Asia Khalitova (Unlicensed)
- Evgeniy
- Роман Сухов (Unlicensed)
Мы обновили документацию, актуальная версия страницы доступна по ссылке: Голосовое меню (/ivr/)
Добавочные номера типа ivr служат для настройки маршрутизации звонков внутри АТС с использованием информации, вводимой клиентом на клавиатуре телефона с помощью тонального набора.
Для конфигурации голосового меню необходимо создать добавочный , указав в качестве типа (type) значение ivr. После этого становится возможным конфигурация голосового меню через API-интерфейс ivr.
Звуковые файлы, которые необходимы для настройки голосового приветствия, загружаются в ресурс sound.
Важные понятия:
- Контекст. Представляет собой заранее сформированный набор правил, на которые можно сослаться в настройках. Каждый контекст как минимум содержит опции:
- start: описывает действия при вхождении в контекст
- timeout: описывает действия при наступлении таймаута (клиент не сделал никакого выбора в течении заданного промежутка времени)
- invalid: действия, наступающие при выборе клиентом опции, которая не сконфигурирована
Все опции по умолчанию выполняют действие hangup (повесить трубку) и это действие должно быть переопределено для задания необходимой логики.
За IVR закреплен так называемый "entry_context" - в него попадает вызов после прихода в голосовое меню. Его еще можно назвать главным контекстом - 'background'/'foreground' тип звучания голосового приветствия. В случае "background" система готова принимать тональный набор в любой момент, а 'foreground' обязывает пользователя прослушать запись до конца и лишь после этого делать выбор(если возможность такого выбора сконфигурирована)
Описание структур данных
Базовые параметры (ivr)
Имя | Тип | Обязательный | Значение По Умолчанию | Описание |
|---|---|---|---|---|
|
|
| идентификатор главного контекста | |
|
|
| время (в секундах) по истечении которого происходит принудительный выход из IVR | |
|
|
| Действия при выходе из IVR по наступлению lifetime
| |
|
|
| Переадресация на указанный номер при истечении lifetime и lifetime_exp_action='transfer' | |
|
|
| время (в миллисекундах) до начала выполнения любых действий после попадания вызова в ivr (может быть полезно, чтобы избегать выпадания первых слов в голосовом приветствии после установления соединения) |
Контекст (context)
Имя | Тип | Обязательный | Значение По Умолчанию | Описание |
|---|---|---|---|---|
|
|
| 5000 | время (в миллисекундах) ожидания начала набора после выполнения последнего правила в опции контекста. По истечении уход в опцию timeout |
|
|
| false | позволен ли донабор любого добавочного клиента |
|
|
| 2000 | время (в миллисекундах) ожидания следующей цифры. По истечении набор считается завершенным. Например, при "digit_len": 3, набор "30" будет принят по прошествии inter_digit_timeout |
|
|
| имя контекста | |
|
|
| длина добавочного клиента | после набора указанного количества цифр, ввод считается завершенным (без необходимости ожидания "inter_digit_timeout"). Также определяет максимальную длину возможного набора клиентом. Например, "digit_len": 3 позволяет набрать "7", "22", "300", но не дает возможности выбора "4000" |
Опция контекста (context_option)
Имя | Тип | Обязательный | Значение По Умолчанию | Описание |
|---|---|---|---|---|
|
|
| Добавляет к стандартным опциям конеткста (start,timout,invalid), пользовательскую опцию. Например, значение "2" задаст возможность обработки ввода цифры "2" после попадания в контекст |
Правило опции контекста (context_option_rule)
Имя | Тип | Обязательный | Значение По Умолчанию | Описание |
|---|---|---|---|---|
|
|
| Непосредственно определяет, что нужно сделать в этом правиле:
| |
|
|
| Проговорить указанные цифры (методом play_digits_method), обязателен при action= 'play_digits' | |
|
|
| Идентификатор звукового файла, который необходимо проиграть, обязателен при action= 'play_sound' | |
|
| нет | Обязателен при наличии идентификтора sound. Может принимать значения:
| |
|
|
| Обязателен при установленной опции digits. Может быть:
| |
|
|
| правило выполняется только в этом временном интервале | |
|
|
| определяет метод анализа источника вызова caller_id:
| |
|
|
| Правило будет работать только для вызовов, источник которых определяется этим полем. Поле заполняется в виде регулярного выражения PCRE. Например: "^(\+|)7812" будет соответствовать всем источникам, начинающимся на "+7812" или "7812" | |
|
|
| Определяет опцию контекста, в которую нужно перейти, при action='jump_to_context' | |
|
|
| Время (в миллисекундах) отсутствия каких-либо звуков со стороны АТС, обязателен при action= 'play_silence' | |
|
|
| Определяет идентификатор другого контекста, в который нужно перейти, обязателен при action='jump_to_context' | |
|
|
| Переадресация на указанный номер. Если нужна переадресация на несколько номеров одновременно (одновременный вызов), то эти номера перечисляются через пробел. Обязателен для action='transfer' | |
|
|
| Имя переменной, которая должна быть установлена. Должно начинаться с латинской буквы, может содержать латинские буквы, цифры, а также символы подчеркивания. Обязателен для action='set_variable | |
|
|
| Значение переменной, которая должна быть установлена. Обязателен для action='set_variable' | |
match_variable_name | string | нет | Имя переменной IVR, значение которой будет сравниваться со значением, заданным параметром match_variable_value. Если значения совпадут, то правило выполнится. Сравниваемая переменная может быть установлена системой, см. раздел "Предустановленные переменные в IVR", либо задана правилом опции контекста типа set_variable. | |
match_variable_value | string | нет | Значение, которое будет сравниваться со значением переменной, имя которой задано параметром match_variable_name. Если значения совпадут, то правило выполнится. Обязателен, если задан параметр match_variable_name. | |
|
|
| Имя переменной, значение которой будет использовано в качестве номера для переадресации. Если переменная не установлена, то действие не выполняется. Переменная может быть установлена с помощью действия set_variable, record_digits, либо с помощью функции Call Interactive. Обязателен при action= 'transfer_from_variable' | |
|
|
| Имя переменной, значение которой будет использовано для проигрывания цифр. Если переменная не установлена, то действие не выполняется. Переменная может быть установлена с помощью действия set_variable, record_digits, либо с помощью функции Call Interactive. Обязателен при action= 'play_digits_from_variable' | |
|
|
| Имя переменной, в которую будут записаны введённые цифры. Обязателен при action= 'record_digits' | |
| integer |
| Максимальное количество введённый цифр, который будут записаны в переменную. Обязателен при action= 'record_digits' | |
| max_rate | integer | нет | 5 | Максимальная оценка разговора, параметр, только для действия quality_rate |
| integer |
| Идентификатор звукового файла, который может быть проигран перед записью ввёденных цифр в переменную. | |
|
|
| URL, на который будет осуществляться HTTP-запрос функцией Call Interactive. Должен начинаться с http:// или c https://. Обязателен для action='call_interactive' | |
|
|
| Метод, которым будет осуществляться HTTP-запрос функцией Call Interactive . Может принимать значение 'GET' или 'POST'. Обязателен для action='call_interactive' | |
|
|
| 5 | Время в секундах, в течение которого система будет ожидать ответ на HTTP-запрос функции Call Interactive. Если вызываемый URL не вернул ответ по истечении этого времени, то выполняется следующее правило. |
|
|
| Номер звонящего для дальнейших переадресаций. Данный параметр может содержать в себе имена переменных, установленных в других действиях ранее, а также предустановленных переменных IVR. Имена переменных указываются в формате ${имя_переменной}. Обязателен при action= 'set_caller_id_number' | |
|
|
| Имя звонящего для дальнейших переадресаций. Данный параметр может содержать в себе имена переменных, установленных в других действиях ранее, а также предустановленных переменных IVR. Имена переменных указываются в формате ${имя_переменной}. Обязателен при action= 'set_caller_id_name' | |
| play_sound_from_variable | boolean | нет | false | Для правил play_sound, quality_rate, voice_helper доступен параметр play_sound_from_variable. В этой системной переменной может хранится приветствие, синтезированное с помощью действия text_to_speech в call interactive: Call Interactive#TTS В случае, если синтезированного приветствия нет, а play_sound_from_variable активен- будет проигран звуковой файл по-умолчанию, указанный в sound |
Предустановленные переменные в IVR
| Имя переменной | Описание |
|---|---|
called_did | Публичный номер (DID), на который пришел вызов в систему. Если вызов локальный, переменная содержит номер IVR без префикса клиента. |
caller_id_name | Имя звонящего |
caller_id_number | Номер звонящего |
Пример
Для клиента с уникальным идентификатором 12, нужно создать IVR с номером "071" при попадании в который действуют правила:
- Проиграть foreground музыкальный файл "advertising.wav" 1 раз
- Проиграть background музыкальный файл "hello.wav" и в случае отсутствия выбора клиента автоматически переводить на добавочный 050
- При наборе "1" перевод на мобильный +7(987)6543210
- При наборе "2" перевод на добавочный 002
- Позволять прямой набор трехзначных добавочных номеров
Действия:
Используя ресурс sound, нужно загрузить файл hello.wav и advertising.wav
user@host$ curl -i -X POST -Ffile=@hello.wav -F"title=мой файл приветствия"-H"Authorization: Bearer TSyAxXtAsbE9Kl0iAVGG6LmnfEte8X"https://host.domain/api/ver1.0/client/12/sound/HTTP/1.1 100 ContinueHTTP/1.1 201 CREATEDServer: nginx/1.8.0Date: Tue, 11 Aug 2015 09:50:41 GMTContent-Type: application/jsonContent-Length: 150Connection: keep-aliveAccess-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, OPTIONSAccess-Control-Allow-Headers: Content-Type, api_key, Authorization{"id": 51,"client_id": 12,"title":"мой файл приветствия"}user@host$ curl -i -X POST -Ffile=@advertising.wav -F"title=мой файл рекламы"-H"Authorization: Bearer TSyAxXtAsbE9Kl0iAVGG6LmnfEte8X"https://host.domain/api/ver1.0/client/12/sound/HTTP/1.1 100 ContinueHTTP/1.1 201 CREATEDServer: nginx/1.8.0Date: Tue, 11 Aug 2015 09:50:41 GMTContent-Type: application/jsonContent-Length: 150Connection: keep-aliveAccess-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, OPTIONSAccess-Control-Allow-Headers: Content-Type, api_key, Authorization{"id": 52,"client_id": 12,"title":"мой файл рекламы"}идентификаторы новых файлов: hello.wav "id": 51; advertising.wav "id": 52
Используя ресурс extension, создать добавочный, типа "ivr"
методресурсданныеответPOST client/@me/extension/
{
"status": "active",
"name": "071",
"label": "тестовый IVR",
"type": "ivr"
}{
"status": "active",
"name": "000*071",
"extra_params": null,
"label": "тестовый IVR",
"client_id": 12,
"extension_group_id": null,
"type": "ivr",
"id": 204
}Идентификатор нового добавочного "id": 204
Создаем контекст, который будет являться главным (entry_context):
методресурсданныеответPOST /extension/204/ivr/context/
{
"digit_len": 3,
"allow_any_dial": true,
"inter_digit_timeout": 2000,
"name": "Основной контекст",
"timeout": 5000
}{
"name": "Основной контекст",
"inter_digit_timeout": 2000,
"timeout": 5000,
"allow_any_dial": true,
"id": 1,
"digit_len": 3
}Идентификатор контекста "id": 1
Теперь можно привязать этот контекст ,как главный к нашему IVR, заодно указываем "sleep-time", позволяющий задать паузу от прихода вызова в IVR до начала каких-либо действий контекста "entry_context"
методресурсданныеответPUT extension/204/ivr/
{
"sleep_time": 5000,
"entry_context": 1
}{
"lifetime_exp_transfer_dst": null,
"lifetime_exp_action": "hangup",
"lifetime": 1800,
"sleep_time": 5000,
"entry_context": 1
}Как отмечалось ранее, каждый контекст уже имеет опцию start. Сконфигурирем его для проигравания foreground музыкального файла "advertising.wav"
методресурсданныеответPOST extension/204/ivr/context/1/options/start/rules/
{
"sound": 52,
"sound_type": "foreground",
"action": "play_sound"
}{
"digits": null,
"sound": 52,
"sound_type": "foreground",
"play_digits_method": null,
"interval": null,
"caller_id_action": "any",
"caller_id": null,
"context_option": null,
"silence_time": null,
"context": null,
"transfer_dst": null,
"action": "play_sound",
"id": 1
}Далее, по аналогии, укажем воспроизвести файл hello.wav в background
методресурсданныеответPOST extension/204/ivr/context/1/options/start/rules/
{
"sound": 51,
"sound_type": "background",
"action": "play_sound"
}{
"digits": null,
"sound": 51,
"sound_type": "background",
"play_digits_method": null,
"interval": null,
"caller_id_action": "any",
"caller_id": null,
"context_option": null,
"silence_time": null,
"context": null,
"transfer_dst": null,
"action": "play_sound",
"id": 2
}Теперь в контексте "Основной контекст", добавим возможность обработки выбора "1"
методресурсданныеответPOST /extension/204/ivr/context/1/options/
{
"digits": "1"
}{
"digits": "1"
}И укажем, что хотим делать для выбора "1" (перевод на мобильный +7(987)6543210)
методресурсданныеответPOST /extension/204/ivr/context/1/options/1/rules/
{
"transfer_dst": "+7987654321",
"action": "transfer"
}{
"digits": null,
"sound": null,
"sound_type": null,
"play_digits_method": null,
"interval": null,
"caller_id_action": "any",
"caller_id": null,
"context_option": null,
"silence_time": null,
"context": null,
"transfer_dst": "+7987654321",
"action": "transfer",
"id": 3
}По аналогии добавим вызов добавочного "002" по набору "2"
методресурсданныеответPOST /extension/204/ivr/context/1/options/
{
"digits": "2"
}{
"digits": "2"
}методресурсданныеответPOST /extension/204/ivr/context/1/options/1/rules/
{
"transfer_dst": "002",
"action": "transfer"
}{
"digits": null,
"sound": null,
"sound_type": null,
"play_digits_method": null,
"interval": null,
"caller_id_action": "any",
"caller_id": null,
"context_option": null,
"silence_time": null,
"context": null,
"transfer_dst": "002",
"action": "transfer",
"id": 4
}Осталось в случае отсутствия выбора клиента автоматически переводить на добавочный 050. Как уже отмечалсь, в контектсте есть опция "timeout", в которой можно задать это действие
методресурсданныеответPOST /ivr/144/context/2/options/timeout/rules/
{
"transfer_dst": "050",
"action": "transfer"
}{
"digits": null,
"sound": null,
"sound_type": null,
"play_digits_method": null,
"interval": null,
"caller_id_action": "any",
"caller_id": null,
"context_option": null,
"context": null,
"transfer_dst": "050",
"action": "transfer",
"id": 5
}В итоге можно посмотреть все доступные опции контекста:
методресурсданныеответGET /extension/204/ivr/context/1/options/
[
{
"digits": "start"
},
{
"digits": "timeout"
},
{
"digits": "invalid"
},
{
"digits": "2"
},
{
"digits": "1"
}
]
Ресурсы
Раздел "добавочный"
PUT /extension/{extension_id}/ivr/
Обновить ivr configuration
Параметры URL
Имя | Тип |
|---|---|
|
|
Параметры JSON
Имя | Тип | Обязательный |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GET /extension/{extension_id}/ivr/
Получить ivr configuration
Параметры URL
Имя | Тип |
|---|---|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
POST /extension/{extension_id}/ivr/context/
Добавить ivr context
Параметры URL
Имя | Тип |
|---|---|
|
|
Параметры JSON
Имя | Тип | Обязательный |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
GET /extension/{extension_id}/ivr/context/
Получить ivr context list
Параметры URL
Имя | Тип |
|---|---|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
PUT /extension/{extension_id}/ivr/context/{context_id}
Обновить ivr context
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
Параметры JSON
Имя | Тип | Обязательный |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
GET /extension/{extension_id}/ivr/context/{context_id}
Получить ivr context
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
DELETE /extension/{extension_id}/ivr/context/{context_id}
Удалить ivr context
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
POST /extension/{extension_id}/ivr/context/{context_id}/options/
Добавить context option
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
Параметры JSON
Имя | Тип | Обязательный |
|---|---|---|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
GET /extension/{extension_id}/ivr/context/{context_id}/options/
Получить context options list
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
DELETE /extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}
Удалить context option
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
|
|
POST /extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}/rules/
Добавить context rule
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
|
|
Параметры JSON
Имя | Тип | Обязательный |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| max_rate | integer | нет |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GET /extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}/rules/
Получить context rules list
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
PUT /extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}/rules/order/
Udpate context option rules order
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
|
|
Параметры JSON
Имя | Тип | Обязательный |
|---|---|---|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
GET /extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}/rules/order/
Получить context option rules order
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
PUT /extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}/rules/{rule_id}
Обновить context rule
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
Параметры JSON
Имя | Тип | Обязательный |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GET /extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}/rules/{rule_id}
Получить context rule
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
|---|---|
Имя | Тип |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
DELETE /extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}/rules/{rule_id}
Удалить context rule
Параметры URL
Имя | Тип |
|---|---|
|
|
|
|
|
|
|
|
Теги по теме