Dial Plan User Guide

User Story

• A caller based in France does not use any prefixes and only places calls to local phone numbers. Typically, to use KAZOO the customer would have to get used to typing prefixes in order to place calls.

Overview
The Dialplan app enables you to support simplified dialing for outbound phone calls. Using a RegEx syntax, Dialplan can take a number a user has dialed and transform it into a number recognized by E.164 global formatting. Users who are used to dialing phone numbers in a way that only works in their specific country can now continue to dial numbers in that way.

Users can dial local numbers, just as they do with the PSTN, by providing Kazoo with DialPlan regular expressions. These regexps will be used on the dialed numbers to correct them to properly routable numbers.

It is possible to set these regexps on an account, user, or device basis.  Kazoo will then apply the regexes in order, preferring the calling device's, then user's (if the calling device is assigned to a user), and finally the account's dialplan.

Before you start
This application assumes you are familiar with using Regular Expression syntaxes, or RegEx, which is a sequence of characters that define a search pattern where the result can be then used for an additional task. It is often used for searching and replacing telephone number strings. There are several websites that provide help in creating and testing these expressions. For starters you can try the links below.

• For more information on how to create or edit a RegEx Expression, see this page.
• To test your RegEx formula, go here.

Home Screen
On opening Dial Plan you will see three tabs: Account | User | Device, and a listing of any Dial Plan rules if any have been assigned.

Account Tab
This shows any System Rules:  rules that are applied to the entire account.

• System Rules will display if they have been pre-configured based on your system install. These are typically related to international calling rules.

• Custom Rules will be where you create custom rules for the entire account. 

  • Description:  Enter a description that says what your RegEx will do
  • Regex:  Enter the actual regex calculation
  • Prefix:   Enter the digits before the regex
  • Suffix:   Enter the digits after the regex

You can test your Regex by typing a series of digits (likely a phone number)  in the empty box.  You should see a result something like this:

The example below shows capturing any digits and adding 502 as the areacode

User Tab

The user tab provides the same options to add RegEx rules, this time unique only to the user. Select the user from the dropdown, and add your RexEx.


 

Device Tab
The device tab provides the same options to add RegEx rules, this time unique only to a specific device. Select the user from the dropdown, and add your RegEx.

Some Tips

Be careful your rules do not interfere with extension dialing within an account

It is possible that these dial_plan rules will interfere with extension dialing within an account.  Please take common extension length into consideration when creating these dial_plan rules.

Determine if a number is "global"#

The first thing to configure is how to tell when a number is "globally rout able" versus an internal extension. This is managed in the system_config/number_manager configuration document, under the reconcile_regex key.

"reconcile_regex": "^\\+?1?\\d{10}$|^\\+[2-9]\\d{7,}$|^011\\d{5,}$|^00\\d{5,}$"

Here is the default, which if reading regex's isn't second nature, optionally matches a + and a 1 (the country code for the US), followed by any 10 digits, or matches 8-or-more digit numbers (prefixed by a +), or the international dialing codes for the US.

This regex must be able to match number formats your carrier(s) will send you. In the US, it is normal to see the 10-digit number (NPA-NXX-XXXX), optionally with a 1 prepended (NPANXXXXXX), or the full E.164 version (+1NPANXXXXXX). The default reconcile_regex matches all of those. Internal extensions, like 100, 2504, or *97, will obviously fail to be matched with the reconcile_regex and thus be rout-able only by authorized devices within an account.

Globally distributed users

Users within an account may be located anywhere in the world. An account-level dial_plan may not make sense for them. Instead, place dial_plan objects on the users' documents to ensure their local dialing preferences are honored.

Country samples#

France +33#

Calls within France are 10-digit numbers with a leading 0; from outside of France, only the last 9 digits (omitting the 0) are dialed after the +33 country code. Armed with this knowledge, a regex might look like:

"reconcile_regex":"^(?:\\+33\\d{9})|(?:0\\d{9})$"

Note: (?:) is a non-capturing regex group

This should match calls dialed within France (using the 0 followed by a 9 digit number) as well as calls coming from outside of France (+33 followed by a 9 digit number).

One locale for all devices in an account

If all of the users/devices in an account are located in the same city, it would be most convenient to place a DialPlan at the account level, allowing them to dial as they are used to and converting it for Kazoo processing. For instance, we can use the following  ^(\\d{7})$  regex for an account whose users are all in Louisville, KY. Then, when a user dials a 7-digit number, it is prepended with the 502 area code (as well as +1).

FAQs

Can I create RegEx rules for incoming calls?
No. The dialplan app is only designed for outgoing call management.

API References

docs.2600hz.com