Dial Plans

Dial plans are used to route calls to trunks. Dial plans are only used for outbound calls; they are not needed for inbound calls. By default, there is no need to handle calling of accounts in a dial plan.

The structure of a dial plan is a sorted list. Each entry presents a candidate to route a call to a trunk or some other resource. Basically, it first compares a pattern with the dialed number according to matching rules. If it matches, it replaces the dialed number according to the replacement rules (if replacement field is not empty) and sends the call to the trunk set for that rule (pattern). If it doesn’t match, it moves on to the next rule.

The rules are defined in separate lines and each contains at least:

• A trunk to which the call is sent if the pattern matches.
• A pattern which the dialed number must match for the rule to trigger.
• Optionally, a replacement field which replaces the dialed number (according to replacement rules) before sending it to the set trunk. If the replacement field is empty, then the dialed number is not touched as it is sent to the set trunk.

The dial plan is sorted by the priorities. Lower numbers will be matched first. If the numbers are the same and the dial plan entry is resumed later (e.g. because of a trunk failover), it will continue with the next higher number.

Dial plans can be global. This means that all tenants can use this dial plan. This makes sense in multi-tenant environments where all tenants can share the same dial plan and the same trunks.

The PBX can check if a number is on a do-not-call list. This uses the address book of the user and the shared address book. If the entry has the do-not-call flag set it will not call the number.

The numbers that are put into the dial plan are usually in the readable format. This means the number is presented in the way that a user would read it.

info

This means that in North America, domestic numbers are 10-digits (without the leading 1) and international numbers start with 011. For the rest of the world, domestic numbers start with a single 0, and international numbers start with a 00. If an area code is present, the PBX will use the local presentation if the call is within the area code. You can change this behavior in the dial plan, for example if you prefer the E164 format in the dial plan.

Dial plan list

The list of dial plans shows the name of the plans. A broken link symbol behind the name indicatd that the plan is not referenced and can be deleted. A world symbol shows that the dial plan was marked as global.

After creating a new dial plan, the new plan will appear in the list. You can now click it in order to configure it. You can also enter any other dial plan in the list, for modification, by clicking it.

Configuring a Dial Plan

Each dial plan has a name, which can have any text value but should be unique.

In addition to the name, each dial plan has the following attributes:

Global: When this flag is enabled, the dial plan an be used by other tenants on the system.

tip

When using a global dial plan, consider putting the plan into a seperate tenant that contins the dial plans and trunks that are available to all tenants on the system. Be careful choosing DID numbers, so that the routing of inbound calls does not get messed up.

Number presentation in dial plan: When the system feeds a number into the dial plan, it first brings the number into a standard format. The setting defined what format to use.

note

Bringing the number into a standard format makes it easier to use the same rule independent from how the user dialed a number, e.g. +18001234567, 18001234567 or 8001234567 would match the same entry in NANPA format.

Check if number is on do-not-call list: Address book entries can have a flag that tells the user not to call the number. When this flag is enbled, th dial plan will refuse numbers that have the flag set.

Star codes that are handled in dial plan: This setting lists the star codes that are handled by this dial plan. Star codes must start with *. If the list is empty, the dial plan will not handle star codes. Otherwise, the list contains the star codes that are handled by this dial plan, for example when the list is *54 *55 this dial plan will handle *54 and *55, all other star codes will be processsed internally by the system. If a star code ends with a *, the system will match only the beginning. For example when the entry is *54* the system will match *54, *541 and *54123. If the pattern is *, all star codes will be handled by the dial plan.

Route internal calls: When this flag is enabled, the system will check if the dialed number is an internal resource of the tenant and send the call there without processing the dial plan.

Each dial plan contains a list of rules. To create a new rule, simply enter all its fields, like the pref number, selecting the rule's trunk from the dropdown, the pattern to match, and the replacement. The browser will automatically create a new line to add more lines. To delete an entry, just remove the content of the line; after saving this line will be removed.

Dial Plan Entries

There are several fields in the dial plan:

Preference. The preference is used to tell the system how to sort the dial plan. It must be a positive, natural number.

Trunk. The trunk drop down field contains the trunk that should be used. There are some special fields that are explained below.

C. This fields stands for CMC, or client matter code. When checked, the PBX will attempt to collect the client matter code from the user before placing an outbound call. This can be useful for accounting purposes.

P. When this field is turned on, the PBX will ask the user to enter the PIN code. The pin code can be set under each extension level PIN setting. This can be useful to protect expensive dial plan entries from abuse, e.g. random people walking into office calling international destinations.

Pattern. The pattern field defines when the entry matches. This field is described below.

Replacement. When the pattern matches, the PBX may transform the user input, for example put numbers in front of the dialed number. This is also explained in more detail below.

Service Flag. Each dial plan entry may be enabled or disabled with a service flag. That makes it possible to enable certain entries based on time or based on manually set flags.

Status. In addition to the service flag, each entry may be manually enabled or disabled.

In the trunk drop down, there are additional options available:

• Not Allowed: When this entry is selected, the PBX will stop processing the dial plan and reject the call. Starting with version 68, if you enter a text in the replacement field, the system will use that text as annoucement to the user why the call was rejected (in the audio language of the tenant).
• Call Extension: This will send a call not to trunk, but to an extension. The extension must be in the replacement field. This option can be useful when using PSTN gateways behind NAT that must register with the PBX as an extension in order to be accessible through the firewall.
• Try Loopback: When there are multiple tenants, the PBX may try to send the call into another tenant through a "loopback trunk". The replacement must contain a telephone number (starting with +) or a SIP URL with a username and a tenant that exists on the system (since version 5.4). If that account can be located on the local system, the call will be sent there. This makes it easy to use multiple tenants on the same system without an external SIP proxy.

Pattern Matching

Simplified pattern matching.

There are two ways to match the dialed number, simplified and extended regular expression.

Before feeding a number into the pattern matching the system represents the number in the local tenant country code format. For example, in the US with the country code 1 a number 1617123123 would be reformatted to 6171231234 and +493055578992 would be formatted into 011493055578992 (unless a different presentation was selected). This makes it easy to match patterns, no matter how the user has dialed the number.

Simplified expressions are based on the following rules:

• Patterns can be separated by the | symbol. In this case the pattern matches if one of the pattern matches. For example 911|411 would match either number 911 or 411.
• A literal matches if the input is equal to the parameter. For example the pattern 911 matches only if the dialed number was 911.
• The symbol x in a pattern matches any character. For example, the pattern x11 matches 911, 411, and any other 3-digit number that ends in 11.
• The symbol * matches an arbitrary long number of digits. When using this pattern, the replacement will use only the digits matched by the symbol.
• Symbols in angle brackets match the characters in the bracket. For example pattern [0-7] matches characters 0 to 7, [134] matches characters 1, 3 or 4.
• Area codes can be matches by using a area codes pattern. For example [usa] matches the domestic USA area codes (more below). This makes sure that the rule applies only to a list of codes that are hard to express in a pattern. For example the pattern [usa]xxxxxxx would match only domestic USA destinations.

Currently the following area codes are defined:

• [usa] domestic USA (3 digits)
• [can] Canada area codes (3 digits)
• [ala] Alaska area codes (3 digits, currently 907)
• [haw] Hawaii area codes (3 digits, currently 808)
• [fre] Toll Free USA area codes (3 digits, currently 800 888 877 866 855 844 833)
• [pre] Premium USA (3 digits, currently 900)
• [pue] Puerto Rico area codes (3 digits, currently 787 939)
• [dom] Dominican Republic area codes (3 digits, currently 809 829 849)
• [vir] United States Virgin Islands area codes (3 digits, currently 340)
• [eur] European Union country codes

For simplified patterns, the replacement contains literals and the * symbol to insert the match. For example, 789* would put 789 in front the number that was matched. If there is no replacement pattern, it will automatically insert the matched pattern.

Extended Pattern Matching

Extended pattern matching is more powerful, but it comes at the price of higher complexity. Simple and extended patterns can be mixed in the dial plan per dial plan entry.

The input to extended patterns is in the form number@domain. The patterns are fed into the extended regular pattern matching. The matches can be referenced with the \1, \2 and so on. \r references the tenant DNS name.

Dial Plan Samples

Basic Dial Plan

In many cases, you may just want to route all numbers to an outside trunk. This can be done easily by using the pattern * You don’t need to fill anything into the replacement field, the system will automatically use * as replacement.

Dial Plan with prefix in front of the number

If you use a pattern like 1* in the replacement field, the system will automatically put a 1 in front of the match that it found in the pattern field. In the case when you use the pattern 617* and dial the number 6171234567 , the system will automatically convert that into a 16171234567.

(Emergency Numbers)

In the past it was common to use a prefix to tell the system that the call is an outbound call, for example a 9. While this is confusing for most callers, it is dangerous for users in case of emergency when there is no time to figure out how to make an outbound call. In some juristictions including the United States is it now the law that callers must be able to dial emergency numbers without a prefix.

A North American Dial Plan

If you use the Vodia PBX telephone system in the fixed-length dial plan of North America, you may use a dial plan similar to the one that follows:

911|411 The first pattern matches the emergency number and the service number explicitly. It is a good idea to have an entry for these important numbers so that they don’t accidentally get routed to the wrong gateway or are rejected. If available, these calls can be sent to a seperate trunk which might point to a local gateway.

011* The second pattern matches all international numbers and sends them to a special trunk, which is intended to save costs for international calls.

[usa]xxxxxxx The third pattern deals with all domestic calls. The fixed-length pattern was used so that the system can actually tell when this number is complete. The replacement puts a 1 in front of the number, putting it into a 11-digit representation.

Extended regular expressions

If the standard simple dialplan processing does not fit the needs, the system can use extended regular expressions instead. A typical dial plan would include the string ([0-9]*)@.* as pattern and sip:\1@\r;user=phone as the replacement. The pattern string has one group [0-9]* (which is referred in the replacement string as \1). That means that if the pattern is matched against the value 2121234567@test.com, it will store 2121234567 in the first group and the result will be sip:2121234567@test.com;user=phone (the user=phone indicates to the recipient that the number is a telephone number).

The following dial plan illustrates the use of the caret. It’s being used to force the system to begin matching from the start of user input.

Assigning dial plans

You can create several dial plans and give them different names.

You can select any of these dial plans as a default dial plan for a tenant. The setting is Default dial plan in the general settings .

When the dial plan for accounts, like extensions or auto attendants, is set to default, then the above tenant default dial plan will be used for that account.

However, any other dial plan (from the list you created) can be set for each account, like extensions, or auto attendants etc.

Text mode

Complex dial plans can be hard to edit. In order to make this easier, there is a text mode in the dial plan web page. This mode converts the dial plan into a CSV text file that can be edited and copied e.g. into other tenants.