Child pages
  • How to configure Dial Plans
Skip to end of metadata
Go to start of metadata


Dial plans are needed in support of telephone numbers. Dialing rules match certain patterns of digits and map them to specific routing rules using gateways. Much of the flexibility but also much of the complexity of an IP PBX system is in its dial plan capabilities. sipX aims at abstracting most of this complexity into a set of simple management operations using a Web user interface.

Basic Operation

The new sipX Web user interface allows for configuring quite flexible dial plans. The current capabilities of the Web UI should cover a lot of cases that until now were only configurable through direct manipulation of XML files.

In configuring a dial plan the typical sequence of operations is as follows:

  1. Define all gateways you are planning to use for a new rule
  2. Configure the actual dial plan rules
  3. Activate the dial plan

Activating the dial plan generates the following XML files in the directory /etc/sipxpbx: <tt></tt>, <tt></tt> and <tt></tt>. Any previous versions of those files are backed up (.in~).

Once all the rules are configured, pressing the <tt>Activate</tt> button takes you to the activation screen. As an advanced option the actual XML files can be viewed in read-only mode.

Note: The activation process restarts a few processes for the new dial plan to become effective, which takes a second or two. Already established calls are not affected.

All gateway and dial plan information is kept in the sipXconfig database. You can modify and regenerate your dial plan without configuring everything from scratch. Reverting the dial plan restores to the default (factory) configuration.

Defining PSTN Gateways (FXO)

Gateways are required to connect the sipX system to the PSTN. The sipx system can accommodate as many gateways as you like and they can be anywhere on the network as long as there is not NAT between sipX and the gateway.

To configure a new gateway go to Network Services - Gateways and click on Add Gateway. Enter a name for the new gateway and an IP address or DNS resolvable fully qualified name. It is recommended to either use fixed IP addresses or DHCP assigned addresses that are reserved for the gateway's MAC address. The value in the name field and the description are only used for administrative purposes. The name is used throughout the UI to identify a specific gateway. The address is the only part of the gateway definition that affects call routing rules in the dial plan.



Note: If you are going to make external calls to the PSTN you need to have at least one gateway configured.

Configuring Dial Plan Rules

The dial plan consist of <i>dialing rules</i>. There are several types of rules and every rule (if enabled) will contribute to the call routing behavior of the sipX system.

{{Box Important| It is possible to have more than one rule of each kind. The order of the rules matters and you can therefore reorder rules. The more specific rules have to come first and before the more generic rules of the same type. The reason is that rules are processed top to bottom. The first rule that matches a dialed number is applied immediatly, which would prevent more specific rules further down to be tested.|}

The Dial Plans screen represents the management interface to administer dialing plans. New rules can be created, existing rules can be enabled or disabled, and the order of rules can be modified.



Primary and Backup Gateways: Most of the rules allow for the configuration of multiple gateways. If you add more than one gateway to a given rule, then all calls that are handled by this rule will be forwarded as a serial fork (i.e. in sequence until the call succeeds or no more gateways are available) to the gateways in the order the gateways are displayed in the UI. For instance a branch office can have a limited number of PSTN lines connected to a gateway. If all local lines at that office are busy, the calls can be automatically re-directed to a larger gateway at headquarters.

Emergency Calling: A separate gateway for emergency calling can be defined. It's address can be configured directly into the phones, which allows phones that support this feature to place emergency calls even if the sipX server is unavailable.

Internal Dialing

The Internal dialing rule determines many of the characteristics of your internal dialing plan. It is here where you define the length of internal numbers (e.g. 3 digits, 4 digits), what auto-attendant to use by default for incoming calls, the alias used for the default auto-attendant as well as the extension users dial to get to the voicemail system.



The sipX system supports multiple auto-attendants. Several rules of type Internal can be used to define different different auto-attendants. If you use more than 1 internal dialing rule make sure that only one of them specified the voice mail extension and voice mail prefix. The rule that specifies the voicemail has to be below other internal rules, otherwise it will intercept the calls to additional auto attendants.

Several rules of type Internal can also be used to allow you to support a dial plan with different station extension lengths for different ranges of internal extensions. The Internal rule does not require a gateway (obviously).

Internal station extension length: This setting defines the length of internal numeric extension numbers. If this setting is changed, the setting Maximum internal extension length under Configuration / Voicemail should be changed as well. This setting influences the dial plans stored in the phone and allows the phone to automatically initiate a call after a sufficient number of digits was entered without requiring you to press dial.

Auto attendant: This drop-down menu allows you to select an auto-attendant for this instance of the Internal rule. Additional auto-attendants are defined by going to "Auto Attendants''.

Auto attendant alias: A comma separated list defines aliases assigned to the auto-attendant selected in the previous field. By default, this alias is used when a caller presses "0" to reach an operator. (E.g. if a call is not picked up and therefore transferred to voicemail, the caller can press "0" to reach an operator). In order to reach an operator the call is transferred to SIP URI If the alias operator is assigned to the auto-attendant in the Internal Dialing rule, then the call is transferred to the auto-attendant specified in this rule. If you would like the call to be transferred to a person on a specific extension or a hunt group, assign the alias operator to that user or hunt group.

Voicemail extension: This is the extension number a user has to dial to reach the sipX voicemail system. It should have the same number of digits as defined under Internal station extension length. You should only specify voice mail extension in the last of your internal rules.

Voicemail inbox prefix: Using the voicemail prefix provides a mechanism to directly address a user's voicemail inbox instead of ringing the user's phone first. For instance, you can leave messages directly into a user's inbox if you don't want to call a user on the phone.

Auto Attendant Dialing Rule

Auto Attendant Dialing is a new type of dialing rule introduced in sipXconfig 3.2. It handles functionality previously serviced by Internal Dialing Rule and adds couple new features.

Once you configure one or more Auto Attendants you make them available by adding extension (and optionally add aliases) on Auto Attendant Dialing Rule screen.

In the simplest case it allows you to select an auto attendant and its extension. On a newly configured system there is a single Auto Attendant Dialing rule that associates extension 100 with default auto attendant operator.

In addition to that you can select other auto attendants that will be accessible during working hours and during holidays.

To configure working hours attendant select it from a "Working time attendant" drop down menu. The sipXconfig will refresh the screen. You will be able to select working hours for each day of the week. If someone calls during this hours the call will be handled by the attendant that you selected as "Working time attendant".

Similarly you can select a "Holiday attendant". Once you choose an attendant name from drop-down menu sipXconfig will show additional section that let's you to add, edit and delete holiday dates. Please note that holiday is a data and not a day in year. You have to add separately New Year's Eve in 2006 and in 2007.



Each auto attendant dialing rule defines a single schedule. You can have more than one auto attendant dialing rule, as long as each rule has a different extension. Rules can reference the same auto attendants. For example you can have a single "vacation" attendant that is responsible for handling vacation announcements for more than one extension.

Emergency Dialing

The emergency dialing rule allows the definition of a specific gateway to be used for emergency calls. This rule also allows you to specify an emergency number common for your country or situation. Several gateways can be specified in this rule, which provides fail-over capability using serial forking in case a gateway in unavailable.

Note: The most fault tolernat and therefore best way to define an emergency dialing plan is to directly program the emergency gateway address into the phone. This can be done for most phones in addition to defining a global emergency dialing rule by going to the respective phone's configuration screen in the sipX user interface. This allows emergency calls to be routed to the PSTN gateway even in case the sipX server system is unavailable.



Using Caller Sensitive Routing you can define emergency routing rules based on the station from which the emergency number is dialed. Click on the link in the white comment box on the right to get to the Caller Sensitive Routing screen.

Note: Using Caller Sensitive Routing rules for emergency call routing replaces the more simplistic emergency dialing plan described above.

Long Distance Dialing

The Long Distance rule is one of the most powerful rules available. You can specify the PSTN prefix, long distance prefix and comma separated list of area codes. PSTN prefix is stripped before the call is sent to the gateway, Long Distance prefix is kept when call is sent to the gateway. If you configure 9 as your PSTN prefix and 1 as your long distance prefix and dial 912223334444 the gateway will see 12223334444.

The area code field allows for specifying optional list of secondary prefixes - area codes, country codes, local codes - you use it only if you want to restrict your rule to particular range of numbers which maybe useful if you have a dedicated gateway that you want to handle calls to a particular area. If you specify 508, 77 as your area codes the rule will be triggered by 915083334444 and 917783334444 but not by 915073334444.

Since you can decide if you prefixes are mandatory or optional (click on "Show Advanced" link). Optional prefix does not have to be dialed, however optional long distance prefix is sent to the gateway even if it's not dialed.

Type field allows for specifying which permission is required for the caller to have a call handled by the rule. You can select one of the predefined permissions (local, long-distance, toll-free, restricted, mobile, international calls) or custom permissions.



If you leave the area code field empty, ConfigServer will generate the following generic rules (matching patterns). The example is for a PSTN prefix of "9", a long distance prefix of "1" and a 10 digit number. This means that all calls with 10 digits, with or without a long distance prefix and with or without an external line prefix (PSTN prefix), will be routed to the gateway(s) assigned to handle long distance calls.


If you configure specific area codes, such as "508" and "617", you can specify that calls to certain area codes will be routed to specific gateways. This allows you to define least-cost routing rules where calls are routed over the IP network to the gateway that can provide PSTN termination at the lowest cost. For a PSTN prefix of "9", a long distance prefix of "1" and areas codes of "508" and "617" you get the following rules (matching patterns). Again, several rules of type Long distance can be defined to match different least cost routes.


You can also specify area codes with various lengths.

Note: User (i.e. an originating line) has to have long distance permission enabled (in one of the groups it belongs to or directly) in order to be able to make long distance calls to the PSTN. Refer to how to configure users and groups.

Restricted Numbers

The Restricted Numbers rule is a special case of a Long Distance rule. All three long distance rules (Long Distance, 900 Dialing, and Toll Free) combine respective permissions assigned to the user (i.e. the originating line that represents a user) with a dialing rule. Therefore, in order for the Restricted rule to apply to a call the user originating the call has to have "900 Dialing" permissions set for the group to which the user belongs to. This permission setting is Disabled by default. All "900" calls will be routed to the gateway(s) specified.

If your locality requires a different number to be dialed than "900" to reach such services, the area code field can be changed accordingly. For the call to succeed the user still requires "900 Dialing" permission enabled.

Important: Choose type 900Dialing.



Note: For a user (i.e. an originating line) to be able to make a "900" call to the PSTN, the group to which that users belongs to has to have the relevant permissions. Refer to how to configure users and groups.

Toll Free Numbers

Similar to the Restricted Numbers rule, the Toll Free is a special case of a Long Distance rule. All three long distance rules (Long Distance, 900 Dialing, and Toll Free) combine respective permissions assigned to the user (i.e. the originating line that represents a user) with a dialing rule. Therefore, in order for the Toll Free rule to apply to a call the user originating the call has to have "Toll Free" permissions set for the group to which the user belongs to. This permission setting is Enabled by default. All "800" calls will be routed to the gateway(s) specified. Default toll free area codes specified are "800, 866, 877, 888".

If your locality requires different numbers to be dialed to reach toll free services, the area code field can be changed accordingly. For the call to succeed the user still requires "Toll Free" permission enabled.

Important: Choose type Toll Free.



Note: For a user (i.e. an originating line) to be able to make a toll free calls to the PSTN, the group to which that users belongs to has to have the relevant permissions. Refer to how to configure users and groups.

Custom Dialing Rule

The Custom Dialing rule allows you to translate a matching string of digits into a different string of digits predicated on a set of permissions defined for the user who originates the call. For instance a second sipX server could be represented by a gateway entry. All calls with an extension that starts with a given digit would be routed to this second sipX server
that serves a different geography or building.



You specify the dialing patterns (this is what users dial), call patterns (how the resulting call is translated) and a set of permissions that are required for the call to get through. The intention is that most users do not have to use custom rules at all. If we notice that it becomes popular it probably means that one of the standard rules needs to be extended or that we need yet another rule type.

In the "Dialed Number" field, specify the number prefix to match plus the number of additional digits; for example, to match 543xxx, the prefix is "543" plus 3 digits.

vdigits & digits: "vdigits" will resolve to the variable part of the dialed number (without the prefix); "digits" will resolve to the entire number that was dialed.

Note: For this custom rule to apply to a call made by a user (i.e. an originating line), the group to which that users belongs to has to have all the permissions checked in the definition of this custom rule. Refer to how to configure users and groups.

In v3.6+, the "Resulting Call" action terms have changed.

  • "Nothing": dial the resulting call number from the "Prefix" field.
  • "Variable part of dialed number": dial the number in the "Prefix" field plus the matched suffix from the dialed number above
  • "Entire dialed number": dial the number in the "Prefix" fields plus the complete number that was originally dialed

Note: The Custom Dialing Rule can also be used without specifying a gateway. In this case it performs translation of incoming digits into a string of outgoing digits without sending the call to a gateway.

Custom call permission

In addition to the default set of call permissions you can define custom permission specific to your dialing plan. You can for example create a "expensive_long_distance" permission to restrict calls to some area codes. Custom permissions are also used to localize the dialplan to other countries or regions where additional rules are desirable.

Legacy dialing rules

Prior to 3.6 release, sipXconfig required creating special rule for long distance and international dialing. They were mostly geared to Northern American dialing scheme. Improved long distance dialing handles local, international, mobile and other dialing permissions butold rules are still stored and interpreted by sipXconfig.

Local Dialing

The Local dialing rules specifies how the sipx system should handle PSTN calls to your local calling area.



Here you specify the length of local external numbers and the PSTN prefix to be used by users of the sipx system to get an outside (local) line. Rules are generated that match numbers dialed with or without prefix so that even without dialing the prefix the call should be routed correctly.

Note: For a user (i.e. an originating line) to be able to make a local call to the PSTN, the group to which that users belongs to has to have the relevant permissions. Refer to how to configure users and groups.

International Dialing

The International Dialing rule is similar to the Long Distance rule, but specifies international numbers. No number of digits is specified as international numbers vary country by country. The rule allows the definition of the international prefix and again specifies one or more gateways for international call termination.

Note: The International Calls Prefix can have various length. Therefore several rules of type International Dialing can be used to define least cost routes to different international destinations. For example, if you have a local gateway in a certain country, a long distance rule could be specified that routes calls to that country to the local gateway.



Note: For a user (i.e. an originating line) to be able to make international calls to the PSTN, the group to which that users belongs to has to have the relevant permissions. Refer to how to configure users and groups.

Activate the Dial Plan

The dial plan is activated by clicking on Activate. Follow the instructions on the next screen.

{{Box Important|The Dial Plan is not active until activated. There is no warning or other message that will remind you to activate the dialplan should you defer that to later after making changes.|}



Note: In order to complete the activation process certain server processes need to be re-started. sipXconfig will offer to restart necessary services automatically. This will take 1 to 2 seconds and in-process calls are not affected.

Using rules unsupported by Dial Plans UI

There are - hopefully rare - cases when dialing plan rules generated by sipXconfig UI are not sufficient. Starting with sipXconfig 3.2 one can amend automatically generated files by injecting rules defined in external files. In most cases this should not be a permanent solution. It requires a a good understanding of mapping rules file formats and calls redirecting architecture. It is always a good idea ask the question on users list before restoring to injecting mapping rules or authorization rules externally.

In order to do inject the rules from external file you need to modify /etc/sipxpbx/ file and set one or more of the following properties (depending on which file you want to modify):


The property value should designate a valid XML file (in the same format as the file that you want to modify).
Entire content (all children of the root mappings element) of the external file is inserted before the content generated by sipXconfig UI.

If external file does not exist, is inaccessible or has invalid format dial rules are still generated and errors are logged in sipXconfig.log.

You can use sipXconfig Show XML on Activate Dial Plans screen to preview the content of the dialing plan XML file including both externally injected rules and the rules generated by sipXconfig.

External rules example

This example describes how to inject the rule translating all calls addressed to users in into calls addressed to standard SIP domain known by sipX. Of course in order to receive such calls you'd have to configure DNS in such a way that resolves to IP address of the machine on which sipX is installed.

{{Box Code|/etc/sipxpbx/external_mappingrules.xml|


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mappings xmlns="">








And add the following line to /etc/sipxpbx/ file:


You must Activate at least one dial plan in order for the external rule(s) to be inserted into the configuration (activating an existing dial plan will work, and no changes need to be made in the dial plan before activation). Sipx services must then be restarted in order for the config change to be used (as part of the activation process you will be asked if you want to restart services). After activation you should see the "hostMatch" element from external_mappingRules.xml in the newly generated file. If so, then after services are restarted you should see the "hostMatch" element in the mappingrules.xml file.

  • No labels