'ivrapi' capability для WebSocket Token API

Обзор

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

Запросы

Взятие управления

Чтобы принять управление во внешнем модуле, в сценарии IVR должен быть размещен компонент Внешнее управление через API. В момент, когда начинается его обслуживание в конкретной сессии, подписчикам отправляется событие 'ivrevents.api_start' с привязкой к этой сессии и конкретному компоненту. Соответственно приложение должно быть подписано на события класса ivrevents.

После получения события любое из приложений может принять управление отправкой запроса ivrapi_accept через API текущего модуля. Только одно подключение может захватить управление - то, чей запрос ivrapi_accept будет первым обработан. В дальнейшем можно перехватить управление отправкой запроса ivrapi_reaccept, что имеет смысл в случае разрыва websocket-соединения.

Отказаться от управления можно отправкой запроса ivrapi_abort. В этом случае сценарий продолжит выполнение следующего компонента. Также управление следует прекратить при получении события 'ivrevents.api_stop'. В этом случае не требуется отправлять никаких запросов в связи с управляемой сессией.

Поле key в запросах должно содержать значение, совпадающее с аналогичным значением из события ivrevents.api_start.

Пример события 'ivrevents.api_start'
[
  "notify",
  {
    "class": "ivrevents",
    "type": "api_start",
    "eventts": 1602002803754,
    "data": {
      "callid": "rB2-002-SuDtIE-01-2582368067@192.168.0.149",
      "cid": "267278f0-0642-00af-0ac9-b80000000006",
      "componentid": 14,
      "componentname": "Внешнее управление 3",
      "ivrid": "rDlg-006-ZevQbP",
      "ivrts": 1602002800707,
      "key": "abc",
      "params": "{\"asdf\":\"zxcv\"}",
      "sm_id": "f9098ae9-0642-00af-0ad1-880000000006"
    }
  }
]

Принятие управления (ivrapi_accept)

Пример
[
  "ivrapi_accept",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll"
  }
]

Перехват управления (ivrapi_reaccept)

Пример
[
  "ivrapi_reaccept",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll"
  }
]

Возврат управления (ivrapi_abort)

Пример
[
  "ivrapi_abort",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll"
  }
]

Инициация компонентов

Во время принятого управления внешнему модулю доступно выполнение любых стандартных компонентов сценария запросом ivrapi_component_apply. Инициированный таким образом компонент может быть прерван запросом ivrapi_component_terminate.

Инициация выполнения стандартного компонента (ivrapi_component_apply)

Для инициации компонента необходимо разместить в поле data объект с настройками компонента в соответствии с тем, как описано в документации по компонентам.

  • Обязательно должно присутствовать поле oType, сообщающее системе о типе компонента (из перечня компонентов платформы Era).

  • Другие свойства, настраивающие компонент.

  • Поля name, oId дефолтятся и могут быть опущены, хотя oId будет сообщаться в событиях.

  • Необязательно заполнять свойства transfer*, а также те, которые возвращают значения - они декорируются автоматически.

  • Необязательными также являются поля, имеющие значения по умолчанию, а также не используемые при выбранных режимах работы компонента.

  • При завершении компонента отправляется событие ivrapi_component_stopped (ниже), сообщающее по какой ветке перехода компонент вышел, а также список всех возвращаемых значений, в обычном режиме сохраняемых в переменные.

  • Типы компонентов и их свойства - в документации к платформе Era.

  • Можно пользоавться следующим подходом - создать сценарий через админку, настроить компонент, сохранить сценарий, открыть его содержание, найти компонент в json и взять его содержимое в качестве data.

Вплоть до получения события о завершении работы компонента не следует пытаться инициировать новые компоненты - система отфильтрует эти запросы и будет отвечать на них ошибкой.

Пример инициации простого воспроизведения
[
  "ivrapi_component_apply",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll",
    "data": {
      "oType": 204,
      "mode": 0,
      "file": ":GS_PUB/x/y/14.mp3"
    }
  }
]
Пример инициации записи
[
  "ivrapi_component_apply",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll",
    "data": {
      "oType": 208,
      "recTimeSec": "10",
      "maxSymbolCount": "3",
      "interruptSymbols": "4, 5, 6",
      "abortOnSilence": 0
    }
  }
]
Пример ответа по завершении компонента записи
[
  "ivrapi_component_apply_result",
  {
    "qid": 0.1234,
    ...
  }
]
Примеры других компонентов
// Пример перевода звонка
"data": {"oType":203, "number": "13", "reinviteMode":2}

// Завершение звонка
"data": {"oType":201}

// Воспроизведение ранее загруженного во временную папку файла
"data": {"oType":204, "mode":0, "file":":TEMP/14.mp3"}

Прерывание выполнения ранее инициированного компонента (ivrapi_component_terminate)

Ранее инициированный компонент может быть корректно прерван в любое время. Переходить к инициации следующего компонента следует дождавшись ответа на отправленный запрос.

Пример
[
  "ivrapi_component_terminate",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll"
  }
]

Вызов метода исполняемого компонента (ivrapi_component_fun)

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

Пример
[
  "ivrapi_component_fun",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll",
    "method": "some_method",
    "data": {"param1": 1, "param2": "value2", "something_else": true}
  }
]

Добавление абонента к двухшаговому переводу (ivrapi_dialer_add)

Ранее инициированный компонент "Перевод с сопровождением" позволяет осуществлять добавление и удаление форков.

Уникальным идентификатором форка является номер (параметр "to"). Один и тот же номер добавить несколько раз нельзя, но если вызов предыдущего форка уже прекратился, то повторять можно.

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

Первый (или несколько первых) форков запускаются сразу вместе с компонентом на номер (или перечисленные через запятую номера). Компонент не позволяет задать для каждого из них особый таймаут ожидания ответа, однако каждый из них может быть остановлен командой 'ivrapi_dialer_remove'.

Компонент перевода завершает работу при успехе, а также если срабатывает общий таймаут или удаляется последний форк (в том числе командой ivrapi_dialer_remove, или по установленному для форка таймауту).

Пример
[
  "ivrapi_dialer_add",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll",
    "to": "304",
    "timeout": 10
  }
]

Удаление абонента из двухшагового перевода (ivrapi_dialer_remove)

Ранее инициированный компонент "Перевод с сопровождением" позволяет осуществлять добавление и удаление форков.

Любой активный форк (консультационный вызов первого шага двухшагового перевода) может быть удален, пока он не прислал финальный ответ 2xx. Уникальным идентификатором форка является номер (параметр "to").

Компонент перевода завершает работу при успехе, а также если срабатывает общий таймаут или удаляется последний форк (в том числе командой ivrapi_dialer_remove, или по установленному для форка таймауту).

Пример
[
  "ivrapi_dialer_remove",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll",
    "to": "304"
  }
]

Работа с файлами

Получение временной ссылки на скачивание файла (ivrapi_file_get_path)

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

Такой файл может быть скачан внешней системой через публичную ссылку в REST-API, пока сценарий активен. Для этого необходимо получить эту публичную ссылку с помощью данного запроса. Ссылка будет доступна в течение 5 минут. Даже если сценарий к этому времени завершится.

Пример
[
  "ivrapi_file_get_path",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll",
    "path": ":TEMP/ivr_records/ivr_000006_1602234901218.wav"
  }
]

Заливка файла во временную папку сценария (ivrapi_file_upload_temp)

При необходимости воспроизвести динамический файл, или отправить факс, почту и т.д. может потребоваться залить файл на сервер и сделать его доступным сценарию для последующего использования компонентами. Для этого необходимо выполнить данный запрос. Сервер самостоятельно скачает файл с указанного URL, разместит его во временном каталоге сценария и вернет корректный путь для использования в компонентах сценариев. Файл автоматически будет удален после завершения сценария.

Пример
[
  "ivrapi_file_upload_temp",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll",
    "url": "http://192.168.0.112/14.mp3"
  }
]

Заливка файла в статическое хранилище (ivrapi_file_upload_static)

В некоторых случаях может понадобиться в большом количестве одновременно работающих сценариев или на среднесрочной перспективе воспроизводить один и тот же файл. Заливка его в каждую сессию может быть неприемлема в силу естественно возникающей паузы, а также нагрузки на сеть. В этом случае файл может быть загружен в статическую папку заблаговременно, а затем применяться в любых сценариях. Загрузка производится в указанное файловое хранилище в том виде, как задаются пути при настройке сценариев (поле destpath). Необходимо выполнить данный запрос. Сервер самостоятельно скачает файл с указанного URL, разместит его по указанному пути. При последующей инициации компонентов в качестве путей к файлу следует указывать то же значение, что находится в поле destpath.

Пример запроса
[
  "ivrapi_file_upload_temp",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll",
    "url": "http://192.168.0.112/14.mp3",
    "destpath": ":GS_PUB/x/y/"
  }
]
Пример ответа
[
  "ivrapi_file_upload_static_result",
  {
    "qid": 0.1234,
    "result": ":GS_PUB/a/b/c/abc.wav"
  }
]

Основные наименования путей для размещения:

  • :SYNC_COMMON или :SYN_MEDIA

  • :SYNC_DOMAIN_DATA или :SYN_DOM

  • :SYNC_DOMAIN_COMMON или :SYN_DOM_MEDIA

  • :SITESHARE_PUBLIC или :SS_PUB

  • :SITESHARE_DOMAIN_DATA или :SS_DOM

  • :GLOBALSHARE_PUBLIC или :GS_PUB

  • :GLOBALSHARE_DOMAIN_DATA или :GS_DOM

Стандартным значением считается :SYNC_DOMAIN_DATA.

Заливка может производиться также без ссылки на сессию со взятым управлением. Для этого служит метод `file_upload_static'

[ "file_upload_static", { "qid": 123, "url": "http://192.168.0.12/abc.wav", "destpath":":GS_PUB/a/b/c" } ] ---

[ "file_upload_static_result", { "qid": 123, "result": ":GS_PUB/a/b/c/abc.wav" } ] ---

События

Завершение работы компонента (ivrapi_component_stopped)

Пример
[
  "ivrapi_component_stopped",
  {
    "oId": 0,
    "transferKey": "transfer",
    "results": {
      "dtmfBuffer": "78"
    }
  }
]

Получен DTMF (ivrapi_dtmf)

Событие дублирует сообщение callevents.dtmf, но приходит раньше и только в рамках захваченного управления через API.

Пример получения DTMF вне инициированного компонента:
[
  "ivrapi_dtmf",
  {
    "key": "abc",
    "ivrid": "rDlg-006-WbVFRX",
    "mode": "idle",
    "dtmf":"5"
  }
]
Пример получения DTMF в рамках инициированного компонента:
[
  "ivrapi_dtmf",
  {
    "key": "abc",
    "ivrid": "rDlg-006-WbVFRX",
    "mode": "component",
    "oId": 0,
    "dtmf": "5"
  }
]

Ссылки

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