Introducing Nerd Vittles Phone Genie for Asterisk

Ever left your home or office and wished you had transferred your calls to your cellphone before you departed. Unless you've done a good bit of design work on your Asterisk® PBX or paid Ma Bell half your monthly paycheck, you're probably S.O.L. until you return to home base. Well, at least until today. Today we introduce version 1.0 of Phone Genie for Asterisk, an all-purpose web utility that lets you reconfigure virtually anything and everything on your Asterisk system on the fly using an incredibly powerful HTML command language that you can master in a matter of minutes. All you'll need is a web browser including most cellphone web browsers as well. And, of course, it's free.

The easiest way to explain how powerful Phone Genie for Asterisk really can be is to give a few examples. So, let's assume you've registered a fully-qualified domain name for your Asterisk server using a free service such as DynDNS.org. Let's use asterisk.dydns.org in our example. Now you're on the road and want to forward calls from extension 200 on your PBX in a Flash system to your cellphone: 678-234-5678. All you need to do is open the browser on your cellphone or any desktop PC and enter the following web address:

If you're new to Asterisk, a few hints may be in order. What the Nerd Vittles' Phone Genie does is provide a web interface to the complete Asterisk Manager API. If you also happen to be using the Asterisk Management Portal or freePBX, then the sky's the limit since there are dozens of functions you can execute by simply manipulating data stored in Asterisk's internal database. We'll give you some examples today, and add many more in the coming weeks and months. For today, you'll have to settle for the Phone Genie Starter Kit with three critical Asterisk Manager tools. These three tools give you complete control over Asterisk's internal database: dbget to query the Asterisk internal database, dbput to add and update information in the database, and dbdel to delete records from the database. For the Asterisk whiz kids out there, you're probably chuckling that there's no such command as dbdel in the Asterisk Manager API. And you'd be right, but now there is... at least with the Nerd Vittles Phone Genie.

Do you have to be a whiz kid to use the Phone Genie? Not at all. In fact, all you really need to do is download the application into the default web directory on your Asterisk, PBX in a Flash, trixbox, or Asterisk@Home web server, and keep reading. We've tested Phone Genie with versions of Asterisk@Home dating back to 2.8, and it works perfectly with PBX in a Flash.

Installation and Setup. To begin, you'll need to download the Phone Genie application and set up a very secure password. Why? Because anyone with the web site address of your Asterisk server and access to this application could trash your Asterisk system faster than you can mutter "Genie in a Bottle." So log into your PBX in a Flash server as root and issue these commands:

cd /var/www/html
wget http://nerdvittles.com/trixbox123/phonegenie.zip
unzip phonegenie.zip
rm -f phonegenie.zip
chown asterisk:asterisk nv-genie.php
chmod +x nv-genie.php

Once the application is in place, you need to edit the file and change the default password to something secure: nano -w nv-genie.php. On line 2 of the file, change 1234 to a numeric value that only you know! Do NOT include non-numeric characters or PHP will reset your password to zero... which isn't that secure. You shouldn't have to change anything else in the file unless you've "improved" the account name and password used to access your Asterisk Manager API in /etc/asterisk/manager.conf. This Manager password is more secure than it appears because it only works from 127.0.0.1, i.e. localhost. So, without adding another entry in this file, you could not run this application from a web server that's different than your Asterisk server.

Getting Started with Call Forwarding. Now that everything's installed and configured, it's time for a test run. For this to work, you'll need a fairly recent version of Asterisk@Home or TrixBox with AMP or freePBX since we'll be using freePBX functions. If you're going to access the Phone Genie application from inside your firewall where your Asterisk server also resides, then you'll need the internal IP address of your Asterisk server. Otherwise, you'll need to configure your firewall to forward port 80 HTTP traffic to the internal IP address of your Asterisk server. And you'll need either the external IP address of your Asterisk system or the fully-qualified domain name for your system. Next, you'll need an extension number on your Asterisk system that we can experiment with. If you want to be able to forward incoming calls back out to your cellphone, then you'll need at least two trunks. The DID trunk handles the incoming call, and a termination trunk will actually forward the inbound call back out to your cell. We'll also need the phone number of your cellphone in the same format that you would dial it on your Asterisk PBX. For example, if a prefix of 1 is required to call outside your PBX, then the number would look like this: 16782345678.

Once you have all the pieces of information, open a web browser and issue a command that looks something like this for a web browser inside your firewall. Otherwise, follow the sample above.

NOTE: All database entries are case-sensitive so be sure you use the family name exactly as it should appear in your database. FreePBX uses CF in ALL CAPS for the call forwarding family of data.

Substitute your own internal or external address for 192.168.0.123. To forward a call, we'll use the freePBX CF function and we'll use dbput to put the information in Asterisk's internal database. Use your real extension number instead of 200. This becomes the key in Asterisk database lingo. Substitute your properly formatted cellphone number for 6782345678. And replace 1234 with the password you stored in the nv-genie.php file. This becomes the value for the call forwarding key 200. Once you get this working either internally or externally on your cellphone, you can save your entry as a favorite in your browser and forward calls at any time with one click!

In addition to a confirmation message, you can check your work in a couple other ways. You can obviously call the extension and see if it forwards the call to your cellphone. You also can query the Asterisk database using Phone Genie. The syntax for a query is almost identical to a dbput command except you don't need to include a value. Here's what it would look like for a query from your cell phone browser:

When you return to home base and want to cancel the call forwarding, you can either pick up the extension you forwarded and dial *73 or you can use Phone Genie's dbdel function. This also can be saved as a favorite so that it's one click away when you need it.

<sermon> It goes without saying, but we'll say it anyway. Don't start randomly using dbdel to delete stuff out of the Asterisk internal database or you'll find yourelf with a whirring boat anchor in a matter of minutes. Both Asterisk and FreePBX rely upon database entries to function at all. Rule #1: If in doubt, leave it alone! <end of sermon>

What Else Can Phone Genie Do? We've barely scratched the surface of what lies ahead. For a list of database entries that you can query, manipulate, and delete, open the Asterisk CLI after logging into your server as root: asterisk -rvvvvv. Now issue the following command: database show. In the listing, you'll see some entries that look like this: /CALLTRACE/502 : 500 . Call Trace is a database family that keeps track of the number that last called a particular extension. In this example, extension 502 was called by extension 500. An easy way to figure this out when you're on the road would be to issue a query using the Phone Genie:

Asterisk Database Display. There may be times when you just want to review a group of settings in your Asterisk database or even the entire database without having to start up a CLI session. The dbshow action in Phone Genie provides this functionality. In its simplest form, the command looks like the following to display your entire Asterisk database:

If you'd prefer to display only a single family of entries in the database, then the syntax looks like this:

That's about it for today. We'll leave you with a partial list of freePBX functions that can be controlled from within Phone Genie. We'll cover other things you can do with the Asterisk Manager and Phone Genie in a future article. If you're in a hurry to add some additional functions and you speak PHP, please feel free to add away. Send us your additions and we'll include them in the next version. Enjoy!

Dialcode: *72

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=CF&key=200&value=6782345678&pw=1234

Dialcode: *73

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=CF&key=200&pw=1234

Dialcode: *90

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=CFB&key=200&value=6782345678&pw=1234

Dialcode: *91

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=CFB&key=200&pw=1234

Dialcode: *52

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=CFU&key=200&value=6782345678&pw=1234

Dialcode: *53

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=CFU&key=200&pw=1234

Dialcode: *69

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbget&family=CALLTRACE&key=200&pw=1234

Dialcode: *70

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=CW&key=200&value=ENABLED&pw=1234

Dialcode: *71

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=CW&key=200&pw=1234

Dialcode: *78

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=DND&key=200&value=YES&pw=1234

Dialcode: *79

Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=DND&key=200&pw=1234

NOTE: The Best of Nerd Vittles tutorial on Phone Genie for Asterisk covers all updates and new features.

Nerd Vittles Demo Hot Line (courtesy of les.net). You now can take a number of Nerd Vittles projects for a test drive... by phone! The current demos include (1) MailCall for Asterisk with password 1111 (retrieve your email by phone), (2) NewsClips for Asterisk (latest news headlines in dozens of categories), (3) Weather Forecasts by U.S. Airport Code, and (4) Weather Forecasts by U.S. ZIP Code. You're not prompted for #4 yet, but it does work! Just call our number (shown in the left margin) and take any or all of them for a spin. The sound quality may not be perfect due to performance limitations of our ancient Intel 386 demo machine. But the price is right.

Nerd Vittles Fan Club Map. Thanks for visiting! We hope you'll take a second and add yourself to our Frappr World Map compliments of Google. In making your entry, you can choose an icon: guy, gal, nerd, or geek. For those that don't know the difference in the last two, here's the best definition we've found: "a nerd is very similar to a geek, but with more RAM and a faster modem." We're always looking for the best BBQ joints on the planet. So, if you know of one, add it to the map while you're visiting as well.

Some Recent Nerd Vittles Articles of Interest...