AdminGuide:Service:DynamicRouting
Return to AdminGuide:Service
This service enables inbound call routing based on the response of an HTTP API invoked on an external web server or upon matching one or more parameters specified in a file uploaded to the PBX.
This is done through a series of prerecorded voice prompts asking the caller to input numeric parameters.
Configuration
The service can be configures in the PBX applications -> Dynamic routing page.
During configuration, the following parameters must be specified:
- Name: routing identifier.
- Type: HTTP request (request to an external web server) / Extension (local file).
- Checktime: the time check that must be verified before routing. For dynamic routing, the failover action must be "Return to previous level".
- Parameters: each numeric parameter can be linked to a voice prompt (such as an input request) and, optionally, it is possible to specify the maximum number of digits.
If this value is not specified, the system will assume that the user had finished dialing the parameter after 5 seconds or upon pressing #. If the user fails to input a digit, the prompt will play again, for a maximum of 3 times. The maximum number of parameters is 5.
It is also possible to enable confirmation requests through a checkbox; if enabled, the system will repeat the inputted digits to the caller and ask them to confirm by pressing "1". If confirmation is not given, the system will repeat the request to insert the parameter.
Request settings
HTTP request
The following settings need to be specified for HTTP requests:
- URL: the URL to which the request must be made (HTTP and HTTPS are both supported).
- Auth type: the type of authentication used by the web server. Can be one of three values:
- NONE: no authentication.
- BASIC: Basic HTTP Authentication; in his case, you will need to specify the authentication credentials (username and password).
- Client certificate integrated in the PBX (available with firware version 4.5.9 or later): request authentication is performed by comparing the identity of the requester through a unique client certificate. This certificate is integrated in each KalliopePBX, signed by CA Kalliope, and its CN is the serial number of the PBX (e.g. CN=KPBX40412345).
- Request Type: the request method (GET and PST are supported). If POST is used, you can specify the format of the body of the request and the corresponding Content-Type.
The passage from parameters to API is executed through placeholders inserted in the URL or contained in the POST. The recognized placeholders are:
- %CALLER_NUM%: the number of the caller;
- %DNID%: the called number;
- %PARAM1%, …, %PARAM5%: the 5 parameters that the caller is asked to insert through the interactive audio menu;
- %UNIQUE_ID%: the unique ID of the call under which the call can be found in the CDR.
For example, with a GET request, the URL might be:
http://www.myserver.com/api?arg1=%CALLER_NUM%&arg2=%PARAM1%&arg3=%PARAM2%
For a POST request, the body might be:
<?xml version="1.0"?>
<parameters>
<caller>%CALLER_NUM%</caller>
<param_01>%PARAM1</param_01>
<param_02>%PARAM2</param_02>
</parameters>
Internal
With an internal request, the file must be uploaded to the TFTP Access folder through the File Manager.
The supported file types are .xls/.xlsx/.ods/.csv and the file may or may not contain columns headers. If it does not, column mapping must be specified, specifying for each field the exact location in the file. It is important that the columns are numbered starting from 0.
The source file must follow this template:
| callerNum | calledNum | param1 | param2 | param3 | param4 | param5 | response | newCallerNameFull | newCallerNamePrefix | newCallerNum|}Actions
This section contains the configuration of the routing rules to execute based on the response from the web server or file matching.
HTTP request
With an HTTP request, the system expects a "200 OK" type response from the web sever, the body of which must contain an XML text as follows:
<?xml version="1.0"?>
<response>
<message>
<elem>digit:1</elem>
<elem>number:200</elem>
<elem>alpha:c234</elem>
<elem>audio:custom/%TENANT_UUID%/sounds/misc/pluto</elem>
<elem>number:201</elem>
<elem>digit:123</elem>
<elem>audio:custom/misc/goofy</elem>
</message>
<displayprefix>text</displayprefix>
<value>105</value>
</response>
N.B.: the string %TENANT_UUID% must be replaced with the actual value of the UUID specified in the "information" widget on the dashboard.
The <message> and <displayprefix> tags (available with firmware version 4.3.5 or later) are optional; <message> specifies the dynamic component of any audio prompt that is set to play to the caller, while <displayprefix> lets you change the Display Name of the call by adding in front of it the prefix specified in the tag itself.
The <value> tag is required and indicates the API response based on which the actions to be executed are defined.
Actions can be defined as follows:
- Play a static audio file uploaded to the system;
- Play dynamic content;
- Forward the call to a new destination or hang up.
The dynamic content may be comprised of a series of concatenated messages based on the sequence of <elem> tags present in the <message> response. The following table lists the possible <elem> formats and the corresponding additions to the dynamic content:
| <elem>...</elem> | Example | Firmware | Descrizione | Example output |
|---|---|---|---|---|
| digit:{digit_sequence} | digit:1234 | - | Plays the individual digits (numerical, from 0 to 9) of {digit_sequence} | Plays the audio message "one two three four" |
| number:{number} | number:1234 | - | Plays {number} | Plays the audio message "One thousand two hundred thirty four" |
| alpha:{alphanumeric_sequence} | alpha:1a2b3c4d | - | Plays the individual alphanumeric characters of the string {alphanumeric_sequence} | Plays the audio message "One a two b three c four d" |
| audio:{audio_file} | audio:custom/misc/test | - | Plays the audio file present on KalliopePBX identified by the name {audio_file} (including the path, as displayed in the "Sounds" -> "Audio files" page) | Plays the audio message custom/misc/test |
| dtmf:{dtmf_sequence},{intertone_pause},{duration} | dtmf:123w*,200,350 | 4.5.12+ | Plays DTMF tones (according to the mode specified for the channel from which the call originates) specified in {dtmf_sequence}; each tone lasts {duration} milliseconds (expressed as an integer) and separated by a pause of {intertone_pause} milliseconds. The allowed characters are the valid DTMF digits (0-9,*#,a-d,A-D) plus "w" and "W" to indicate a pause of 500 or 1000 milliseconds. N.B.: the inter-digit pause is inserted even for the "w" and "W" characters. |
Plays the following DTMF tones, each for 350 milliseconds: "1", 200 ms pause, "2", 200 ms pause, "3", 200 + 500 + 200 ms pause, "*" |
| pause:{duration} | pause:450 | 4.5.12+ | Inserts a pause of {duration} milliseconds | Inserts a 450 milliseconds pause |
Routing rule
The forwarding action to be executed. In addition to normal actions, it is also possible to forward the call to the numbering plan, using the value contained in the response as the selection.
Internal
With internal requests, the system will verify the calling number, called number, and parameters on the file and return the value that will be used to choose which actions to execute from the corresponding response column.
If there is more than one row that matches the data, the action will be the one corresponding to the row with the most matches (best match).
In this case, dynamic content is not available and the available actions are therefore comprised of the following:
- Play a static audio file uploaded to the system
- Routing rule
At this point the forward action is defined. In addition to normal actions, it is also possible to forward the call to the numbering plan, using the value contained in the response as the selection.
If the parameters are incorrect, the call comes from a number not specified in the file, or no response value is specified, then the error management action will be executed.
It is also possible to change the name and number shown on the display of the called phone by inserting values in the newCallerNameFull, newCallerNamePrefix, newCallerNum fields.
Specifically, newCallerNameFull will replace the name of the caller, newCallerNamePrefix will be added before the calling number, and newCallerNum will replace the calling number.
- Error management: if the request to the web server returns an error or the file matching is unsuccessful, the call will be handled as specified in this section.
Example of dynamic routing
| callerNum | calledNum | param1 | param2 | param3 | param4 | param5 | response | newCallerNameFull | newCallerNamePrefix | newCallerNum |
|---|---|---|---|---|---|---|---|---|---|---|
| 102 | - | - | - | - | - | - | - | - | simona | 111 |
| 103 | - | 111 | 22 | - | - | - | 100 | - | - | - |
| - | - | 123 | 123 | 333 | 123 | 123 | 100 | - | - | 321 |
After the exact selection for dynamic routing has been created in the numbering plan, an extension calls this number.
If the call comes from 102, the system will send response 200 and execute the associated action.
If the call comes from 103, an audio message will ask for the parameters; if the inputted values are correct the system will send response 100 and execute the associated action.
If the call comes from an unspecified extension, an audio message will ask for the parameters; if the inputted values are correct the system will send response 100 and execute the associated action.
In all other cases, the error management action will be executed.