AdminGuide:Service:DynamicRouting/en

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>

 <?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>

 <?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/pippo</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).

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