HOWTO: Route Dial Patterns and Trunk Dial Rules
Hints on Route Dial Patterns and Trunk Dial Rules
New users of FreePBX are often confused by the fact that there is a place to enter "Dial Rules" when creating a new Trunk, and "Dial Patterns" when creating a new Outbound Route. Since the construction of these seems similar, users try to do something in the wrong place and it doesn't work. This is a brief attempt to explain the difference.
Trunk Dial Rules
First let's deal with trunks, because they are perhaps the easiest to understand. The thing to remember about Trunk Dial Rules is that they are ONLY used for adding numbers to, or subtracting numbers from the number being sent to the trunk. Trunk Dial Rules are NEVER used to allow or restrict numbers that may be dialed. Therefore, it follows that (with one exception noted below) any entry not containing a | character (to strip off number at the start of the entry) or a + character (to add numbers at the start of an entry) is totally useless - it will simply waste processor time while the system looks at those entries.
To give an example, here's a common newbie mistake. Let's say that you have a couple different trunks that allow outgoing toll-free numbers in the USA, and one of them is Free World Dialup, which requires a star (*) key in front of the actual number. For the moment, let's assume that you want to restrict these trunks to toll-free numbers only. So in the first trunk, you might be tempted to put some lines like this:
1800NXXXXXX 1822NXXXXXX 1833NXXXXXX 1844NXXXXXX 1855NXXXXXX 1866NXXXXXX 1877NXXXXXX 1888NXXXXXX
And then in the Free World Dialup trunk, you congratulate yourself as you cleverly add the * to each toll-free definition:
*+1800NXXXXXX *+1822NXXXXXX *+1833NXXXXXX *+1844NXXXXXX *+1855NXXXXXX *+1866NXXXXXX *+1877NXXXXXX *+1888NXXXXXX
Congratulations, you've managed to waste a bunch of processor time! In the first example, NONE of the entires are accomplishing a thing because none of them contain a | or + character. You could (and should) remove every one of them. Call filtering by number dialed is done by ROUTES, not by TRUNKS.
Note: There is, however, one exception to the general "definitions without a | or + are useless in a trunk" rule. A definition without a + or |, if matched, will stop the processing of definitions beyond that point. Consider the following example:
This will add 1321 to any 7 digit number, EXCEPT those starting with 555. So, a definition can also be used as a "stopper" to prevent that pattern from being matched by another definition that is lower in the list (thanks to groogs in the #freepbx IRC channel for this clarification).
And in the second example (the Free World Dialup trunk), you could accomplish the same thing by ONE line, like this:
or, because you know that "real" Free World Dialup numbers are five or six digits long, you could even use
(Note the period as the last character) - Which would prepend the * to any number 7 digits long or longer (although you may not want to do this if you use Free World Dialup as a route to other networks, but that's a more advanced discussion).
Again, this bears emphasizing: You CANNOT use Trunk Dial Rules to allow or restrict certain numbers from going out on a trunk. You can only add or strip digits.
Route Dial Patterns
Route Dial Patterns are used to specify what numbers are allowed to go out via that route. When a call is placed, the actual number dialed by the user is compared with the Dial Patterns in each route (from highest to lowest priority) until a match is found. If no match is found in any route, the call fails (there is "no route" for that call).
If the number dialed matches a pattern in more than one route, only the rules in the route with the highest priority are used. In other words, if a call tries to use that route and fails, it does not keep trying additional routes to see if it matches another. This is actually desirable behavior because it allows you to force certain calls to go out via lower cost routes.
Route Dial Patterns cannot be used to add digits to the number dialed by the user. However, you can strip off leading digits before passing them to a trunk. This is most useful if you use a specific dialing code to access a particular route (for example, "9" to access an outside line).
Note that each route can be set to access one or more trunks. Each trunk may require different translations (changing what was actually dialed to something else before sending it on is called a translation in telephone-speak) so you don't want to strip digits at the route level if only some of your trunks will require it and some don't.
Route Dial Patterns only allow calls, they cannot block calls. The only way to block certain patterns is to make sure they are not included in any route. Or, you can include the blocked pattern in a higher priority route, then make sure that route doesn't send calls to any trunks that cost money. The easiest way to do this is to create an ENUM trunk.
For example, let's say you want to allow all calls within Country Code 1 EXCEPT calls to 1-900 numbers and to local 976 numbers (in a real situation you'd probably have additional restrictions, but this is just to illustrate the technique). In a lower-numbered route (which has a higher priority) you could include these lines in the Route Dial Pattern:
Then make sure that the only trunk that route accesses is the ENUM trunk (create one if you don't have one). Because ENUM is always free, chances are the call will never complete, but if it does it will not cost anything. Now make a higher numbered route (lower priority) and either include a general pattern such as:
Or if you want additional security, you could instead use a list of specific area codes that you wish to allow (omitting those that do not exist or that you don't want to allow calls to be placed to):
1202NXXXXXX 1203NXXXXXX etc.
Yes, it may be a fairly long list, but it will work. You may still want to use ENUM as your first trunk choice (if you want to check for a "free" route to the called number, before going to your usual provider), but then you will be sure to include a trunk that permits outgoing calls to these numbers.
How do I....?
How do I allow seven digit dialing for local calls in North America?
In the route that handles calls to your local area code, include this in your Route Dial Patterns:
In the trunk(s) accessed by that route, include this in the Trunk Dial Rules:
Replace aaa with your local Area Code.
How do I block certain International destinations while allowing others?
Again, make sure you've set up an ENUM trunk which can be used as a destination for calls you don't want to pay for. Then think about your dial patterns and how you want to allow or block them. Remember that less specific rules must always be placed in a lower priority than more specific rules. For example, let's say we want to allow calls to landlines in country code 64, but not to mobiles or high-cost numbers. In a higher priority (lower-numbered) route, include the patterns you want to block, e.g.:
011642. 011648. 01164900.
Associate this route with the ENUM trunk only. Then in a lower priority (higher-numbered) route, place the more general pattern:
Then associate this route with the ENUM trunk (if you want to check for a "free" route first), followed by the trunk(s) of the provider(s) you wish to use for calls to country code 64. Don't forget to strip the "011" international prefix in the ENUM trunk Dial Rules.