How to give a particular extension different or restricted trunk access for outgoing calls

NOTE: Unlike some of the how-tos in this section, this one is written for those who have some experience with adding contexts to /etc/asterisk/extensions_custom.conf or some familiarity with Asterisk dial plans. It is not as much a "cookbook" type of document as suggestions on how to reach the goal of giving a particular extension different or restricted trunk access for certain types of outgoing calls. I am not saying that the ways I show here are the only ways, or even necessarily the best ways to accomplish this goal. If you can improve on what I have written, please leave a comment - I may incorporate it into the main text (with credit to you, of course).

IMPORTANT: When implementing any sort of restrictions on extensions, using the method described here or any other method, please be absolutely certain that you do not inadvertently restrict access to emergency services numbers (such as 911 in the U.S./Canada)!

There is a recurring question that comes up every so often, regarding how to give one particular extension (or a group of extensions) access to a different trunk for specific outgoing calls, or perhaps to restrict access to a particular trunk. Usually this involves an extension that is accessible to people that might want to make calls that cost money, and you don't want them to do that. But there are many other reasons to route calls differently for different extensions, while still keeping all extensions on the same system so they can call each other.

Usually when someone asks about this, a common suggestion is to use the unsupported third-party Custom Contexts module. While this module is very versatile and lets you have a high degree of control over what each extension may access, there are at least two downsides. One is that it's not part of the official distribution and therefore, a future upgrade of FreePBX might "break" it. The other issue is that you have to go through and check (and maybe change) all the priority dropdowns if you add, remove, or move a route, and that can get to be a pain in the butt very quickly if you are in the habit modifying your routes with any frequency.

Restricting Outgoing Calls

Let's deal with restricting outgoing calls first. Before going any further, I will mention for the benefit of expert users that Rob Thomas has developed an Outbound Route Permissions module for FreePBX, that allows you to block access to certain routes from specified extensions. You can do bulk changes on the Route Extensions configuration page, and you can individually change access to routes on the extension's page. At this point (May, 2009) this is still an unsupported module in the first stages of development.

Having said that, there was an article in Moshe's blog entitled Restricting outbound calls in FreePBX (blacklist). That approach allows one to blacklist calls system-wide, but it does not allow calls to be passed or blocked selectively depending on the calling extension. But shortly thereafter, Moshe came out with a second blog post, Restricting outbound calls in FreePBX (whitelist), which not only does allow calls to be passed or blocked selectively depending on the calling extension, but also allows you to "whitelist" certain numbers (in case you want the "restricted" extensions to be able to dial certain number despite the restrictions). Moshe takes a slightly different approach than what I do below - Moshe allows you to restrict on a per-extension basis, but the restriction is for ALL routes with the only exceptions being the specific "whitelisted" numbers. My approach (as well as that of the aforementioned Outbound Route Permissions module) assumes you may only want to restrict access to some routes. It also allows you to restrict on a per-extension basis, but the restriction is then only applied to specific routes that you wish to restrict (calls to numbers in non-restricted routes can still go through).

Before we begin, it would be good if you had a solid mastery of the difference between routes and trunks, and how they interact. If you have not already done so, I suggest you read Hints on Route Dial Patterns and Trunk Dial Rules.

Here's one way to set up a restriction: Use a text editor (nano, Midnight Commander's editor, etc.) to add the following two dialplan fragments to /etc/asterisk/extensions_custom.conf (note, if your extensions can pass the # character to Asterisk then change all instances of _[*0-9]! to _[*#0-9]! - adding the # character - this applies to all examples on this page):

[custom-restricted-ext1]
exten => 911,1,Noop(Allowing unrestricted 911 call)
exten => 911,n,Goto(from-internal,${EXTEN},1)
exten => _[*0-9]!,1,Noop(Using Call Restriction 1)
exten => _[*0-9]!,n,Set(_RestrictedExt1=TRUE)
exten => _[*0-9]!,n,Goto(from-internal,${EXTEN},1)
exten => h,1,Hangup()

[custom-restricted-trunk1]
exten => _[*0-9]!,1,Noop(Testing for Call Restriction 1 ${RestrictedExt1})
exten => _[*0-9]!,n,GotoIf($["${RestrictedExt1}" = "TRUE"]?restrict1:norestrict1)
exten => _[*0-9]!,n(restrict1),Noop(Call blocked due to call restriction: 1)
exten => _[*0-9]!,n,Playback(feature-not-avail-line,noanswer)
exten => _[*0-9]!,n,Goto(app-blackhole,congestion,1)
exten => _[*0-9]!,n(norestrict1),Noop(No call restriction: 1)
exten => h,1,Hangup()

In the code above, change both instances of 911 to your local emergency number if it is something other than 911, or remove those two lines completely if you do not wish to permit the restricted extensions to make emergency calls (doing that is NOT recommended except in very special circumstances).

After adding this additional code to extensions-custom.conf, create a new custom trunk with the Custom Dial string Local/$OUTNUM$@custom-restricted-trunk1 , then go into any Outbound Route to which you wish to restrict access, and move that new custom trunk to the top of the trunk list (or second from the top if you have an ENUM trunk at the top, assuming that you don't care if a free ENUM call actually goes through).

The go into any extension that you wish to restrict and change the context from from-internal to custom-restricted-ext1. After saving all the configuration changes, you should be able to place a test call that would use the restricted route. You should hear the "That feature is not available on this line" recording (the most appropriate one I could find among the standard recordings supplied with FreePBX).

If you wanted to have different restrictions for different extensions, you could just make additional contexts. Here's an example for use with a second group of restricted extensions:

[custom-restricted-ext2]
exten => 911,1,Noop(Allowing unrestricted 911 call)
exten => 911,n,Goto(from-internal,${EXTEN},1)
exten => _[*0-9]!,1,Noop(Using Call Restriction 2)
exten => _[*0-9]!,n,Set(_RestrictedExt2=TRUE)
exten => _[*0-9]!,n,Goto(from-internal,${EXTEN},1)
exten => h,1,Hangup()

[custom-restricted-trunk2]
exten => _[*0-9]!,1,Noop(Testing for Call Restriction 2 ${RestrictedExt2})
exten => _[*0-9]!,n,GotoIf($["${RestrictedExt2}" = "TRUE"]?restrict2:norestrict2)
exten => _[*0-9]!,n(restrict2),Noop(Call blocked due to call restriction: 2)
exten => _[*0-9]!,n,Playback(feature-not-avail-line,noanswer)
exten => _[*0-9]!,n,Goto(app-blackhole,congestion,1)
exten => _[*0-9]!,n(norestrict2),Noop(No call restriction: 2)
exten => h,1,Hangup()

For this second group you'd then create another custom trunk with the Custom Dial string Local/$OUTNUM$@custom-restricted-trunk2. Then, at the top of the trunk list for any route, you could add either or both of your custom trunks, depending on which groups of extensions you wanted to restrict from using that particular trunk.

This approach does not incorporate a specific "whitelist" feature, however if you wanted to whitelist certain numbers (so they could be called even by "restricted" extensions) and those numbers happen to match one of your "restricted" routes, simply create a new outbound route similar to the restricted one, but that contains only the "whitelisted" numbers listed in the Dial Patterns text box, and that duplicates the trunk list of the restricted route - except, of course, you do not include your custom trunk that enforces the restriction! Make that route higher in priority than the restricted route. Since you are only matching the "whitelisted" numbers in that route, it will allow calls to those specific numbers go through without restriction. Of course, you could use patterns rather than specific numbers if you wanted to do something like un-restrict an entire area code, or entire telephone exchange prefix.

A possible alternative approach to restricting outgoing calls (for advanced users only)

Although I have not attempted to use this method, I just wanted to point out that there is an alternative approach that could possibly be used that would potentially eliminate the need to change the context in extensions or to use custom trunks. In the file /etc/asterisk/extensions.conf there is a context called macro-dialout-trunk-predial-hook which, according to comments within that file, is "intentially left blank so it may be safely overwritten for any custom requirements that an installation may have" and that any such "customizations to this dialplan should be made in extensions_custom.conf." What that means is you can create a [macro-dialout-trunk-predial-hook] context in /etc/asterisk/extensions_custom.conf and it will override the (intentionally blank) context in extensions.conf. The macro is called whenever a call goes out over any trunk, therefore if you can determine which trunk is being used and which extension is placing the call, you can determine whether the call should be blocked.

Unfortunately, by the time that a call reaches the trunk, the original calling extension number is apparently not preserved except as part of the CHANNEL variable (the CALLERID(number) variable may be an acceptable substitute in certain situations). And if a call is forwarded, the number of the extension that's actually doing the forwarding may or may not be found in the DIALEDPEERNUMBER variable. You can test to see what variables are available by adding the following code to /etc/asterisk/extensions_custom.conf

[macro-dialout-trunk-predial-hook]
exten => s,1,NoOp(Trunk ${OUT_${DIAL_TRUNK}} selected)
exten => s,n,Macro(dumpvars)
exten => s,n,MacroExit()

Place a test call that uses a trunk and watch the CLI and you will see some of the available and the current contents of those variables. Note that the full trunk name is printed on the CLI by the first line. By editing [macro-dialout-trunk-predial-hook] you can set up conditional statements, such that if a call from a particular extension (extracted from the CHANNEL variable) is being sent to a particular trunk, you can restrict it.

If you use this method, make sure that the last statement in the macro is MacroExit(), and it would probably be a good idea to read some documentation on Asterisk macros before you begin. Also, keep in mind that the Gotoif statement can contain multiple conditions. For example, the Gotoif line could look something like this like this:

exten => s,n,GotoIf($[$["${OUT_${DIAL_TRUNK}" != "SIP/restrictedtrunk"] & $["${CHANNEL:0:7}" != "SIP/234"]]?skip)

...which would jump to the label "skip" unless the trunk name was "restrictedtrunk" and the call originated on channel "SIP/234..." (presumably extension 234).

The page on Asterisk Expressions gives more information on connecting expressions with logical operators such as & (and) and | (or).

Different Routes for Different Extensions

The above code will only restrict calls. It will NOT handle the case where (for example) you have two companies using the same FreePBX system, and you want one company's calls to go out on one route while the other company's calls use a different route. The problem is that FreePBX will only attempt to use one route for outgoing calls that match a specific dial pattern - once a dial pattern has been matched with a route, it will not try additional routes. So, you can restrict certain extensions from using a particular route, but it's a lot harder to make FreePBX try a different route that would match the same dial pattern. You CAN do things like this using the unsupported Custom Contexts module (if it still works with the version of FreePBX you are using). You can also do it using the aforementioned Outbound Route Permissions module for FreePBX - as noted above, at this point (May, 2009) this is still an unsupported module in the first stages of development.

Both the Outbound Route Permissions module and the method I am about to describe use route prefixes to select the desired route. To help you understand this technique, you may wish to read the document Basic usage of route prefixes to reroute calls from specific extensions.

Here's an approach (to making some extensions use one route and some another) that I've used in the past, before the Outbound Route Permissions module was available (even if you don't plan to use this method, you may wish to read on because the basic technique is very similar). First, I made a duplicate of a particular outbound route (using a different route name, of course). In the duplicated route, I changed the trunk selections. I kept the dial patterns the same, except that in front of every line in the dial patterns I added a few more digits followed by a bar character (example, if the original route contained a pattern such as 1NXXNXXXXXX, the duplicated route contained 0000999|1NXXNXXXXXX - I like to use patterns with a few zeroes in front because no real number begins with several zeroes. Note I had to add the 0000999| to the start of EVERY line in the dial patterns of the duplicated route).

So now I had two routes, the general one with the truck selections used by most extensions (and with the "normal" dial plan), and the duplicated one which contained the trunk selections I wanted to use with a particular extension, and with the modified dial plan.

In addition, I also made a separate route for 911 calls from that one extension (I'm using 911 here, substitute your local emergency number if it is different) - in that route I added the dial pattern 0000999|911 and set up the trunk selection for 911 calls from that extension. If you want all your 911 calls to go out the same trunk(s) regardless of which extension they came from, then you could just add the 0000999|911 pattern to your existing 911 route. Just remember that your emergency routes should be the highest priority (at the top of the routes list).

Next I added this to /etc/asterisk/extensions_custom.conf:

[custom-trunk-selector-1]
exten => _[*0-9]!,1,Set(restprefix=0000999)
exten => _[*0-9]!,n,Set(sysextlen=3)
exten => _[*0-9]!,n,Goto(custom-trunk-selector,${EXTEN},1)
exten => h,1,Hangup()

[custom-trunk-selector]
exten => 911,1,Goto(from-internal,${restprefix}${EXTEN},1)
exten => _1NXXNXXXXXX,1,Goto(from-internal,${restprefix}${EXTEN},1)
exten => _NXXNXXXXXX,1,Goto(from-internal,${restprefix}${EXTEN},1)
exten => _NXXXXXX,1,Goto(from-internal,${restprefix}${EXTEN},1)
exten => _*72!,1,Goto(custom-app-cf-on-rest,${EXTEN},1)
exten => _*90!,1,Goto(custom-app-cf-busy-on-rest,${EXTEN},1)
exten => _*52!,1,Goto(custom-app-cf-unavailable-on-rest,${EXTEN},1)
exten => _[*0-9]!,1,Goto(from-internal,${EXTEN},1)
exten => h,1,Hangup()

[custom-app-cf-on-rest]
exten => *72,1,Answer
exten => *72,n,Wait(1)
exten => *72,n,Macro(user-callerid,)
exten => *72,n,Playback(call-fwd-unconditional)
exten => *72,n(startread),Playback(ent-target-attendant)
exten => *72,n,Read(toext,then-press-pound,,,,)
exten => *72,n,GotoIf($["foo${toext}"="foo"]?startread)
exten => *72,n,Wait(1)
exten => *72,n,Set(saytoext=${toext})
exten => *72,n,GotoIf($[${LEN(${toext})} <= ${sysextlen}]?noprefix)
exten => *72,n,Set(toext=${restprefix}${toext})
exten => *72,n(noprefix),Set(DB(CF/${AMPUSER})=${toext})
exten => *72,n,Playback(call-fwd-unconditional&for&extension)
exten => *72,n,SayDigits(${AMPUSER})
exten => *72,n,Playback(is-set-to)
exten => *72,n,SayDigits(${saytoext})
exten => *72,n,Macro(hangupcall,)
exten => _*72.,1,Answer
exten => _*72.,n,Wait(1)
exten => _*72.,n,Macro(user-callerid,)
exten => _*72.,n,Set(toext=${EXTEN:3})
exten => _*72.,n,GotoIf($[${LEN(${toext})} <= ${sysextlen}]?noprefx)
exten => _*72.,n,Set(toext=${restprefix}${toext})
exten => _*72.,n(noprefx),Set(DB(CF/${AMPUSER})=${toext})
exten => _*72.,n,Playback(call-fwd-unconditional&for&extension)
exten => _*72.,n,SayDigits(${AMPUSER})
exten => _*72.,n,Playback(is-set-to)
exten => _*72.,n,SayDigits(${EXTEN:3})
exten => _*72.,n,Macro(hangupcall,)
exten => h,1,Hangup()

[custom-app-cf-busy-on-rest]
exten => *90,1,Answer
exten => *90,n,Wait(1)
exten => *90,n,Macro(user-callerid,)
exten => *90,n,Playback(call-fwd-on-busy)
exten => *90,n(startread),Playback(ent-target-attendant)
exten => *90,n,Read(toext,then-press-pound,,,,)
exten => *90,n,GotoIf($["foo${toext}"="foo"]?startread)
exten => *90,n,Wait(1)
exten => *90,n,Set(saytoext=${toext})
exten => *90,n,GotoIf($[${LEN(${toext})} <= ${sysextlen}]?noprefix)
exten => *90,n,Set(toext=${restprefix}${toext})
exten => *90,n(noprefix),Set(DB(CFB/${AMPUSER})=${toext})
exten => *90,n,Playback(call-fwd-on-busy&for&extension)
exten => *90,n,SayDigits(${AMPUSER})
exten => *90,n,Playback(is-set-to)
exten => *90,n,SayDigits(${saytoext})
exten => *90,n,Macro(hangupcall,)
exten => _*90.,1,Answer
exten => _*90.,n,Wait(1)
exten => _*90.,n,Macro(user-callerid,)
exten => _*90.,n,Set(toext=${EXTEN:3})
exten => _*90.,n,GotoIf($[${LEN(${toext})} <= ${sysextlen}]?noprefx)
exten => _*90.,n,Set(toext=${restprefix}${toext})
exten => _*90.,n(noprefx),Set(DB(CFB/${AMPUSER})=${toext})
exten => _*90.,n,Playback(call-fwd-on-busy&for&extension)
exten => _*90.,n,SayDigits(${AMPUSER})
exten => _*90.,n,Playback(is-set-to)
exten => _*90.,n,SayDigits(${EXTEN:3})
exten => _*90.,n,Macro(hangupcall,)
exten => h,1,Hangup()

[custom-app-cf-unavailable-on-rest]
exten => *52,1,Answer
exten => *52,n,Wait(1)
exten => *52,n,Macro(user-callerid,)
exten => *52,n,Playback(call-fwd-no-ans)
exten => *52,n(startread),Playback(ent-target-attendant)
exten => *52,n,Read(toext,then-press-pound,,,,)
exten => *52,n,GotoIf($["foo${toext}"="foo"]?startread)
exten => *52,n,Wait(1)
exten => *52,n,Set(saytoext=${toext})
exten => *52,n,GotoIf($[${LEN(${toext})} <= ${sysextlen}]?noprefix)
exten => *52,n,Set(toext=${restprefix}${toext})
exten => *52,n(noprefix),Set(DB(CFU/${AMPUSER})=${toext})
exten => *52,n,Playback(call-fwd-no-ans&for&extension)
exten => *52,n,SayDigits(${AMPUSER})
exten => *52,n,Playback(is-set-to)
exten => *52,n,SayDigits(${saytoext})
exten => *52,n,Macro(hangupcall,)
exten => _*52.,1,Answer
exten => _*52.,n,Wait(1)
exten => _*52.,n,Macro(user-callerid,)
exten => _*52.,n,Set(toext=${EXTEN:3})
exten => _*52.,n,GotoIf($[${LEN(${toext})} <= ${sysextlen}]?noprefx)
exten => _*52.,n,Set(toext=${restprefix}${toext})
exten => _*52.,n(noprefx),Set(DB(CFU/${AMPUSER})=${toext})
exten => _*52.,n,Playback(call-fwd-no-ans&for&extension)
exten => _*52.,n,SayDigits(${AMPUSER})
exten => _*52.,n,Playback(is-set-to)
exten => _*52.,n,SayDigits(${EXTEN:3})
exten => _*52.,n,Macro(hangupcall,)
exten => h,1,Hangup()

Then in the extension setup for that particular extension, I changed the context from from-internal to custom-trunk-selector-1.

In custom-trunk-selector-1, I define the restriction prefix and the length of extensions on the system (the length is only used for call forwarding - set it to the maximum length of a local extension number on your system). Note that for additional restrictions you could make more of these short contexts with different restriction prefixes.

In the main custom-trunk-selector context I send 911 (emergency) calls, and 11, 10, and 7 digit calls to from-internal, but with the restriction prefix prepended. I will point out that the 911 line is not necessary if you don't need special routing for 911 calls from any restricted extension, but if you use it make sure that there is a valid 911 route for every restricted extension! In this case I did want to force 911 calls from the restricted extension to use the specific trunk assigned to that extension.

So, when the user of the restricted extension places a call, it first goes to the customized context to see if it appears to be a 911 call or an 11, 10, or 7 digit number in North America (the first four lines of the context) - if so it prepends our unique code (0000999 in this case) to the front of the number before sending it on to from-internal. If it is a call forwarding activation code (*72, *90, or *52) it goes to a modified version of the dialplan that handles call forwarding setup (see further discussion below). If it matches any other pattern (the last line of the context), the number goes to from-internal unchanged.

When a call that has matched a NANP pattern gets to the routing tables, it will skip the "normal" route and go to the route to which I prepended the 0000999| to the front of each entry in the dial patterns. The | (vertical bar) character tells the route to strip off the 0000999 before sending the call on to the trunk.

Note the above is rather simplistic and may require more tweaking to get the results you want. If there is a particular route that you want used by ALL extensions (for example, your outbound route for toll-free calls), but the entries in that route's dial plan are a partial match for the patterns in the customized context, you can simply duplicate the dial plan entries and prepend the unique code in front of the duplicates (so in your toll-free route you might have both 1800NXXXXXX and 0000999|1800NXXXXXX, etc.) - no need to create a separate route in that case (where all extensions use the same trunk selections).

One other point - if you want forwarded or follow-me calls to use the restricted route, then you must include the special prefix when setting up the forward or follow-me! If an extension user sets up call forwarding by dialing one of the codes *72, *90, or *52, then the above custom dialplan will take care of storing the forwarded number in the database with the prepended restriction code, so that forwarded calls will use the route associated with the called extension (if, for some reason, that's NOT what you want, omit the three lines that handle *72, *90, and *52 in custom-trunk-selector, and then omit the three contexts that start with custom-app-cf-). Only numbers exceeding the length of a local extension (as defined in custom-trunk-selector-1) will have the restriction prefix prepended.

Note that the modified call forwarding code does not prompt the user to enter an extension. I'm not sure why that's allowed in any case, especially without any verification requirement such as entry of a PIN code, but in this situation you really don't want to be able to set call forwarding for one extension by calling in from a different one, unless you want the system using the wrong route for forwarded calls. I'm not saying the dialplans could not be modified to permit this, but I'm not going to be the one to attempt it. I'm trying to keep things reasonably simple here.

The call forwarding contexts were copied from extensions_additional.conf and then modified. The problem with this approach is that future versions of FreePBX may change something in the original [app-cf-on], [app-cf-busy-on], and [app-cf-unavailable-on] contexts, necessitating revisions of the custom code above. But there's really no other way to handle user-entered call forwarding where a restriction prefix may be added, other than trusting the user to include the prefix when setting call forwarding (probably not a good idea).

Again, please note that if you set up call forwarding using any other method (such as the Extension Settings) tool, YOU are responsible for prepending the restriction prefix.

And just to add a little extra complication, the above discussion and code assumes that you want FreePBX to handle forwarded calls locally, but that might not always be the case. If a particular user happens to have their own provider trunk and their own DID, and if the provider offers call forwarding, then you might want to pass call forwarding requests upstream to that provider (so that each forwarded call doesn't occupy two channels between your FreePBX switch and the provider). In other words, where possible you may want to offload the task of call forwarding to the upstream provider, but if you do that keep in mind that local (extension-to-extension) calls won't be forwarded unless you can figure out some way to also set the forwarding in FreePBX. The exact method for doing this will vary between providers, but hopefully the hints in this section will have given you some ideas on how to handle that situation. If you wanted to get really fancy, you could write an AGI script to log onto the provider's web portal and change the call forwarding there, but that's definitely beyond the scope of this document!

I hope this helps someone, and keep in mind there's a good possibility that I may add more to this page later on, particularly if I discover better ways to do this. You might also get some ideas from this post.

What about restricting calls between extensions on the same FreePBX server?

While this is a bit outside the original topic of this How-To, the question came up about how to make a particular extension or group of extensions unreachable from certain other extensions. While I have no idea why anyone would want to do this, it can be done using similar techniques to those used for restricting calls to certain trunks, but it potentially might involve a fair bit of effort. Let's say you wanted to restrict calls to extension 299 and all extensions in the 440-449 range (this is just an example) - you might add something like this to /etc/asterisk/extensions_custom.conf:

[custom-restricted-internal]
exten => 299,1,Goto(app-blackhole,congestion,1)
exten => _44X,1,Goto(app-blackhole,congestion,1)
exten => _[*0-9]!,1,Goto(from-internal,${EXTEN},1)
exten => h,1,Hangup()

The first line of the context would send all calls specifically made to extension 299 to congestion - you can use as many lines as you need if you need to restrict calls to more than one extension. The second line is an example of a pattern match, restricting all calls to extensions matching the 44X pattern - note the underscore at the start of the pattern; this indicates to Asterisk that you are matching a pattern and not an individual extension named "44X". The third line catches any other number containing the digits 0-9 and/or the * character in any position, and passes it on to the from-internal context.

After setting up the context as you need it in extensions_custom.conf, you'd then go to the configuration page for each of the extensions you want to restrict (yes, every single one of them, one by one) and change the context from from-internal to custom-restricted-internal, or whatever you called your context.

Note: Some of the material in this How-To was excerpted from the post, A different approach to placing outgoing calling restrictions on certain extensions, which goes into more detail on the restriction method described above.