Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Протестировать методы API можно на странице интерактивного обозревателя API и без написания кода
Некоторые ресурсы, описанные на странице, по умолчанию могут быть не доступны из-за типа приложения (см. Создание и авторизация приложений)

Функция Call Interactive позволяет инициировать HTTP-запрос на заданный URL и обработать ответ на него. Call Interactive может быть использован в качестве действия опции контекста голосового меню (IVR), либо для обычных исходящих вызовов с телефонного терминала (настройка выполняется в клиентской конфигурации). С запросом передается постоянный набор параметров, содержащий информацию о вызове. Данные параметры располагаются в строке запроса (при методе GET) или в теле запроса (при методе POST). URL и метод запроса могут быть заданы при настройке

Конфигурация Call Interactive

Для конфигурации функции Call Interactive требуется указать два параметра: URL, на который системой будет осуществляться запрос, и метод (GET или POST). При выбранном методе GET параметры запроса, содержащие информацию о вызове, будут переданы в строке запроса, а при методе POST –  в теле запроса. 

Table of Contents
maxLevel2

Параметры запроса Call Interactive IVR

Expand
titleРазвернуть

Имя

Тип

Описание

EventType

string

Тип события, всегда имеет значение call_interactive

CallID

string

Уникальный идентификатор вызова

CallerIDNum

string

Номер вызывающего абонента

CallerIDName

string

Имя вызывающего абонента

CalledDID

string

Внешний вызываемый номер. Присутствует, если доступен

CalledExtension

string

Номер IVR в расширенном формате (например: yyyy*zzz)

CalledExtensionID

integer

Идентификатор внутреннего номера типа ‘IVR’ в системе

CallStatus

string

Статус вызова, всегда имеет значение ANSWER

CallFlow

string

Поток вызовов, всегда имеет значение IN

CallerExtension

string

Имя внутреннего номера, осуществляющего вызов IVR. Присутствует только при внутреннем вызове

CallerExtensionID

integer

Идентификатор внутреннего номера, осуществляющего вызов IVR. Присутствует только при внутреннем вызове

CalledNumber

string

Номер, который набирала вызывающая сторона. Может быть внешним номером (например: 003258422544), номером IVR в расширенном формате (например: 0003*001) или коротким номером IVR (например: 001).

CallAPIID

string

Идентификатор звонка. Автоматически генерируется и сохраняется на протяжении всего звонка вне зависимости от того, переводится ли он

Опциональные параметры запроса Call Interactive IVR

Могут присутствовать в запросе call_interactive, если правило call_interactive идет после правила voice_helper

Имя

Тип

Описание

voice_navigator_DTMF

string

Донабор с телефонного терминала во время правила голосового меню action='voice_helper'

voice_navigator_STT

string

Содержит распознавание голоса во время правила голосового меню action='voice_helper'

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

Может присутствовать в запросе call_interactive, если правило call_interactive идет после правила quality_rate

Имя

Тип

Описание

quality_rate

string

Оценка разговора (quality rate)

Параметры запроса Call Interactive исходящий вызов

Expand
titleРазвернуть

Имя

Тип

Описание

EventType

string

Тип события, всегда имеет значение call_interactive

CallID

string

Уникальный идентификатор вызова

CallerIDNum

string

Номер вызывающего абонента

CallerIDName

string

Имя вызывающего абонента

CallFlow

string

Поток вызовов, всегда имеет значение OUT

CallerExtension

string

Имя внутреннего номера, осуществляющего вызов IVR.

CallerExtensionID

integer

Идентификатор внутреннего номера, осуществляющего вызов IVR.

CalledNumber

string

Номер, который был набран на телефонном терминале. Можно подменить действием SetToNum

CallAPIID

string

Идентификатор звонка. Автоматически генерируется и сохраняется на протяжении всего звонка вне зависимости от того, переводится ли он

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

Code Block
languagehtml
http://mysite.com/myscript?CalledExtensionID=145&CalledNumber=332&CallID=5205dc5cc5a411e5ab9eb3691b90ea15&CallerIDNum=000%2A306&CallerExtensionID=134&CallerExtension=000%2A306&CallFlow=IN&CalledExtension=000%2A332&CallAPIID=3584705175%3A5205dc5cc5a411e5ab9eb3691b90ea15&CallerIDName=000%2A306&CallStatus=ANSWER

Переменные в строке запроса

В строке запроса могут быть переданы дополнительные параметры, содержащиеся в URL. Эти могут принимать как статические значения, так и значения переменных, заданных в IVR ранее. Для того, чтобы использовать в URL значение переменной, необходимо использовать формат $varname, где varname – это имя требуемой переменной.

Если выбран метод запроса GET, параметры, содержащие информацию о вызове, добавятся к уже существующим параметрам URL.

Пример URL со статическими параметрами:

Code Block
languagehtml
http://mysite.com/myscript?param1=value1&param2=value2

Пример URL с параметрами-переменными:

Code Block
http://mysite.com/myscript?param1=$var&param2=$var2

Структура ответа

Ответ на запрос Call Interactive не является обязательным и нужен, если требуется совершить какое-либо действие.
Ответ на запрос должен быть сформирован в формате XML и иметь следующую структуру:

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
     Action
</Response>

где Action может быть одним из перечисленных ниже действий.

Info

Допускается до 10 действий включительно в одном ответе, исключениями из этого правила являются действия: hangup, SimpleTransfer, TTS (Text to speech) - после этих действий остальные будут проигнорированы.

Варианты действий ответа на Call Interactive IVR

Expand
titleРазвернуть

Hangup

Немедленно завершает звонок.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Hangup/>
</Response>

Pause

Приостанавливает звонок на заданное атрибутом length тега Pause число секунд. Если значение не задано, то по умолчанию принимается 10.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Pause length="15" />
</Response>

SetVar

Задает значение переменной для IVR. Имя переменной должно содержатся в атрибуте name тега SetVar, а значение – содержимым этого тега.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SetVar name="transferDestination">09897987</SetVar>
</Response>

Jump

Осуществляет переход к заданной опции заданного контекста IVR. Идентификатор контекста и опция задаются атрибутами context и option тега Jump.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Jump context="3" option="start"/>
</Response>

SetCallerId

Задает номер вызывающего абонента и имя вызывающего абонента в среде IVR. Номер и имя задаются атрибутами name и number тега SetCaller.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SetCaller name="callerName" number="92992"/>
</Response>

PlaySound

Проигрывает звук, имя файла которого задано содержимым тега PlaySound. Имя файла можно получить из API как параметр filename ресурса “Звуковые файлы (/sound/)”. Атрибутом where тега PlaySound указывается тип проигрывания звука: foreground или background. При проигрывании типа background возможен ввод цифр в переменную, имя которой указывается в атрибуте digitvar тега PlaySound.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <PlaySound where="background" digitvar="transferDestination">ae3d969ccc49e1a7746e0b1ce36ee4176190040c.wav</PlaySound>
</Response>

SimpleTransfer

Вызов через правило переадресации simple transfer игнорирует настройки внутреннего номера и правила переадресации внутреннего номера. Ответ, аналогичный заранее определенному правилу simple transfer. Возможно указать как один, так и несколько номеров (NUM1,NUM2), разделенных запятой, пробелы не должны присутствовать. Правило по умолчанию финальное (final='yes'), в том числе при отсутствии указания final, за исключением случаев, если не указано final="no".

Параметр timeout задает время ожидания ответа вызовов в секундах. В случае некорректного указания timeout либо отсутствия данного параметра будет использован системный timeout. Также, при необходимости, можно добавить параметр early_media="True" (именно в таком формате), в таком случае early media не будет игнорироваться.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SimpleTransfer final="no" timeout="20">NUM1,NUM2</SimpleTransfer>
</Response>

TTS — Text to speech

Info

Работает только при активированной функции speech_to_text в клиентской конфигурации (эта настройка доступна только администратору платформы)

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <TTS lang="ru-RU" voice="alena" speed="2.0" play_now="true" save_to_var="false" >текст для озвучки</TTS>
</Response>

Параметр lang – язык чтения текста. Если язык не указан, то будет использован язык по умолчанию – русский (ru-RU). Также доступны варианты:

  • en-US – английский язык;

  • tr-TR – турецкий язык.

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

Code Block
languagexml
ru_voices = {'voices': ['oksana', 'jane', 'omazh', 'zahar', 'ermil', 'alena', 'filipp'], 'def': 'oksana'}
en_voices = {'voices': ['alyss', 'nick'], 'def': 'alyss'}
tr_voices = {'voices': ['silaerkan', 'erkanyavas'], 'def': 'silaerkan'}

Параметр speed – скорость чтения текста. Доступен только из следующего диапазона:
[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 3.0]

Info

Для передачи слов-омографов используйте знак «+» перед ударной гласной: з+амок, зам+ок.
Чтобы отметить паузу между словами, используйте знак «-».
Рекомендуемая максимальная длина строки — 500 символов

Параметр play_now может принимать значения "true" либо "false". Информирует о том, нужно ли проиграть синтезированное приветствие сразу. Отложить проигрывание приветствия можно с помощью дополнительного параметра save_to_var="true".
Проигрывание приветствия из переменной доступно в правилах голосового меню play_soundquality_rate и voice_helper.
Возможны комбинации:

  • play_now="true", save_to_var="false" – приветствие проиграется проигрывается сразу же;

  • play_now="true", save_to_var="true" – приветствие проиграется проигрывается сразу же, а также его можно будет использовать дальше в логике IVR;

  • play_now="false", save_to_var="true" – приветствие не проиграетсяпроигрывается, но его можно будет использовать дальше в логике IVR;

  • play_now="false", save_to_var="false" – ничего не проиграетсяпроигрывается, такой ответ на Call Interactive будет проигнорирован.

Варианты действий ответа на Call Interactive исходящий вызов

Expand
titleРазвернуть

Hangup

Немедленно завершает звонок.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Hangup/>
</Response>

SetAni

Задает определение номера при вызове в транк (Ани= автоматичская идентификация номера). Задает определение заданное атрибутом did тега SetAni. Значение должно быть из списка клиентских did, в обратном случае вызов будет завешен ошибкой.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SetAni did="79847845789" />
</Response>

SetToNum

Меняет вызываемый номер. Атрибут to_num тега SetToNum.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SetToNum to_num="79847845789" />
</Response>