TUTORIAL Dial Plan Explanation

[alewis]

Looking for a simple but comprehensive tutorial on dial plans and call routing, preferably with worked out examples, and detailed explanations of each digit in a dial plan (x n | etc) and what they do.

For example, assuming one (or more) SIP lines and a PSTN line, the dial plans for directing calls out over each according to the numbers dialed, and working examples of "dial plan '09|xn xxxxx' on a number '901234 567890'" does this:
sees the zero and keeps it, sees a 1 and knows to route to PSTN.
sees a whatever and drops it
Asterisk then dials 01234 567890 out the PSTN lines

And similar for SIP services.


"Its been done"... well, maybe. I've read the PBXIAF guides and they left me with questions. To expand on the first paragraph, showing example dial plans, and then what happens step-by-step to a dialled number, how it is translated, and what number comes out afterwards. When you are new, its difficult to understand "| does that" and "x does that". Some examples would be great.

I have searched the topics, found two pages of results which I am working through, but so far nothing meets what I am looking for.

Why? In the long term, I want to understand dial plans fully. In the short term, I want to ensure that calls are routed correctly. For example, calls to 01xxx, 02x, and 0800 via PSTN, and 00 numbers either depending on the next two digits.

Thanks in advance

 

[wardmundy]

Dial Plans 101

Good idea, and I've added it to the Wish List.

To get you started, dial plan logic is managed with FreePBX. When someone picks up a phone and dials a number, that begins an outbound call unless FreePBX determines that there is an internal match on an existing Extension, Ring Group, or Miscellaneous Destination. Assuming no internal match on the number that is dialed, Outbound Calls begin by searching through the Outbound Routes (from top to bottom) for a Dial Pattern match on the phone number that has been dialed. If there's a match, that Outbound Route wins the call, and the search for an Outbound Route ends forever on this call. Then the search for a Trunk to place the call begins. The trunks in the winning route are searched from top to bottom for a Dial Pattern match on the phone number. Once a trunk has a match to a phone number, the call goes out that trunk. If there's congestion detected on that trunk or if the call flunks the ENUM check, the call drops down to the next trunk in the same Outbound Route only and the call is attempted again. This process of elimination continues until the call is completed or rings busy OR until you run out of available trunks to try in the winning outbound route.

Dial Patterns work like this. A blank dial pattern matches every number dialed. The same applies if a dial pattern consists of nothing but a period. Then you can get more specific from there. For example, NXXNXXXXXX says the dialed number must be exactly 10 digits long, and the first and fourth digits can't be zero or one. 1NXXNXXXXXX says the dialed number must begin with a 1 and the second and fifth numbers can't be zero or one. XXX. says the number must be four or more digits long. Any numbers will do. Using three Dial Patterns of 411, 1NXX5551212, and NXX5551212 would cover all the possible ways to dial Directory Assistance in the United States.

Then you can get fancy. 9|NXXNXXXXXX says the number must begin with a 9 and be 11 digits long with the second and fifth numbers non-zero/one. And this dial pattern says strip off the leading 9 before passing the call along. You typically find logic like this in an Outbound Routes Dial Pattern. You should arrange the sequence of Outbound Routes with the more specific entries at the top of the list (e.g. calls with a prefix or calls to Information) and the more general and generic entries at the bottom of the list. That way you make certain that every call that you intend to be successfully completed has an available Outbound Route. Here's a more complex example of an Outbound Route we call Information that redirects all Directory Assistance calls to a free service:

411|18003733411
NXX5551212|18003733411
1NXX5551212|18003733411

In a Trunk Dial Pattern, you might use an entry like this: 1+NXXNXXXXXX. This says that if the number passed to me is 10 digits long and the first and fourth numbers are non-zero/one, add a leading prefix of 1 to the number before actually placing the call. You might do something similar for 7-digit calls in your hometown when your ITHP is on the other side of the country, e.g. 1843+NXXXXXX. You usually do this to make a dialed number match what your service provider is expecting to see to complete the call.

This should get you started. I haven't had much coffee this morning so there may be something I overlooked or totally screwed up, but we have lots of whiz kids that will chime in and correct me. Good luck!

 

[alewis]

Cheers! That is a better explanation than anything I have found yet in the various documentation!

If I knew the ins and outs, I'd write it up myself together with call-flow diagrams... but as I lack the basic grasp of it...!

I'm sure it is one of those things that for many people is a "light-bulb" moment. You can read and read but it doesn't quite click, and then one or worked-out examples and "bing".

 

[jroper]

Here's something I knocked up a while ago for some training I was doing:-

[FONT=Liberation Sans, sans-serif]Outbound Routing and Trunks.[/FONT]


There are two sections where numbers can be manipulated before passing them out to the outside world. The trunk and the outbound route.
The Trunk




The first thing to note is there is no point whatsoever of putting any anything in the trunk dial rules unless it changes the dial string. The dial rules are there for manipulating the number before sending it onto the carrier.



For instance, many VoIP carriers require calls to be sent to them in what is known as IETF format. For instance, someone in the USA would dial: -

011 44 1179 1179 33 to speak to me in the UK however, your ITSP will only require:-
44 1179 1179 33
In the UK and much of the rest of the world, we simply prefix with a 00, so to call me normally, the user dials 00 44 1179 1179 33, however the carrier requires 441179117933



In the USA, there is a system of numbering called the NANP – the North American Numbering Plan. The plan is made up of three sections:



NPA – the area code [2-9][0-8][0-9]
NXX – The exchange Code [2-9][0-9][0-9]
Station Code – [0-9][0-9][0-9][0-9]



All numbers in the USA follow the above convention. However, the USA international code is 1, therefore your ISP may require you to actually send 1 followed by the remaining 10 digits.



The Outbound Route

The outbound route selects which trunk to use depending on the number dialed by the customer.
It goes in strict order from the top, trying to match the number actually dialed with the pattern in the outbound route. When it matches with a pattern, then it will select the first available trunk connected to that route.



Generally speaking, we try and get all the numbers into the same sort of order before delivering them onto the the trunk. e.g. In the USA, we would be trying to get them into 10 digit NANP format. For the rest of the world, we would be delivering the numbers with the international dialing code, so that if the call goes out via a standard land line, it will simply be delivered as is, whereas if you are going out via a provider, you can add and remove digits to suit the carrier.



The Tools

In both outbound routes and trunks, there are a number of codes that are used to filter or select numbers as well as to do manipulation.



Selection

X – Matches any digit from 0 to 9
Z – Matches any digit from 1 to 9
N – Matches any digit from 2 to 9
[123] – Matches only the numbers in the brackets, e.g. 123
[1-3] – Matches a range of digits in the brackets, again 123
[1236-9] – Matches a range of digits as above, 123 678 and 9
. Is a wildcard and matches everything. Asterisk warn against just putting in a . to match with everything – it is better practice to put X. to match everything.



So in the North American numbering plan mentioned previously, we had:-
NPA – the area code [2-9][0-8][0-9]
NXX – The exchange Code [2-9][0-9][0-9]
Station Code – [0-9][0-9][0-9][0-9]



Which translates to
N[0-8]XNXXXXXX
However, for simplicity, it is just written as NXXNXXXXXX



Another example is a UK Cellphone.



The number always starts with a 447, and next digit is a number between 4 and 9, and always with another 9 digits after the 7 – so this number would be selected as 447[4-9]XXXXXXXXX, being lazy, you could just select the number as 447. but there is a danger that people could dial numbers beginning 4470 which are over a dollar a minute, and provide a revenue share for the owner of the number.



Manipulation

Numbers can be manipulated with the following operands.



“+” - Adds a number onto the dialed digits.
“|” _ Subtracts a number from the dialed digits.



So in the USA, to add a 1 onto the front of the NANP dial it is as simple as putting in 1+NXXNXXXXXX before delivering the number to your VoIP carrier. Do this in the trunk dial rule.




In the UK, things are slightly more tricky. When we dial say my number in the UK, we would dial 01179117933, so to get this into IETF format, we have to remove the leading 0 and replace with a 44. This can be achieved by putting in a manipulation rule in the trunk dial rules. 44+0|ZXXXXXXXXX This rule would strip the leading 0 off and add a 44 onto the front where the number was 11 digits long, started with a 0, and the next number was not a 0.



Also in the UK, we can dial locally for instance, 01788 is the Rugby code, and then there are 6 digits, where the first digit is not a 0. So to pass this over a VoIP trunk in IETF format, we need to add 441788 onto the front of the number – this is easily done with 441788+ZXXXXX. However, there is one small problem – directory inquiries in the UK begin with 118 followed by 3 digits, so we would have to put a precise rule in for that as well 118XXX and make sure it went out via a suitable trunk.



The | can be used to help people move from an old PBX, where you do 9 for an outside line, and you still want people to dial with or without a 9. Simply put 9| NXXNXXXXXX and NXXNXXXXXX in the dial patterns box in the outbound route.



This will therefore match any 10 digit NANP number, and any 10 digit NANP number prefixed with 9.



Practicalities




The first job is to create all the trunks, with dial rules to put them into IETF format where necessary, so that the number is delivered as the carrier expects to see it.



The we can move onto Outbound routes.



The first job is to ensure that the emergency services can be called. In the USA, this is 911, or if you are in a panic, it may be 9911 (9 for an outside line) In the UK, it is 999 and in much of Europe 211.



Taking the USA as an example, it is usually preferable to send emergency calls out over the local PSTN so that the caller ID is correct, and the emergency services know where to find you. There are E911 services, but keeping it simple, we assume all Emergency calls are going out over the local PSTN lines.



Operator Services and local calls.

So Create an outbound route, select the first PSTN trunk, and all the others (just in case) and put in:-
911 ; Will call emergency services
9|911 ; Will call emergency services even if they did 9 for an outside line.



Additionally, we can put some other patterns in here for any other numbers which have to go out over the PSTN. IN the UK, we have operator services, which are all 3 or 4 digits long, and never more than 5, so a simple:
ZXXXX ; 5 Digit numbers not starting with a 0
ZXXX ; 4 Digit numbers not starting with a 0
ZXX ; 3 Digit numbers not starting with a 0



In my experience, operator services and numbers that have to be dialed via the PSTN are never more than 5 digits and always start with a 1 to 9.



Then we want to do the same for people who still want to dial 9 for an outside line – as per the legacy system
9|ZXXXX ; 5 Digit numbers not starting with a 0 and prefixed with a 9 for an outside line
9|ZXXX ; 4 Digit numbers not starting with a 0 and prefixed with a 9 for an outside line
9|ZXX ; 3 Digit numbers not starting with a 0 and prefixed with a 9 for an outside line



You may also want to put in something 777|. So you can test your analogue trunks are working correctly, to force a call over the PSTN by prefixing your call with a 777.



National

The next Outbound route entry will be say for your USA, or national numbers, e.g.



NXXNXXXXXX ; NANP numbers
9| NXXNXXXXXX ; NANP numbers, where the user has prefixed with a 9



The leading 1, or whatever has to be added on the front will be added on by the trunk dial rule.
If you are using VoIP, you may want a hidden dial string to force calls over the VoIP trunks, so maybe add 888|. to force calls over VoIP.
International Calls

The final entry, maybe for your international calls.



The length of the dialed digits can vary depending on where you are calling, so this will be the last outbound route.



So in the USA, the international prefix is 011 and the next number will be a number between 1 and 9, so an entry for international routes will be



011Z. Which will match any international number
For the rest of the world that uses 00 as the international prefix, 00Z. Will achieve the same ends.



Again, the 00 or the 011 will be stripped off by the dial rule in the trunk.



Again, we would want to make provision for people dialing 9 for an outside line



9|011Z. Or 9|00Z. As appropriate for your country.



Clearly these rules can be moved around to suit your own particular requirements.



Inbound Routes




It is not well documented, but it is possible to pattern match on inbound routes in the caller ID, this is done by prefixing the Caller ID to be matched with an underscore. So to match all calls that come from Germany, which has a dialcode of 49, simply type _49. in the inbound route caller ID field. This will match all calls which begin with a 49, with anything after it. You can use all of the selection digits to pattern match that you use in the outbound routes.


Joe

 

[alewis]

Joe

Many thanks, this is a lot clearer than much of the documentation.

But...

There are areas where it isn't clear whether you are talking about editing the trunk outgoing dial rules, or the outbound route dial calls... I'm sure that from someone who has the "knack" its obvious, but from the view point of someone who doesnt know, it isnt...

I'm not being picky! I'm tearing my hair out trying to work why call is not being placed over a SIP trunk. I just get "service not available".

And I don't know enough to work out whether I have put dial rules in the wrong place, or what.

This is my understanding.

PBX needs to decide which route a call takes. This the purpose of the outbound route dial rules, which act as a filter, if you like. It pattern matches.

The Trunk dial rule then manipulates the number the user has dialled, and turns it into a number (format) the voip provider or telco requires.

So, without the complication of PSTN routes, or North American dialling to the UK, or anything else that I'm not going to be doing as I live in the UK this is my understanding

My outbound route has
.

the trunk sequence is "voicetrading_sip" (voicetrading provide the voip service)

This simply means any number, send to the trunk named voicetrading_sip.

Trunk. The voicetrading_sip SIP trunk has a single dial rule
0000144+9|0|XXXXXXXXXX

I understand this to mean:
strip the leading 0
strip the leading 9
add 0000144
so if the user dial 901234 123456 the number dialled by the pabx is 0000144 1234 123456 (less spaces, of course) the carrier requires 00001 plus the country code.. At the moment I just want to place a test UK call, within the UK, from the UK

I'm pretty sure the rules are simple, very very simple. Manipulating numbers is very easy. Whats not easy to work out though is when examples use a term that appears in two contexts, without specifying which context it refers to, (or states one then shows an example referencing the other) I DO appreciate the help guys, its just very frustrating when trying to work out whether my mistake lies in the manipulating I am doing, or because I have put it in the wrong section, or both!

Once I understand the basic concept, I'm sure I'll be able to work how to filter on national, international, NGN, PSTN, etc etc. Its just this first hurdle that's proving a problem.

Thanks again, and hope someone can help!

 

[jroper]

Hi

You seem to have it about right.

Outbound Routes select which trunk to use

Trunks manipulate the digits for the carrier.

In the Outbound Route, I would have 9|0[12]X. and strip the 9 off before passing it off to the trunk.


then in the trunk, you only need 000144+0|[12]X.

This would strip off the 9 in the outbound route, selecting on the basis of a 0 followed by 1 or 2 (UK landlines), then any numbers, in the trunk, the 0000144 is added, and the leading 0 removed.

Joe

 

[alewis]

Cheers Joe

Now I'm challenged

The possible numbers that might get dialled

4 digit internal
6 digit external
11 digit external
11 digit NGN
international calls in nn format (e.g. 45 <number>)
international calls in 00nn format (e.g. 0045<number>
international calls in 00n or 00nnn format (001 for US, 00998 for uzbekistan)

How the hell!!!! Given voice trading offers 3 clases of service, I'm going to keep it simple and use 00 prefix (rathe than 0000 or 00001 or "grey" or "gold").

What I have worked out so far, which strips leading 9 and passes what is left

4 digit internal... erm.. ! how does it do this?
9|ZZZZZZ (6 digit external, eg local nos)
9|[0]ZXXXXXXXX (for 10 digit Uk numbers. rare)
9|[0]ZXXXXXXXXX (11 digit UK numbers*)

Up to this point, the trunk dial plan would have 0044+0| to add 0044 and strip any leading 0.

I'm assuming it strips any leading zero.. hence dialing 9 01202 123456 flows like this
OB route strips the 9 and passes 0102123456 to the trunk
Trunk strips the 0 and adds 0044, sending 0044 1202 123456 (spaces added for clarity)
Likewise dialling 9123456
OB route strips the 9 and passes 123456
Trunk - no leading 0 to strip, only adds 0044 and sends 0044 123456 (space for clarity).

Which now buggers me on how to accomodate non-uk numbers!
9| then ??? and what the heck to put into the trunk rule!???

Hmm. should I train users to dial full codes 001 to 00999, or.. or or... hang (apology, typing as I think...!) on, do I not do anything... what would I need to have the OB manipulate and pass the number to the trunk, so the trunk is only adding 00... (or 00001)
e..g I dial 9-123456 or 9 01202 123456 the trunk strips the 9, the zero if it exists, adds 00

0044+9|ZXXXXX turns 9123456 into 0044123456
0044+90|ZXXXXXXXXX
0044+90|ZXXXXXXXXXX 9 01202 123456 into 0044 1202 123456 and likewise for 10 digit national codes
00+9|[Z]
00+9|[ZZ]
00+9|[ZZZ]

Um and there I run out of steam on how to strip and add numbers to accomodate internal, local, national/ngn, and int calls!!!

Help!!!! (thanks!)

 

[jroper]

I'm sort of getting confused looking at how you hve done it, so I don't know how you must be feeling about it.

Lets see if I can knock up some rules for you that work for the UK. I'm assuming you are doing 9 for an outside line - this is traditional, although now completely pointless.

Operator calls, 999,100 152 etc

These have got to go out via your BT lines,

So create first OB route, for OPerator numbers - anything less than 5 digits, starting with a number between 1 and 9 will be a number that HAS to go out via the PSTN - so call this opeator numbers, put in the following:

9|ZXX
9|ZXXX
9|ZXXXX
9|118XXX ;Directory enquiries

Outbound UK National and Non Geographic

Create your second outbound route for everything else - I'm assuming that this is all going to go out via your provider, and only fall over to BT if the provider fails. UK numbers start with a 0 followed by a number between 1 and 9. Yes there are different length numbers, but we know that it is a UK call if it starts with with a single 0 and the next number is not 0.

So in it's simplest form,

9|0Z.

Will capture anything bound for the UK - you could be more granualar if you want to block PRS numbers like 09 and 070

e.g.

9|0[1258]. ; Landlines, VoIP numbers starting with 05 and NGN's begining with 08
9|07[4-9]. ; Mobiles (all start with 074 to 079)


International

International calls in the UK and most of the restof the world use 00 to to get an international line, this USA uses 011, but they are fairly unique in that respect.

So this is very simple, an International number is any number that starts with a 00 followed by a number between 1 and 9, therefore an outbound route will simply say:-

9|00Z.

If you are not using different trunks for international calls, then you could put this in the UK outbound route.

Trunks

Now moving onto the trunks.

You have ZAP trunks - no dial rules need to be put in here, you just send the number out exactly as dialled.

If you have got one of those BT feature lines that insist on a 9 prefix before every call, then just put in 9 in the "outbound dial prefix" box, or indeed you use a 1xxx operator.

In respect of your carrier that demands two things from you:-

1. That you deliver you calls in international format with no international prefix like 00, or 011

2. That you prefix all calls with a 00, 000, 00001 or whatever to chose which route you want.

Remember that the 9 for an outside line has been already stripped off before it gets to the trunk, so we don't have to worry about it.

So we have two types of calls coming to our VoIP trunk: -

1. International calls - these are easily dealt with , just strip off the leading 00 and send them to the carrier.

2. UK national calls, they need the leading 0 stripped off and pre-pended with 44.

International calls, create a dial rule that says:-

00|Z. ; any number dialled with a 00 followed by 1 to 9, followed by anything else, take off the 00.

National calls:

44+0|Z.

We've already filtered out the 09's and 070's etc in the outbound routes, so all we have to do is strip off the leading 0, and prepend a 44.

Finally, we have the prefix for the carrier to select which route you want (Grey, STandard or Gold)

Just add the prefix 00, 0000 or 00001 etc, in the "Outbound Dial Prefix" box, then you can change the routing quickly and easily.

Job done.


So quick summary;

First OB route

9|ZXX
9|ZXXX
9|ZXXXX
9|118XXX

With Landlines selected as the only trunk.

Second OB Route (Simple Version)

9|0Z.
9|00Z.

Voip Trunk first, then Zap Trunks.

ZAP Trunk

Nothing, unless you have BT feature line or 1xxx operator

VoIP Carrier

44+0|Z.
00|Z.

Put the routing prefix in the Outbound Dial Prefix.



Joe

 

[alewis]

Many thanks Joe

These work a treat, and I think I understand how it fits together now

Now for a different problem,... troubleshooting when nothign has changed!!!

 

[jpe]

Adding a 1 to NXXNXXXXXX

I've tried the 1+NXXNXXXXXX in every hole it would fit, but i am getting no joy.
i'm trying to get numbers from the address book that dont have a 1 to dial out.
I've read this thread and half a dozen others, but I must have a monkey block cuz it's beating me in the head right now.

 

[jroper]

Try NXXNXXXXXX in the outbund route and 1+NXXNXXXXXX in the trunk associated with the outbound route.

Joe

 

[lks4414]

I work in a k-12 school district in the USA. I need to verify my work please.
911
9|911
2.
6.
9.

911 would call emergency services
9|911 would strip off the first 9 needed for centrex and call emergency services
2. for centrex numbers beginning with 2
6. for centrex numbers beginning with 6
9. for matching any numbers beginning with centrex 9 dialed for outside line. With this last entry do I even need 911 or 9|911 ?

 

[wardmundy]

Much of this depends upon your service providers and which ones are equipped to handle 911 calls. We recommend a separate Outbound Route for Emergency services with the 911 and 9|911 entries for Dial Patterns. The trunk sequence should only included providers that support 911 services. This outbound route should obviously be moved to the top of your list of Outbound Routes in FreePBX.

With regard to the 2., 6., and 9. entries, for your own phone bill protection, we'd recommend using more specific entries, e.g. NXXNXXXXXX and 9|NXXNXXXXXX would protect you from international calls. For internal calls between your extensions, you don't need dial patterns. When you would use an entry such as 2XX or 2XXX would be in the situation where you have several Asterisk systems and want to provide a route for local users to reach extensions on another Asterisk PBX.

 

[lks4414]

We are using pots lines to a single central office. Here in Indiana, USA, and our service is centrex. For us, prior to PBXinaFlash, you just dialed 911 and the old Merlin system placed the call out an analog POTS line. the 2 and 6 idea was to give them what they had which was 3 digit calling to other buildings over the centrex service. In your example I thought the N was a digit 2-9 which works for me but the XXNXXXXXX meant there had to be that many digits. so would I be
2xx
6xx
9|nxxnxxxxxx
?
My only providers on my trunks is the centrex POTS lines.

 

[twinclouds]

Hi, Joe:
I am recently try to find some information about the dial plan, your post is the best I have seen. Thank you for your work.
I am using Ward's Orgasmtron 5.1 and it is great for domestic calls. However, it is not set up for international calls. I would like to set up such call plans following your description. The problem is that there are many trunks and outbound routes and I don't know which one I should modify. I can use try and error to modify one by one but it will really be helpful if someone can provide more specific guidance. Thanks in advance.

 

[jroper]

Hi

The matches in outbound routes are done from the top down, so by inspection, you should be able to work out where in the list to put it.

Joe

 

[twinclouds]

Do I also need change any trunks with dial plans?

 

[jroper]

Hi

That depends on the carrier, and how they want the number presented.

Joe

 

[twinclouds]

OK. I tried it after got home. It worked after I added the international calling pattern to my outbound route. I added it to the last one "default" but I guess anyone will do. Thanks for your help.

 

[twinclouds]

It is working now. Thank you for your help.