Versions Compared

Key

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


Warning

Мы обновили документацию, актуальная версия страницы доступна по ссылке: Call Interactive

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

Table of Contents

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

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

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

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


 

Имя

Тип

Описание

EventType

string

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

CallID

string

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

CallerIDNum

string

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

CallerIDName

string

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

CalledDID

string

Вызываемый номер телефонной сети общего пользования (

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

)

.

CalledExtension

string

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

CalledExtensionIDintegerИдентификатор добавочного IVR в системе

CallStatus

string

Статус вызова

. Параметр может принимать следующие значения (в зависимости от типа события):

Для событий типа Dial-In и Dial-Out параметру задается значение CALLING.
Для событий типа Hangup параметр может принимать следующие значения:

  • ANSWER — звонок принят, вызываемая сторона вышла на связь с вызывающей; звонок успешен;
  • BUSY — вызывающая сторона получает сигнал «занято»; команда набора номера достигла вызываемой стороны, но та оказалась занята;
  • NOANSWER — ответа на звонок не последовало; команда набора номера достигла вызываемой стороны, звонок осуществлялся предельно долгое время вплоть до его истечения;
  • CANCEL — звонок отменен; команда набора номера достигла вызываемой стороны, но вызывающая сторона завершила звонок до «снятия трубки» вызываемой;
  • CONGESTION — перегрузка сети; обычно данный статус говорит о том, что вызываемый номер не опознан;
  • CHANUNAVAIL — канал недоступен; в SIP-сети данный статус может говорить о том, что абонент не зарегистрирован.

    , всегда имеет значение ANSWER

    CallFlow

    string

    Поток вызовов

    . Всегда должен иметь значение «IN».

    , всегда имеет значение IN

    CallerExtension

    string

    Добавочный номер

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

    Только на случай вызова в пределах одного сервера

    Присутствует только при внутреннем вызове

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

    CalledNumber

    string

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

    CallAPIID

    string

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

    Эта переменная может использоваться для идентификации звонка в службе Call Events, если он был создан посредством запроса к UnifiedAPI.

     

    ...

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

    Могут присутствовать в запросе call_intercative


    Имя

    Тип

    Описание

    voice_navigator_DTMF

    string

    Донабор с телефонного терминала во время правила Голосовое меню (/ivr/) action voice_helper

    voice_navigator_STT

    string

    Содержит распознавание голоса во время правила Голосовое меню (/ivr/) action voice_helper

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

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

    Code Block
    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
    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 может быть одним из перечисленных ниже действий. 

    Допускается до 10 действий включительно в одном ответе.

    Варианты действий

    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

    Работает только при активированной функции 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
    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]

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


    play_now: "true", либо "false" инструктирует о том, нужно ли проиграть сразу синтезированное приветствие, отложить проигрывание приветствия можно с помощью дополнительного параметра save_to_var="true".

    Проигрывание приветствия из переменной доступно в правилах /ivr/ play_sound, quality_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 будет проигнорирован.