Dynamic Routes User Guide
- 1 Overview
- 2 Dynamic Routes Main Page
- 3 Creating a Dynamic Route
- 3.1 Dynamic Routes General Options
- 3.1.1 Dynamic Route Name
- 3.1.2 Dynamic Route Description
- 3.2 Dynamic Route DTMF Options
- 3.2.1 Enable DTMF Input
- 3.2.2 Announcement
- 3.2.3 Max digits
- 3.2.4 Timeout
- 3.2.5 Validation
- 3.2.6 Invalid Retries
- 3.2.7 Invalid Retry Recording
- 3.2.8 Invalid Recording
- 3.2.9 Invalid Destination
- 3.3 Dynamic Route Saved Variables
- 3.4 Dynamic Route Lookup Source
- 3.4.1 Source Type
- 3.4.2 Enable substitutions
- 3.5 Dynamic Route Default Entry
- 3.6 Dynamic Route Entries
- 3.1 Dynamic Routes General Options
- 4 Dynamic Route Lookup Source Types
- 5 Dynamic Route Variable Substitutions
- 6 Edit/Delete a Dynamic Route
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
Dynamic Routes General Options
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.
IMPORTANT - when defining lookup queries or destinations that contain square brackets and it is not the intent to reference a Dynamic Route Variable then you must set Enable Substitutions to No.
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 trailing semicolon is not required in the query. Since the SQL query is written directly to Asterisk dialplan, any semicolon character(s) must be escaped with \
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 trailing semicolon is not required in the query. Since the SQL query is written directly to Asterisk dialplan, any semicolon character(s) must be escaped with \
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¶m2=[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.