'ivrapi' capability for WebSocket Token API
- Overview
- Requests
- Taking control
- Initiating components
- Initiating a standard component (
ivrapi_component_apply) - Interrupting a previously initiated component (
ivrapi_component_terminate) - Calling an executing component method (
ivrapi_component_fun) - Adding a subscriber to a two-step transfer (
ivrapi_dialer_add) - Removing a subscriber from a two-step transfer (
ivrapi_dialer_remove) - Working with files
- Getting a temporary file download link (
ivrapi_file_get_path) - Uploading a file to the script temporary folder (
ivrapi_file_upload_temp) - Uploading a file to static storage (
ivrapi_file_upload_static)
- Events
- Links
Overview
Provides an interface for taking control of an IVR script and initiating call processing by various components.
Requests
Taking control
To take control in an external module, the External control via API component must be placed in the IVR script.
When its servicing starts in a specific session, the 'ivrevents.api_start' event is sent to subscribers, bound to that session and specific component.
Accordingly, the application must be subscribed to events of the ivrevents class.
After receiving the event, any of the applications can take control by sending an ivrapi_accept request via the current module API. Only one connection can capture control - the one whose ivrapi_accept request is processed first.
Subsequently, control can be intercepted by sending an ivrapi_reaccept request, which makes sense if the WebSocket connection breaks.
Control can be abandoned by sending an ivrapi_abort request. In this case the script continues with the next component.
Control should also be terminated upon receiving the 'ivrevents.api_stop' event. In this case no requests related to the controlled session need to be sent.
The key field in requests must contain a value matching the same value from the ivrevents.api_start event.
[
"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 control 3",
"ivrid": "rDlg-006-ZevQbP",
"ivrts": 1602002800707,
"key": "abc",
"params": "{\"asdf\":\"zxcv\"}",
"sm_id": "f9098ae9-0642-00af-0ad1-880000000006"
}
}
]
Accepting control (ivrapi_accept)
[
"ivrapi_accept",
{
"qid": 0.1234,
"key": "abc",
"ivrid": "rDlg-006-Sm41ll"
}
]
Initiating components
During accepted control, the external module can execute any standard script components with the ivrapi_component_apply request.
A component initiated this way can be interrupted with the ivrapi_component_terminate request.
Initiating a standard component (ivrapi_component_apply)
To initiate a component, place in the data field an object with component settings as described in the components documentation.
-
The
oTypefield must be present, telling the system the component type (from the Incoplax platform component list). -
Other properties configuring the component.
-
The
nameandoIdfields are defaulted and may be omitted, althoughoIdwill be reported in events. -
It is optional to fill
transfer*properties and those returning values - they are decorated automatically. -
Fields having default values and those not used in the selected component operation modes are also optional.
-
When the component completes, the
ivrapi_component_stoppedevent (below) is sent, reporting the transition branch the component exited through and the list of all returned values normally saved to variables. -
Component types and their properties are in the Incoplax platform documentation.
-
The following approach can be used - create a script through the admin panel, configure the component, save the script, open its content, find the component in the JSON, and take its content as
data.
Until the component completion event is received, do not try to initiate new components - the system filters such requests and responds with an error.
[
"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,
...
}
]
// Call transfer example
"data": {"oType":203, "number": "13", "reinviteMode":2}
// Call termination
"data": {"oType":201}
// Playback of a file previously uploaded to the temporary folder
"data": {"oType":204, "mode":0, "file":":TEMP/14.mp3"}
Interrupting a previously initiated component (ivrapi_component_terminate)
A previously initiated component can be correctly interrupted at any time. Proceed to initiating the next component after waiting for the response to the sent request.
[
"ivrapi_component_terminate",
{
"qid": 0.1234,
"key": "abc",
"ivrid": "rDlg-006-Sm41ll"
}
]
Calling an executing component method (ivrapi_component_fun)
A specific request can be sent to a previously initiated component. An example of such a request is adding subscribers to an initiated two-step transfer, although this particular example is implemented by separate methods.
[
"ivrapi_component_fun",
{
"qid": 0.1234,
"key": "abc",
"ivrid": "rDlg-006-Sm41ll",
"method": "some_method",
"data": {"param1": 1, "param2": "value2", "something_else": true}
}
]
Adding a subscriber to a two-step transfer (ivrapi_dialer_add)
The previously initiated "Attended transfer" component allows adding and removing forks.
The unique fork identifier is the number (the "to" parameter). The same number cannot be added several times, but if the call of the previous fork has already ended, it can be repeated.
For each such newly added fork, its own timeout can be set (the "timeout" parameter in seconds). The overall timeout set for the component determines the maximum transfer wait time.
The first (or several first) forks are started immediately with the component to the number (or comma-separated numbers). The component does not allow setting a special response wait timeout for each of them, but each can be stopped with the 'ivrapi_dialer_remove' command.
The transfer component completes on success, and also if the overall timeout fires or the last fork is removed (including by the ivrapi_dialer_remove command or by the timeout set for the fork).
[
"ivrapi_dialer_add",
{
"qid": 0.1234,
"key": "abc",
"ivrid": "rDlg-006-Sm41ll",
"to": "304",
"timeout": 10
}
]
Removing a subscriber from a two-step transfer (ivrapi_dialer_remove)
The previously initiated "Attended transfer" component allows adding and removing forks.
Any active fork (the consultation call of the first step of a two-step transfer) can be removed until it sends a final 2xx response. The unique fork identifier is the number (the "to" parameter).
The transfer component completes on success, and also if the overall timeout fires or the last fork is removed (including by the ivrapi_dialer_remove command or by the timeout set for the fork).
[
"ivrapi_dialer_remove",
{
"qid": 0.1234,
"key": "abc",
"ivrid": "rDlg-006-Sm41ll",
"to": "304"
}
]
Getting a temporary file download link (ivrapi_file_get_path)
The script periodically generates files (for example as a result of recording or fax reception). The internal path to a file generated this way is returned as a result of the initiated component completion. 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 this, obtain this public link using this request. The link is available for 5 minutes, even if the script finishes by then.
[
"ivrapi_file_get_path",
{
"qid": 0.1234,
"key": "abc",
"ivrid": "rDlg-006-Sm41ll",
"path": ":TEMP/ivr_records/ivr_000006_1602234901218.wav"
}
]
Uploading a file to the script temporary folder (ivrapi_file_upload_temp)
When a dynamic file needs to be played, or a fax, email, etc. sent, the file may need to be uploaded to the server and made available to the script for subsequent use by components. To do this, execute this request. The server independently downloads the file from the specified URL, places it in the script temporary directory, and returns a correct path for use in script components. The file is automatically deleted after the script finishes.
[
"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 the same file may need to be played by many simultaneously running scripts or over the medium term.
Uploading it into each session may be unacceptable due to the naturally occurring pause and network load.
In this case the file can be uploaded to a static folder in advance and then used in any scripts.
The upload is performed to the specified file storage in the form in which paths are specified when configuring scripts (the destpath field).
Execute this request. The server independently downloads the file from the specified URL and places it at the specified path.
When subsequently initiating components, the same value as in the destpath field should be specified as file paths.
[
"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"
}
]
Main path names for placement:
-
:SYNC_COMMONor:SYN_MEDIA -
:SYNC_DOMAIN_DATAor:SYN_DOM -
:SYNC_DOMAIN_COMMONor:SYN_DOM_MEDIA -
:SITESHARE_PUBLICor:SS_PUB -
:SITESHARE_DOMAIN_DATAor:SS_DOM -
:GLOBALSHARE_PUBLICor:GS_PUB -
:GLOBALSHARE_DOMAIN_DATAor:GS_DOM
The standard value is :SYNC_DOMAIN_DATA.
Upload can also be performed without reference to a session with taken control. The file_upload_static method serves this purpose.
[ "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
Component completion (ivrapi_component_stopped)
[
"ivrapi_component_stopped",
{
"oId": 0,
"transferKey": "transfer",
"results": {
"dtmfBuffer": "78"
}
}
]
DTMF received (ivrapi_dtmf)
The event duplicates the callevents.dtmf message but arrives earlier and only within control captured via the API.
[
"ivrapi_dtmf",
{
"key": "abc",
"ivrid": "rDlg-006-WbVFRX",
"mode": "idle",
"dtmf":"5"
}
]
[
"ivrapi_dtmf",
{
"key": "abc",
"ivrid": "rDlg-006-WbVFRX",
"mode": "component",
"oId": 0,
"dtmf": "5"
}
]