Miscellaneous/Custom application/extensions: How to extend FreePBX with custom dialplan (part 1 of 2)

FreePBX was primarily designed to be a simple and easy to tool for programming asterisk dialplan and call flow. In the name of simplicity, however, it is sometimes necessary to sacrifice advanced features and overly complex ways of doing things. FreePBX takes a great middle ground in providing the best of both worlds: on one hand, an extremely powerful yet intuitive and simple GUI, and on the other hand a really neat way to seamlessly extend the gui into ‘raw’ dialplan. This is done using a combination of the Custom and Miscellaneous modules.

First, a small refresher on Asterisk Dialplan. Every asterisk instruction is composed of four parts:
  • Context
  • Extension
  • Priority and
  • Application

For example:


exten => 66,1,Playback(tt-monkeys)

In this example, when a call hits extension 66, priority 1 in context play-monkeys asterisk will Playback the tt-monkeys voice prompt. Additionally, Asterisk also includes the ability to include one (or more) contexts inside another using the (believe it or not…) include command, for example:


exten => stuff here

include some-other-context

FreePBX takes advantage of the include feature to keep its dialplan simple and clean by breaking up the dialplan in to smaller contexts. The context FreePBX uses for its call routing is the from-internal context. from-internal itself is pretty much a blank context – accept for two includes. You can see it here:


include => from-internal-xfer

include => bad-number

from-internal-xfer includes (amongst others) from-internal-additional and from-internal-custom. from-internal-additional is also pretty sparse – except for some more includes of many, many smaller context, corresponding to the entire FreePBX generated dialplan. from-internal-custom is always included – and always empty – so that you can use it as you’d like. Simply start a new context in /etc/asterisk/extensions_custom.conf and add your dialplan there. So to include our play-monkeys context in the FreePBX generated context we would add the following to /etc/asterisk/extensions_custom.conf:


include => play-monkeys

exten => 66,1,Playback(tt-monkeys)

followed by a dialplan reload (asterisk -rx "dialplan reload" or asterisk -rx "extensions reload" if your on asterisk 1.2). That’s all! Now pick up an extension and dial 66. You should hear the tt-monkeys file being played back.
While this method is really simple, its got its drawbacks: If you were to include some code with, say, extension 66, and then you would set up a phone at extension 66 in FreePBX – what would happen when you dial 66?
That’s right, asterisk would be kinda confused: it wouldn’t know which ’66’ to call (actually it would pick one of them – but which is another story). In order to prevent such a situation, FreePBX rigorously protects the dialplan from having a double entry. You can’t, ever, have two extension with the same extension number (try it!). You also can’t have other ‘destinations’ (which are also called extension in asterisk dialplan language) such as ring groups or queues with the same extension number as another extension.

to be continued…


Moshe Brevda, FreePBX Development Team
lazytt – FreePBX forums
hi365 – IRC

Time Groups & Time Conditions

FreePBX 2.5 breaks down Time Conditions in to two separate modules: Time Groups and Time Conditions. The reason? To confuse you! Nay, we wouldn’t do that. But in case we did, this should set the record straight.

First, lets have a look at the old way of doing things: For illustrative purposes, we’ll talk about the CEO of a multi billion dollar corporation. Obviously, as the most powerful and best paid person in the company, he does the least amount of work, and when he does, he tires quickly. Fortunately for him, they built his office with tons of amenities – including a power napping station where he takes a daily afternoon nap. There is just one thing they forgot to do: automatically turn off his phone during that period. This is the precise purpose of time conditions.
Until now, a setup like this required a lot of work. First, you would set a time condition for Monday morning from 10:00 am until 12:30pm. You would then set the "Destination if time matches" as your extensions. As the "Destination if time does not match", you would put in the next time condition – 2:00pm to 3:30pm (wish those were your working hours, eh?). But wait – you didn’t create that time condition yet. So you’ll need to save this one, then create the next one. If your still following, you’ll realize that you will run in to this problem again – the ‘condition failed’ destination is not yet created. Or in other words, you need to work backwards, starting from Thursday afternoon, and working up the week from there.

By the time your done, you should have at least 10 different time conditions – just for this one extension. Now imagine if there are 4 other people in the company on the same schedule – were pushing fifty time conditions – for just five extensions! And that not including the usual company widetime conditions – including various work schedule’s, open hours, holidays, etc.

Here to save the day is naftali5’s Abstracted Time Groups and updated Time Conditions, (as implemented by FreePBX project lead – Philippe Lindheimer). In a nut shell, what this upgrade does is it separates the time condition from the destinationallowing for the same ‘set’ of conditions to be ‘reused’ many times. Back to our example. In order to accommodate our tired CEO, we would click on the Time Groups module (assuming that the Time Conditions module is installed) and create a new time group by clicking add a new time group. Enter a description, such as "executive working hours". Now start by creating the first time group (10:00am-12:30 pm, mon-thu) and click Submit. Now pick the "Executive working hours" from the time groups menu, and add the second time group (2:00pm – 3:30pm mon-thu), and click submit. When your done it should look like this:

Time Group


Now, click on the Time Condition module. Add a time condition called "CEO’s working hours" and select "Executive working hours" from the time groups drop-down list. Now, simply select the CEO’s extension as the "Destination if time matches" and his voicemail as the "Destination if time does not match" (or send the call wherever you would like – depending on your needs). Bravo! Can it be simpler? If you need to set the same time conditions for other exec’s, just create a new time condition – and reuse the time group as many times as you’d like! The time condition should look something like this:

Time Condition

One more thing:

This solution beautifully and simply addresses our needs and allows for reusing the time groups while keeping the time condition separate. There is just one hiccup: said CEO does not like to be disturbed while he smokes his cigar’s and sips Chardonnay. He needs a simple way to be able to manually override the time conditions and send all his calls to voice mail. That’s what the "Day/Night Mode Association" option is for (assuming you have the day/night module installed). You can set a Day/Night Control with a "Night" destination of the CEO’s voicemail. When ever he needs to smoke his cigars, he can just dial his Day/Night control code – and all his call will be routed to his voicemail.

A more down-to-earth use of Day/Night mode association: just because you set your businesses time conditions, doesn’t meant that bad weather wont force you to close early. Use a Day/Night Control to set your business to go in to night mode early. Or have your receptionist do it – without needing to touch your delicate FreePBX gui!

The use of Day/Night controls are endless – and can introduce some form of dynamic call-flow control. What is your best/wildest implementation of Time Groups/Conditions? Lets hear about it in the comments!

Moshe Brevda, FreePBX Development Team
lazytt – FreePBX forums
hi365 – IRC

FreePBX 2.5.0 is FINAL!


It’s old news to the hundreds of you who beat me to the punch and already responded to those automated email notices telling you that FreePBX 2.5.0 has gone final! All of us who have contributed to the success of this release are thrilled to see it pass this great milestone and for those of you who will be at Astricon next week, I hope to see you at one of the parties to celebrate this great achievement!

Oh darn – got to buy a plane ticket for that don’t I, hmm, donation box is empty, feel free to help out. They are expecting me to give a talk this year…


With new features that span the spectrum of needs you are sure to find capabilities in 2.5 that you could not do or was much less convenient in previous releases. The list of features is too long to mention which is going to keep me really busy between now and October 7th preparing a new section for the upcoming Open Telephony Training Seminar covering this great milestone. (And don’t forget that special deal we mentioned last week which I think is about to expire!

Whether you want to do more with Queues (did you see Moshe’s great article yesterday?), take advantage of BLF, change your IVR messages on the fly with a feature code, simplify your current unmanageable chain of Time Conditions (and incorporate a manual override directly into the Time Condition), or a list of hundreds of other capabilities then you should be having a look at 2.5.

Want to write an article on something new with 2.5 that really peaks your interest? Contact me and we can make arrangements for you to publish something in the Technical Corner column, we would love to see more contributors there!

And as far as stability is concerned this release is panning out to over achieve our high standards once again! We’ve seen the normal pattern of other beta programs. People look for issues, and they find them, the majority of which are usually current bugs in the existing and often previous releases that have never been reported. More often then not, such bugs were only corrected in 2.5 and often will never be back ported to 2.4. So 2.5 is well worth looking at for the enhanced stability as well as all the great features it has to offer. With over 3000 systems in use at the time 2.5.0 went final, you can be confident that many other users have helped pave the way for you to feel comfortable upgrading and staring to explore the new capabilities of 2.5.

Now, with Astricon preparation in order for next week(if I can get there) and the next Open Telephony Training Seminar just around the corner, time to sign off with a thanks to all of you who helped develop, report bugs, provided great feature code ideas and patches and tested the early version prior to it going final!

– on behalf of the FeePBX team!

Queue weights vs. Queue priorities

FreePBX version 2.5 seems to be coming along real nicely and hopefully will be out of beta any day minute now, with way over 500(!) bug fixes and closed tickets, and an elephant load of cool new features. A big tip of the hat to Philippe Lindheimer, the FreePBX projects leader, under who’s leadership (and hard work) this great milestone has been achieved. The Chinese are fond of saying "An army of a thousand is easy to find, but, ah, how difficult to find a general." How true! Without Philippe’s guidance and unique vision of the project, it would probably long be covered in moldy green with every release bumping the bug to feature ratio by 3:.001. Thank you Philippe for making FreePBX what it is!

Lets have a look at two new cool features in FreePBX 2.5: Queue weights and Queue priorities. We’ll start with the Queue priorities module. Queue priorities essentially allows you to give a call a greater priority in a queue. Think of it as the First Class check-in counter – only your standing in the same line as the ‘commoners’. Once you mark a caller with higher priority, their position in the queue is automatically promoted – so that their call gets answered quicker than the others. To illustrate: if Jack is waiting in a queue with priority 1 and Jill comes along at priority 10 – who do you think is going to be answered first? Being that Jill is the holder of a First Class ticket – she will be answered first even if Jack is holding for a longer time! Neat, eh? Now add Jake, holding ‘only’ a business class ticket – say with priority 5, where will he go? Being that he is the second highest priority he will be second in our example – after Jill (10) but before Jack (0).

Queue weights does something similar only in reverse. It gives the queue a priority (called a weight) versus the other queues. If that sounds confusing, then try this: imagine, back to our airport, that instead of all the people standing at one check-in counter there are three counters – one for first class, one for business class, and one for the rest of us. Unfortunately, all the people that usually man the counters ran off to the OTTS, and only Sally stayed on to check in the passengers. So now we have people waiting in three different lines and Sally needs to decide whom to check in first. As I’m sure you guessed, Sally will first check-in those waiting at the first class counter as they have the highest weight, or importance to Sally and her self centered, money hungry, step-on-the-little-guys enterprise).

Another application of call weights (and I bet this one will hit a bit closer to home): the small business. I’m talking about the (more or less) one man business where the sales guy is also the janitor, the CEO is also the secretary, and the technician is also the delivery man. And all three are one and the same guy. But in order to give the big company appearance, you set up a PBX with fancyshmancy stuff like ivr’s and queues and music on hold. (Yes you! C’mon, don’t look at me like that – you know that’s what got the geek in you attracted to asterisk in the first place…). Anyway so your sales/management/technical/maintenance/logistic team (aka you) have all your phone(s) logged in to the different queues. Obviously its business (sales) before pleasure (nothing like pulling an allnighter trying to fiddle with that new linux app that you got off some guy on IRC, trying to impress an old client), and you want to receive the calls in the sales queue before those in the technical assistance queue. This is where call weights comes in to the picture: you can set the weight of the sales queue to be higher than that of the technical support queue, and, like the magic that asterisk is, callers in the sales queue will always come out ahead of the callers in the technical queue (you should of never logged in to that one to begin with anyway – its usually full of annoying clients who need help after trying to "fix" their system).

Truth is, in that last example, you could do exactly the same thing with queue priorities – give the people calling for sales a higher priority (vs. giving the queue a higher weight). But being the geek that you are, you want to impress your family and friends’ clients by announcing their estimated hold time – and position in the queue. Now what happens if you have a caller that was already told that they are next in line and someone with a higher priority call comes in? You guessed it – grandma gets pushed to the back of line in favor of your basket-ball buddy! Granny will be kinda pissed when she hears that she is now number two in the queue. So you need to know you environment before deciding which strategies to take.

That’s not to say that Queue Priorities doesn’t have merits of its own. When that little mom and pop, garage based business grows up and becomes Google or HP (hey – you can do it!) and you have a large call center with different departments, there will often be a situation where after talking to someone in department X the caller will be transferred over to someone in department Y. But being that they already waited in the queue for dept. X its only fair that they shouldn’t have to wait again. This is a very practical application of Queue Priorities: the guy in dept. X transfers the caller to a destination that sets their priority higher in the Y queue, so that they get answered right away, and don’t have to wait again.

Two more points: you might be wondering what happens when two or more callers enter a queue at a higher priority? All the people at a given priority get treated just like people usually get treated in a queue, first come first server (fifo), so that all the people at, say, priority 10 will have their calls answered (again fifo), and then people at priority 5, and so on. Last but not least, we previously mentioned the lines at the airport. In the UK people call those a queue (as in "I’m standing in the queue"). But you already knew that.

Moshe Brevda, FreePBX Development Team
lazytt – FreePBX forums
hi365 – IRC

MAJOR ANNOUNCEMENT: Asterisk Speech Recognition Magic Button

If you have already heard about the Magic Button, read on because the feature set has expanded by a factor of five. This post is to inform the community about the upcoming community release of the Magic Button software, as well as the upcoming availability of the new LumenVox Community Speech Licensing Server.

The formal announcement, live demonstration (always interesting demonstration speech applications on a speaker phone with a microphone held up to the speaker) and details will be presented in Vegas in a week-and-a-half. If you are with the press and are interested in attending the event to see the Magic Button in action or would like to schedule an interview, please email me directly at ethan.schroeder at schmoozecom dott com.

For an audio (MP3) introduction to the Magic Button, visit http://schmoozecom.blogspot.com/

The Magic Button is an extensive speech recognition call management tool built on Asterisk and LumenVox speech recognition technology. It allows users to control their PBX experience with nothing more than their voice.

Welcome to a brand new way to communicate. With the touch of the Magic Button, you can use your voice to control calls, set your away status, send and receive messages, call and page groups of people in your organization, and even ask what the date, time or weather is!

You can initiate conversations with people in your organization, your customers or any telephone number. Just say “call John Smith”, “call extension one zero zero one”, “call extension one thousand one”, “call 5-5-5-1-2-3-4”, “call one-eight-hundred-5-5-5-1-2-3-4”, “Intercom John Smith”, or “Intercom Extension 1-0-0-1”.

When you are on the phone with someone else, you can say things like “transfer to John Smith”, “transfer to extension 1-0-0-1”, “transfer to John Smith’s voicemail” or “park call”. Call parking allows you to put a caller on hold and pick that caller up from any phone in your organization. After parking a call, you will be told the parking slot the caller is in. If you forgot the parking slot, you can retrieve a list of parked calls by saying “list parked calls”. If you or someone else parked a caller in slot seventy-one, you or anyone else in your organization could say “retrieve call seven one” or “retrieve call seventy one” and be immediately connected to that caller.

In addition, you can interact with call groups (ring groups), page groups, and voicemail blast groups. You can say “what groups can I page?”, “what groups can I call?”, or “what voicemail blast groups are there?”. Depending on the groups setup on your system, you can say things like “page all”, “page warehouse”, “call group sales”, or “leave a message for group sales”.

Checking your voicemail has never been easier now that there is the Magic Button. Just say “check messages” and you can login and check your messages with your voice, including having the options of listening to messages, moving messages, deleting messages, and even fast-forwarding and rewinding messages by saying “fast forward” and “rewind”. Additionally you can setup your voicemail by saying “record my name”, “record my greeting”, or “record my temporary greeting”. Finally, you can leave messages for other people by saying things like “leave a message for John Smith.”

Controlling your phone calls is easy with the Magic Button. You can tell the Magic Button your home or mobile telephone number and instantly forward your calls when you are away. Say “set my home phone number to 5-5-5-1-2-3-4” or “set my mobile number 5-5-5-1-2-3-4”. You will then be able to say “forward my calls to my home phone” or “forward my calls to my cell phone”. Additionally, you can forward your calls to any extension or external phone number by saying “forward my calls to extension one-thousand-one” or “forward my calls to 5-5-5-1-2-3-4”. To turn off call forwarding, just say “disable call forwarding”. Don’t want to be disturbed? Just say “enable do not disturb” and your phone won’t ring. When you are ready to take calls again say “disable do not disturb.”

Information is always just a finger press away with the Magic Button. Say “What time is it?”, “What is the date?”, or “What is the weather like?”

Out of the office? No problem. With the Magic Button, you can assign a special inbound DID phone number or hidden IVR option to allow employees access to all Magic Button functionality on the road. Users login with their extension and voicemail password (using their voice), and become their extension and have full access to all Magic Button functionality.

You can control your away status and even find out where other people in your organization are. If you are going to lunch, just push the Magic Button and say “I’m at lunch”. The Magic Button will prompt you if you would like to set a return time and record a temporary away message. Likewise, you can say “I’m away”, “I’m in a meeting” or “I’m out of town”. When you are back, just say “I’m back”. Asking “where is John Smith?” will tell you if John Smith has set an away status. If John Smith is away, you will be prompted with the option to be notified when John Smith is back. As soon as John Smith is back you will be paged and notified that John Smith is back and have the option of connecting to John Smith.

Finally, the ability to import your Microsoft Exchange contacts is completed and in beta testing. Just say “import my contacts” and now you can call people in your contact list! It is tested and working on Exchange 2003 and Exchange 2007 (should work on Exchange 2000, as well)

One of the biggest hurdles to bringing speech recognition capabilities to small and medium business has traditionally been the cost of speech recognition ports on a phone system. In order to ensure non-blocking of service, you need to purchase enough speech ports to supply total possible concurrency. This would easily add 25% to the total cost of the solution to the customer. Initial cost is an issue no more! Through an arrangement between FreePBX, Schmooze Communications, Digium, and LumenVox, we are announcing a Community Speech Licensing Server. By pooling together hundreds (and eventually thousands) of licenses, we are able to provide speech recognition capabilities on an unlimited, non-blocking port model at low monthly per-PBX fees, while providing the rich applications like the Magic Button, voice-enabled company directory and voice-enabled auto-attendants (IVRs) as part of a low monthly service fee for access to the Speech Licensing Server.

How low? How about $5-$50/month low, depending on the size of the PBX? Now we’re talking speech recognition that is affordable to any PBX customer.

Your commitment to the Community Speech Licenseing Server also helps the FreePBX project, as Philippe has partnered with us to bring you this and future speech-driven applications that are easy to configure via the FreePBX interface.

More details and an audio introduction are available on the blog at http://schmoozecom.blogspot.com