'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_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"
  }
]

Ссылки

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