Adding Post-Dial Processing to Asterisk and FreePBX Dialplans

Last week we introduced a couple of new free calling options for Asterisk®: ENUM and Gizmo5's Backdoor Dialing. But one of the limitations of the Gizmo5 service in particular was the need for a 0101 prefix in order to trigger a free call as opposed to a pay per minute call to the same number. This highlighted a pretty serious limitation in the way FreePBX processes most outbound calls. As we indicated, the process goes something like this. After a caller dials a number, FreePBX searches through its Outbound Routes (from top to bottom) looking for a match on the dial string. Once it finds one, FreePBX then initiates calls beginning with the first trunk in the trunk priorities list for that outbound route. If the call is completed, no further call processing takes place. And a completed call includes a call that is either answered or rings busy. If a call is not completed, FreePBX continues to drop down the available trunks list and repeats the process until a call is either completed or the trunk list is exhausted. The one exception to this scenario was support for ENUM. In that situation, a lookup occurs after a call is dialed to see if it can be placed as a free SIP call. We'd like to do the same thing with Gizmo5's Backdoor Dialing. What we want to do is query the Gizmo5 database to determine whether a number to be called is a free call. If it is, then we want to modify the route for processing the outbound call to take advantage of Gizmo5's free calling option. And we'll also need to change the phone number by adding a 0101 prefix.

Since our last column, another serious limitation in FreePBX post-call processing was mentioned on the PBX in a Flash Forums. With a number of commercial PBXs, it's possible to specify post-dial processing for emergency calls. For example, in an office environment, if an employee dialed 911, it would be helpful to alert a receptionist in some way so that immediate first aid could be attempted and also to give the receptionist a heads up so that he or she could direct emergency responders to the appropriate location in a building. As written, FreePBX doesn't provide an easy way to handle this.

So our objective today is to provide a couple applications which address these limitations. And the apps also will document a methodology for overcoming other post-dial processing issues which may arise using the existing FreePBX framework.

The trick to adding today's hooks into the Asterisk dialplan is to understand that Asterisk loads identically named dialplan contexts only once. Taking advantage of this, FreePBX provides a mechanism for users to insert custom code to replace default FreePBX contexts. All of these configuration files are stored in /etc/asterisk. For today, the context we want to modify is [macro-dialout-trunk]. This is the FreePBX macro that does the heavy lifting once a call has been placed and a trunk route has been selected to handle the call. With FreePBX 2.3, the macro is in extensions.conf. In FreePBX 2.4 and 2.5, the context is in extensions_additional.conf. In both cases, what we want to do is copy the entire contents of the existing context into the bottom of extensions_override_freepbx.conf. If you're using an editor to cut-and-paste the code, be sure you get the code that is located outside the left and right margins of your editor. And the context ends on the line before the next context begins. In the case of FreePBX 2.3, the next context is [macro-agent-add]. In the case of FreePBX 2.4, the next context is [macro-dialout-dundi]. And, in 2.4, there is now a comment which indicates where each context ends: ; end of [macro-dialout-trunk].

What we want to do is insert a line or two of custom code in this context which you've copied into extensions_override_freepbx.conf. The purpose is to run our custom code after the number to dial and trunk ID have been passed to this macro. Then, in the case of the Gizmo5 application, we'll run out to the Internet to determine if this call should be handled as a free call. If so, we'll change the trunk ID number to match your Gizmo5 trunk, and we'll change the number to dial by prefixing the existing number with 0101. The only gotcha with the Gizmo5 Backdoor Dialing is that every number must be tested at least once by someone (not necessarily you) in order to populate the Gizmo5 free calling database. You can check as many numbers as you like at this link. In the case of our 911 emergency application, we'll check to see if the number being dialed is 911. If so, we'll send an email or text message to an address that you define with an alert that extension 1234 just placed a call for emergency assistance to 911.

If you're using FreePBX 2.3, the custom code below should be inserted after the third "exten" line in the context, i.e. after the following line of code:

exten => s,n,Set(ROUTE_PASSWD=${ARG3})


If you're using FreePBX 2.4, the custom code below should be inserted after the first "exten" line, i.e. after the following code:

exten => s,1,Set(DIAL_TRUNK=${ARG1})


And the code to be inserted looks like this for Asterisk 1.4:

exten => s,n,AGI(nv-outbound.php|${ARG2}|${ARG1})
exten => s,n,AGI(nv-gizmo.php|${ARG2}|${ARG1})


For Asterisk 1.6, it should look like this:

exten => s,n,AGI(nv-outbound.php,${ARG2},${ARG1})
exten => s,n,AGI(nv-gizmo.php,${ARG2},${ARG1})


Now we need to add a couple of PHP scripts to your system and set a few configuration options, and you'll be ready to go. While logged into your server as root, issue the following commands:

cd /var/lib/asterisk/agi-bin
wget http://pbxinaflash.net/source/gizmo/nv-gizmo.zip
unzip nv-gizmo.zip
rm nv-gizmo.zip
wget http://pbxinaflash.net/source/gizmo/nv-outbound.zip
unzip nv-outbound.zip
rm nv-outbound.zip
chown asterisk:asterisk *.php
chmod +x *.php
asterisk -rx "dialplan reload"
grep OUT_ /etc/asterisk/extensions_add* | awk '/ = / { print $0 }'


The last line of code above is used to decipher the trunk numbers associated with each of your trunks. What we need to know is the trunk number for the Gizmo5 trunk that you set up in last week's tutorial. Write it down and then edit nv-gizmo.php: nano -w nv-gizmo.php. Look down the screen about 5 or 6 lines for the line that reads $GIZMO_TRUNK = "21" ; and replace 21 with the number you wrote down for your actual Gizmo5 trunk. In the next two lines, insert your actual Gizmo5 username and password between the quotation marks. Don't change anything else. Save your changes: Ctrl-X, Y, and then press the Enter key.

With the other application, nv-outbound.php, we need to be sure it's working with your phone system before you actually need it. And we don't place test calls to 911. So here's the drill. Edit the file: nano -w nv-outbound.php and insert your email address or text message address in the $email variable between the quotes. Then move to the next line and insert a telephone number with the area code that you can dial from a phone on your system to test that the notification is working. For example, put in your cell phone number. Once you save your changes, pick up a phone on your system and call your cellphone. You should receive an email notification within a few seconds. Once it's working, edit the application again and change the $number2monitor to "911" and you're all set. Enjoy!

VPN in a Flash Update! We've had over 100 reservations for our new VPN in a Flash system. We're very close to having a manufacturer in place so hopefully we'll have more good news in a week or two. We have begun the documentation for the new product, and we encourage you to take a look and offer any questions or comments you may have on our forums. The documentation is in the new Google Knol format and can be reviewed here. It's not too late to get in the queue and place a reservation for a system. Just send us a note, and we'll keep you posted as the release date approaches. It'll hold your place in line with absolutely no obligation to purchase.

Coming Attractions. We're very close to signing on a new VoIP provider for PBX in a Flash users that will provide penny-a-minute calls in the U.S. and Canada as well as all-you-can-eat plans for just over $10 a month with an annual contract. We're also only a week or two away from a new version of AsteriDex with Outlook synchronization and a TTS dialer for AsteriDex queries from any connected Asterisk phone. Stay tuned!

Hosting Provider Deal of the Century. Just an FYI that the Nerd Vittles hosting provider, BlueHost, has raised the bar again on hosting services. For $6.95 a month, you can host unlimited domains with unlimited web hosting disk storage and unlimited monthly bandwidth. Free domain registration is included for as long as you have an account. It really doesn't get any better than that. And their hosting services are flawless! Just use our link. You get a terrific hosting service, and we get a little lunch money.

Special Thanks to Our Generous Sponsors

FULL DISCLOSURE: ClearlyIP, Skyetel, Vitelity, DigitalOcean, Vultr, VoIP.ms, 3CX, Sangoma, TelecomsXchange and VitalPBX have provided financial support to Nerd Vittles and our open source projects through advertising, referral revenue, and/or merchandise. As an Amazon Associate and Best Buy Affiliate, we also earn from qualifying purchases. We’ve chosen these providers not the other way around. Our decisions are based upon their corporate reputation and the quality of their offerings and pricing. Our recommendations regarding technology are reached without regard to financial compensation except in situations in which comparable products at comparable pricing are available from multiple sources. In this limited case, we support our sponsors because our sponsors support us.

BOGO Bonaza: Enjoy state-of-the-art VoIP service with a $10 credit and half-price SIP service on up to $500 of Skyetel trunking with free number porting when you fund your Skyetel account. No limits on number of simultaneous calls. Quadruple data center redundancy. $25 monthly minimum spend required. Tutorial and sign up details are here.

The lynchpin of Incredible PBX 2020 and beyond is ClearlyIP components which bring management of FreePBX modules and SIP phone integration to a level never before available with any other Asterisk distribution. And now you can configure and reconfigure your new Incredible PBX phones from the convenience of the Incredible PBX GUI.

VitalPBX is perhaps the fastest-growing PBX offering based upon Asterisk with an installed presence in more than 100 countries worldwide. VitalPBX has generously provided a customized White Label version of Incredible PBX tailored for use with all Incredible PBX and VitalPBX custom applications. Follow this link for a free test drive!
 

Special Thanks to Vitelity. Vitelity is now Voyant Communications and has halted new registrations for the time being. Our special thanks to Vitelity for their unwavering financial support over many years and to the many Nerd Vittles readers who continue to enjoy the benefits of their service offerings. We will keep everyone posted on further developments.
 

Some Recent Nerd Vittles Articles of Interest...