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

Share this Blogpost

Start the Discussion

Sign up for our Newsletter

Scroll to Top