Ward Mundy's Technobabblelog

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:

http://asterisk.dyndns.org/nv-genie.php?action=dbshow&pw=1234

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!

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.

Nifty idea, there. Given that your hack encodes all the information in the URL, it would be pretty trivial to setup some other interactions with the Asterisk database. For example, Snom phones have an “Action URL” which can be assigned to a button. Many companies aren’t crazy about the idea of time conditions controlling how incoming calls are handled, and if they go to a Ring Group or IVR, it’s tricky to just use *72 forwarding since you really want to change the ring group or ivr, not your individual extension. Your Genie could certainly take control over those as well. I dig it! My customers who like their legacy systems and manual control will appreciate this very much.

– Jason

[WM: Good point. Cisco phones could also do something similar assuming you could ever find a version of their SIP software where the web stuff actually works.]

Thank you for this group of functions. They work very well. I’m actually working on getting this into trixbox. I have one comment/question:
Any ideas on how to make the scripts respond a little quicker? I’m working out a strategy using xajax. Peace.

Version 1.1 was released today. In addition to the admin password, it provides individual password support for every extension on your Asterisk system. For those with security concerns, this greatly reduces your exposure to damage over the Internet. Using an extension password, a user can only execute commands pertaining to the individual user’s extension. For complete documentation, read the Best of Nerd Vittles writeup on Phone Genie 1.1.

Version 1.2 is now available with full support for every Asterisk CLI command. Just download the application again and replace the original. Complete documentation on the new feature set is available at the Best of Nerd Vittles.

All is very nice and well. Just one thing is missing: I would like to use the web interface for calling and receiving calls fromm my Asterisk PBX rather than to use a softphone..is it possible to add to that application?
It may be of use when using a PDA or Symbian based web smartphones without installing a softphone.

This is great! And I am totally on the same track as Jalapeno. As a quick test, I changed the action URL of the DND button… I just wish there was a more comprehensive list of things we could do with the Phone Genie…

Excellent: I have about 40 snom phones setup and will use the action url settings in SNOM administration to set DND in asterisk as well as at the phone. This will allow the salesman to ‘Turn Off’ the follow me function when in meetings or on holidays.

It works by writing a value to the asterisk database. I modified this a lot for my needs, and then I remembered that the Phone Genie can access the database remotely. So now I can lock and unlock extensions remotely rather than by keying in a feature code directly on the phone. And it works in parallel with the local application, so a phone can be locked locally and unlocked remotely and vice-versa.
Thanks, Ward!