'ivrapi' capability for WebSocket Token API

Overview

Provides an interface for taking control of the IVR script and initiating call processing by various components.

Requests

Taking control

To accept control in an external module, the IVR script must host the component External Control via API. The moment its service starts in a specific session, an event 'ivrevents.api_start' is sent to subscribers with a binding to that session and specific component. Accordingly the application should be signed to class events ivrevents.

After receiving the event, either application can take control of sending an ivrapi_accept request through the current module’s API. Only one connection can take control - the one whose ivrapi_accept request will be processed first. It is then possible to hijack the control of sending the ivrapi_reaccept request, which makes sense if the websocket connection is broken.

You can give up control by sending an ivrapi_abort request. In this case the script will continue execution of the next component. Also, control should be terminated when the event 'ivrevents.api_stop' is received. In this case, no requests need to be sent in connection with the managed session.

The key field in queries must contain a value that matches a similar value from the event ivrevents.api_start.

Example of an event '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": "External management 3",
      "ivrid": "rDlg-006-ZevQbP",
      "ivrts": 1602002800707,
      "key": "abc",
      "params": "{\"asdf\":\"zxcv\"}",
      "sm_id": "f9098ae9-0642-00af-0ad1-880000000006"
    }
  }
]

Management acceptance (ivrapi_accept)

Example
[
  "ivrapi_accept",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll"
  }
]

Override (ivrapi_reaccept)

Example
[
  "ivrapi_reaccept",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll"
  }
]

Return of control (ivrapi_abort)

Example
[
  "ivrapi_abort",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll"
  }
]

Initiation of components

During the accepted control, the external module can execute any standard script components with a request ivrapi_component_apply. A component initiated in this way can be interrupted by a request ivrapi_component_terminate.

Initiating the execution of a standard component (ivrapi_component_apply)

To initiate the component, place an object with the component’s settings in the data field as described in the component documentation].

  • The oType field that tells the system the type of the component (from the list of platform components) must be present Incoplax).

  • Other properties that customize the component.

  • The name, oId fields are defaulted and can be omitted, although oId will be reported in events.

  • It is not necessary to fill in the transfer* properties and those that return values - they are decorated automatically.

  • Optional fields are also fields that have default values and are not used in the selected modes of operation of the component.

  • When the component is terminated, the ivrapi_component_stopped event (below) is sent, informing which branch of the transition the component exited on, as well as a list of all return values, normally stored in variables.

  • Component types and their properties - in the platform documentation Incoplax.

  • You can use the following approach - create a script through the admin, customize the component, save the script, open its contents, find the component in json and take its contents as a data.

You should not attempt to initiate new components until you receive a component termination event - the system will filter out these requests and respond to them with an error.

Example of simple playback initiation
[
  "ivrapi_component_apply",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll",
    "data": {
      "oType": 204,
      "mode": 0,
      "file": ":GS_PUB/x/y/14.mp3"
    }
  }
]
Example of record initiation
[
  "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
    }
  }
]
Example of a response upon completion of a record component
[
  "ivrapi_component_apply_result",
  {
    "qid": 0.1234,
    ...
  }
]
Examples of other components
// Example of call transfer
"data": {"oType":203, "number": "13", "reinviteMode":2}

// Ending a call
"data": {"oType":201}

// Playing a file previously downloaded to a temporary folder
"data": {"oType":204, "mode":0, "file":":TEMP/14.mp3"}

Interrupting the execution of a previously initiated component (ivrapi_component_terminate)

A previously initiated component can be correctly terminated at any time. You should proceed to the initiation of the next component after waiting for a response to the sent request.

Example
[
  "ivrapi_component_terminate",
  {
    "qid": 0.1234,
    "key": "abc",
    "ivrid": "rDlg-006-Sm41ll"
  }
]

File handling

Getting a temporary link to download a file (ivrapi_file_get_path)

The script periodically generates files (e.g. as a result of recording or receiving a fax). The internal path to the file thus generated is returned as a result of the termination of the initiated component. This value is contained in the field corresponding to the variable receiving the output value.

Such a file can be downloaded by an external system via a public link in the REST-API while the script is active. To do so, you must obtain this public link using this request. The link will be available for 5 minutes. Even if the script has finished by that time.

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

Pouring a file into a temporary script folder (ivrapi_file_upload_temp)

If you need to play a dynamic file, or send a fax, mail, etc., you may need to upload the file to the server and make it available to the script for later use by components. To do this, you need to execute this request. The server will independently download the file from the specified URL, place it in the temporary script directory and return the correct path for use in script components. The file will be automatically deleted when the script is finished.

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

Uploading a file to static storage (ivrapi_file_upload_static)

In some cases, it may be necessary to play the same file in a large number of simultaneously running scenarios or on a medium-term basis. Pouring it into every session may not be acceptable due to the naturally occurring pause as well as the load on the network. In this case, the file can be uploaded to a static folder ahead of time and then applied in any scenarios. The upload is done to the specified filestore as paths are specified when configuring scripts (field destpath). It is necessary to execute this request. The server will download the file from the specified URL and place it on the specified path. During the subsequent initiation of components, the same value that is in the destpath.

Request example
[
  "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/"
  }
]
Response example
[
  "ivrapi_file_upload_static_result",
  {
    "qid": 0.1234,
    "result": ":GS_PUB/a/b/c/abc.wav"
  }
]

The main names of the paths to be placed:

  • :SYNC_COMMON or :SYN_MEDIA

  • :SYNC_DOMAIN_DATA or :SYN_DOM

  • :SYNC_DOMAIN_COMMON or :SYN_DOM_MEDIA

  • :SITESHARE_PUBLIC or :SS_PUB

  • :SITESHARE_DOMAIN_DATA or :SS_DOM

  • :GLOBALSHARE_PUBLIC or :GS_PUB

  • :GLOBALSHARE_DOMAIN_DATA or :GS_DOM

The standard value is considered to be :SYNC_DOMAIN_DATA.

Filling can also be done without reference to the session with the taken control. For this purpose the method `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" } ] ---

Events

Terminating the component (ivrapi_component_stopped)

Example
[
  "ivrapi_component_stopped",
  {
    "oId": 0,
    "transferKey": "transfer",
    "results": {
      "dtmfBuffer": "78"
    }
  }
]

Received DTMF (ivrapi_dtmf)

The event duplicates the callevents.dtmf message, but comes earlier and only within the captured control via the API.

Example of receiving DTMF outside the initiated component:
[
  "ivrapi_dtmf",
  {
    "key": "abc",
    "ivrid": "rDlg-006-WbVFRX",
    "mode": "idle",
    "dtmf":"5"
  }
]
Example of DTMF acquisition within an initiated component:
[
  "ivrapi_dtmf",
  {
    "key": "abc",
    "ivrid": "rDlg-006-WbVFRX",
    "mode": "component",
    "oId": 0,
    "dtmf": "5"
  }
]

References

  • Personalization
  • Increase font size
  • Decrease font size