Overview

The Dynamic Routes module can be used to prompt a caller for input and direct call flow to one of many destinations based on a live lookup using various supported lookup methods

Dynamic Routes Main Page

From the Applications Menu, choose Dynamic Routes. This is the main Dynamic Routes page where you can see all configured routes for the system listed alphabetically by name.

Creating a Dynamic Route

Click the 'Add Route' button

Open

Dynamic Routes General Options

Open

Dynamic Route Name

The name of the dynamic route. This can be chosen at will. It is used to identify the route when selecting it as a destination from other applications or inbound routes.

Dynamic Route Description

Optional description text for the Dynamic Route. This is for documentation purposes only.

Dynamic Route DTMF Options

If you want the caller to enter DTMF digits, it is configured in this section.

Enable DTMF Input

Setting: Yes or No. Default: No. If set to yes the call waits for input from the caller on the touch tone keypad.

Announcement

The System Recording to be played to the caller. If Enable DTMF input is set to 'Yes' then playback takes place before waiting for DTMF input.

Max digits

The maximum number of digits accepted for input. Once the max digits is reached, call processing continues regardless of timeout.

Timeout

Timeout in seconds to wait for DTMF input. This value is only used if Enable DTMF Input is set to Yes. If no value is given for timeout, the default for the channel is used. It is recommended that an explicit value be set.

Validation

Validation rule using an Asterisk regular expression (see Asterisk REGEX). For example to ensure the caller DTMF input is between 3 and 4 digits long you could use ^[0-9]\{3,4\}$ Note that the curly braces and other Asterisk special character need to be escaped.

Invalid Retries

Number of times the caller gets to enter DTMF input before the call goes to the Invalid Destination.

Invalid Retry Recording

System recording to play to the caller when they enter invalid input.

Invalid Recording

System recording to play to the caller when then enter invalid input and get directed to the Invalid Destination.

Invalid Destination

Destination to send the caller once they've exhausted all their invalid input retries.

Dynamic Route Saved Variables

In order to reference the DTMF input or the result of the lookup later in the call flow, you must specify a variable name. These variables are available only as long as the channel is up. 

Saved input variable name

Name of variable in which to save DTMF input for future use in the dial plan or further dynamic routes. This variable is referenced either as [name] in Dynamic Routes query/lookup where name is the name of the variable you specify here. To reference the variable in Asterisk dialplan (e.g. custom applications) it is necessary to prefix it with "DYNROUTE_" i.e.  ${DYNROUTE_name}

Saved result variable name

Variable name in which to save lookup result for use in the dial plan or further dynamic routes. This is referenced either as [name] in Dynamic Routes query/lookup where name is the name of the variable you specify here in square brackets. To use the variable in Asterisk dialplan (e.g. custom applications) it is necessary to prefix it with "DYNROUTE_" i.e. ${DYNROUTE_name}

Dynamic Route Lookup Source

Optional setting to allow for a lookup to be done in order to obtain a returned result. The returned result will be assigned to the "Saved result variable name" (if specified) and can be used to direct the call to any matching Dynamic Route Entry specified below.

Source Type

Select the type of lookup to perform. See Dynamic Route Lookup Source Types below for full details.

Enable substitutions

If enabled, any expression containing square brackets will be substituted with Dynamic Route variables. See Dynamic Route Variable Substitutions below for full details.

Dynamic Route Default Entry

When the Lookup result does not return a match to any of the Dynamic Route entries below then the caller will be sent to the default destination specified here. This is optional but is strongly recommended. If there is no default destination defined, then in the case of a lookup failure or if the lookup result does not match one of the defined values, the call will be dropped. If the desired result is that the call be dropped by default, route the caller to the "Terminate Call" destination.

Dynamic Route Entries

Optional. If a lookup is done and a lookup result has been obtained, the caller will be sent to the corresponding destination that has an exact match to the lookup result. If there are no entries here, the caller will always be sent to the default destination. Additional rows may be added by clicking the + symbol and rows are deleted by clicking the trash icon. 

Dynamic Route Lookup Source Types

None

No lookup is carried out. The call is sent to the default destination

MySQL

A lookup is done to a MySQL database. The parameters used are:

• MySQL hostname: hostname of server

• MySQL database: database name

• MySQL username: username

• MySQL password: password

• MySQL query: the SQL to be used. It can contain substitutions as indicated in the table below. Example: select destination from callerid_table where calleridnum like '%[NUMBER]'

The MySQL lookup features rely on the Asterisk module app_mysql which is deprecated and scheduled to be removed in Asterisk 19 It's preferred to use ODBC

ODBC

A lookup is done to an Asterisk ODBC data source. The parameters used are:

• ODBC function: the Asterisk ODBC function name that has been configured

• ODBC query: the query. It can contain substitutions as indicated in the table below. Example: select destination from callerid_table where calleridnum like '%[NUMBER]'

For information about setting up ODBC see the article at the Dynroutes home page.

URL

A lookup is done to a URL. The returned result must be text only. HTML, XML and JSON is not supported. The URL may contain parameters and the parameter values may include the substitutions indicated in the following table.
Example: http://localhost/test.php?param1=4&param2=[NUMBER]

AGI

A lookup is done by launching an Asterisk AGI script. The parameters used are:

• AGI Lookup: the pate and file name of the Asterisk AGI script to be launched.

• AGI Result Variable: the name of the variable that the script uses to transfer the the result to Dynamic Routes. The script should execute a SET VARIABLE command using this variable name at the end of execution in order to pass back the lookup result. 

Asterisk variable

The lookup value is read from an Asterisk Variable. The parameters used are:

• Asterisk Variable: the variable name from which to read the result

Example: ${xxx}. Complex expressions may also be used provided they use valid Asterisk functions, for example: ${REGEX("^1.3$" ${DYNROUTE_dtmf})} would check that the DTMF input was in the range 1000-1999 (providing that the Saved input variable name was set to "dtmf"). You can use Asterisk Conditionals that return 0 or 1 such as $["${DIRECTION}" = "INBOUND"] and you can write values to Asterisk channel variables and functions using the function SET, e.g. ${SET(GROUP()=inbound)}

Dynamic Route Variable Substitutions

The following variables can be used in square brackets in Dynamic Routes:

[INPUT] - The DTMF input by the caller on the touchtone keypad
[NUMBER] - The Caller ID Number of the incoming call
[DID] - The called number or DID
[name] - Where "name" is the value of one of these two fields: Saved input variable name or Saved result variable name. In the case of Saved input variable name, the DTMF input is saved under this name. This is useful if you are using two or more Dynamic Routes in sequence so that you can save the DTMF from the previous Dynamic Route in a uniquely named variable and use that variable in the lookup of the second Dynamic Route. In the case of Saved result variable name, the result returned from the lookup is saved to the variable name and can be used in a later Dynamic Route.

If you want to use a variable created outside Dynamic Routes in the lookup, then name the variable with a DYNROUTE_ prefix. Then [name] will be substituted by the value of the asterisk variable DYNROUTE_name. There is currently no way of reading an arbitrarily named asterisk variable, except for the lookup type "Asterisk variable".

Edit/Delete a Dynamic Route

At the main Dynamic Routes page, you can use the trash and pen icons at the right to either edit or delete the corresponding Dynamic Route.