FreePBX is the most popular open source IP-PBX solution that is based on Asterisk, another popular open source telephony system.
FreePBX has a modular architecture and its GUI provides about 80% configuration of Asterisk. Although with commercial modules, it can be a UC solution not just an IPPBX or phone system.
Despite all of these great features, this is usual that users need to do something with the calls that is not possible with standard modules. In this case, users have to play a little with Asterisk dialplan and customize it; the engine of its call routing!
In the following, we will cover the most common solutions for FreePBX dial plan customization.
Custom Destinations
If you want to direct a call through the system to a specific destination with custom dialplan, you can do it via a Custom Destination.
For example, with using two APIs, the icanhazdadjoke.com to get the text of a joke, and the Voip Innovations apidaze API to send the content of that joke out via SMS. At the first step, we should create the example dialplan in the /etc/asterisk/extensions_custom.conf:
[randomjoke-sms]
exten => s,1,Noop(Entering user defined context randomjoke-sms in extensions_custom.conf)
exten => s,n,Set(apidaze_key=xxxxxxxxx) ; get from APIDAZE Dev App
exten => s,n,Set(apidaze_secret=xxxxxxxxxxxxxxx); get from APIDAZE Dev App
exten => s,n,Set(from_DID=xxxxxxxxx) ; DID associated with APIDAZE App
exten => s,n,Set(destination=${CALLERID(number)})
; set headers and curl for corny joke
exten => s,n,set(CURLOPT(httpheader)=Accept:text/plain)
exten => s,n,set(CURLOPT(httpheader)=User-Agent:Asterisk-FreePBX-joke2SMS)
exten => s,n,set(joke=${URIENCODE(${CURL(https://icanhazdadjoke.com)})}) ; make API call and encode it. Content returned with a <CR> is a problem
exten => s,n,set(joke=${URIDECODE(${STRREPLACE(joke,%0A,%20)})}) ; filter out <CR> by replacing with a space character
;send the joke to the caller’s CallerID number via SMS using Voip Innovations api-daze API
exten=>s,n,set(result=${CURL(https://api.apidaze.io/${apidaze_key}/sms/send?api_secret=${apidaze_secret},from=${from_DID}&to=${destination}&body=${joke})})
exten => s,n,Return ; end the custom destination context with a return application
You can add this piece of dialplan to extensions_custom.conf through the GUI:
Admin → Config Edit
Then in the next step, create a Custom Destination with a GoSub string of:
randomjoke-sms,s,1
And enable the Return option. Choose the destination for the call and submit.
So, you just need to route your specific calls to this custom destination.
Preprocess Inbound Calls
In some cases you need to apply a user defined custom dialplan to an inbound call before it reaches your FreePBX Inbound routes. The easiest way is creating your context in the /etc/asterisk/extensions_custom.conf. For example:
[from-trunk-preprocess] ; context name is arbitrary
; Characters that follow a ; are for commenting
exten => _.,1,Noop(Entering user defined context from-trunk-preprocess in extensions_custom.conf)
exten=> _.,n,Verbose(0,Caller ID: ${CALLERID(name)}) ; doesn’t do much, just logs the Caller ID name
; Add whatever others you need
exten => _.,n,Goto(from-trunk,${EXTEN},1) ; context must end with at goto the from-trunk context
; end of from-trunk-preprocess
With the context created in /etc/asterisk/extensions_custom.conf, now edit your FreePBX trunk(s) in the GUI and change the context to the name you used above, in this case ‘from-trunk-preprocess`. Submit and apply config, and all inbound calls on those trunks will first use the preprocess context before going to the Inbound Routes (from-trunk).
Custom Feature Code Prefix
In some cases you need to do something before dialing an internal extension. To create a dial prefix, use code similar to the following and add it to the /etc/asterisk/extensions_custom.conf :
[from-internal-custom]
exten => _**XXX*XXXX,1,Noop(Entering user defined context from-internal-custom in extensions_custom.conf)
exten => _**XXX*XXXX,n,Noop(ext: ${EXTEN:-4} delay: ${EXTEN:2:3})
exten => _**XXX*XXXX,n,Wait(${EXTEN:2:3})
exten => _**XXX*XXXX,n,goto(from-internal,${EXTEN:-4},1)
Once the dialplan has been reloaded (apply config), dialing “**015*1004” will allow the system to dial extension 1004 with a 15 second delay before dialing.
Dialplan Hook for Outbound Calls
If you want to perform an action on all outbound calls like changing the caller id or a SIP header value, you can use a dialplan hook macro similar to this in the /etc/asterisk/extensions_custom.conf:
[macro-dialout-trunk-predial-hook]
exten => s,1,Noop(Entering user defined context macro-dialout-trunk-predial-hook in extensions_custom.conf)
; Add whatever others you need
exten => s,n,MacroExit
Please note this macro would be called when you are using outbound routes! If you route calls directly to the trunk(s), you should use previous methods for dialplan customization.