AdminGuide:Service:DynamicRouting

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 by passing a series of numeric parameters to ask the caller through prerecorded voice prompts.

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 to ask the caller 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 replay 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 NONE (no authentication) or BASIC (Basic HTTP Authentication). For Basic Authentication, it is necessary to specify the authentication credentials (username and password).

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/misc/pluto</elem>
<elem>number:201</elem>
<elem>digit:123</elem>
<elem>audio:custom/misc/goofy</elem>
</message>
<value>105</value>
</response>

The <value> tag 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

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 allowed values of the <elem> are:

- digit: repeat the single digits, one after the other (it is possible to specify numbers with more than one digit, which will be read one by one); - number: repeat the whole number; - alpha: accept digits and alphabet letters, which will be repeated one at a time; - audio: specify the path to an audio file (present on the PBX) to be played.

• 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.

Nei casi negativi in cui i parametri non siano corretti, o la chiamata provenga da un numero non specificato nel file o non sia specificato il valore delle response, verrà sempre eseguita l’azione di gestione errori.

E’ inoltre possibile inserendo dei valori nei campi newCallerNameFull, newCallerNamePrefix, newCallerNum modificare il nome e numero chiamante che verranno mostrati sul display del telefono chiamato.

In particolare se inserisco il newCallerNameFull il nome del chiamante verrà sostituito con questo valore, se inserisco il newCallerNamePrefix questo valore viene anteposto al nome chiamante mentre se inserisco newCallerNum viene sostituito il numero chiamante.

• Gestione errori: Nel caso in cui la richiesta al server WEB restituisca un errore oppure il riscontro sul file non vada a buon fine la chiamata viene gestita come indicato in questa sessione.

Esempio instradamento dinamico interno

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

Dopo aver creato sul Piano di numerazione l’esatta selezione per l’instradamento dinamico, da uno degli interni si effettua la chiamata a tale numero.
Se la chiamata proviene dal numero 102, il sistema invierà la risposta 200 e verrà eseguita l’azione associata a quella response.
Se la chiamata proviene dal 103, verranno richiesti tramite un messaggio vocale, i valori dei parametri; se i parametri inseriti sono corretti il sistema invierà la risposta 100 e verrà eseguita l’azione associata a quella response.
Se la chiamata proviene da altro interno non specificato nel file, verranno richiesti i valori dei parametri e se i parametri inseriti sono corretti il sistema invierà la risposta 100 e verrà eseguita l’azione associata a quella response.
In tutti gli altri casi viene seguita l’azione definita nella gestione errori.