Introducing AsteriDex III: A Web-Based Robodialer for Asterisk and Trixbox

It's another free software day at Nerd Vittles, and we have the third generation of our Asterisk® database dialer utility for you. The original AsteriDex was a web-based AutoDialer on Steroids. It let you store and manage phone numbers of all your friends and business associates with an easy-to-use MySQL database. Then you could call up the application in your favorite web browser from anywhere and click on the contact you wanted to call, and Presto! AsteriDex first called you at the number you designated for this contact, and then AsteriDex connected you to your contact through an outbound call made using your Asterisk server.

For those lucky enough to have GrandStream's GXP-2000 IP phone with AutoAnswer, you could even configure AsteriDex to automatically activate the speakerphone and then place the call to the contact you selected. In short, the original worked much like Microsoft's TAPI software without the configuration nightmare or your favorite (required) Micro$oft bloatware. Installation and configuration for your Asterisk@Home system was a snap and took less than 10 minutes. It also worked with vanilla Asterisk running the Asterisk Management Panel (AMP) software. AsteriDex was quick to implement and simple to use because it only did one thing, but did it well. The AsteriDex autodialer placed calls to all your favorite callees using a web interface.

Version Two added two new features. First, you could use AsteriDex to automatically look up CallerID Names in your MySQL database for all your incoming calls. And, second, you could dial a person in your database by spelling up to five characters of the person's name using any phone in your home or office, and AsteriDex automatically placed the call for you just as if you'd use the web browser interface. To use this feature, you just dialed 00 plus the one to five-digit code of the person to call. In Version Three, we've cleaned things up a bit more. The web interface now displays contact phone numbers and speed dial numbers regardless of whether you're using Internet Explorer, Firefox, or Safari. The speed dialer now tells you who's being called using the Flite speech synthesis engine built into every new (free) TrixBox server. And, last but not least, we'll show you how to install AsteriDex for multiple people in your home or office.

In case you're wondering, "Can you do the same thing with SugarCRM?" Well, sorta but not really. If you need full-blown contact management, then SugarCRM may be your thing. Just don't expect it to be a weekend project. CRM is really for folks whose lifeblood is contact management. If that's you, great! But for the rest of us that just wanted a phone and web-based autodialer that's simple to set up and easy to use, AsteriDex is just the ticket. You can add a contact to AsteriDex in under 10 seconds. You can delete one faster than that. And making changes to existing entries is a breeze as well. So let's get started.

AsteriDex Overview. Here's a brief overview of how all this works and the installation process. Then we'll install the pieces. How does it work? It's simple. When you call up the web application, you're presented with a tabbed and alphabetized listing of all your friends and business associates. You add the names and phone numbers of friends and business associates to a MySQL database table on your Asterisk machine. We'll show you how, and we've even provided the names and numbers of some of your favorite airlines to get you started. For each entry, you specify not only the phone number of the contact but also your phone number for placing calls to this party. You can also tell it to use a default phone extension for outbound calls. When you click on someone's name in the web application, AsteriDex swings into action and places two calls. First, it calls you at the number you've designated. When you answer or your answering machine does, AsteriDex places a second call to the person or business you selected. It then joins the two calls together, and presto: a phone conversation is born. It works exactly the same way with the phone-initiated speed dialer. Just dial 00 and then up to five characters of your friend's name to place a call. And, in our next column, we'll wrestle with CallerID enhancements for TrixBox and show you how to configure AsteriDex and TrixBox to display a matching CallerID Name out of your customized database.

To install AsteriDex, we'll first download the software. Then, we'll walk you through the two-minute drill to configure the app to meet your own requirements. Next, we'll put the pieces in the right places on your Asterisk server. And finally, we'll crank up AsteriDex and make a test call.

Securing AsteriDex. If AsteriDex came preinstalled on your TrixBox system, there may be a security vulnerability. Just to make sure your system is protected, download and install this simple patch. Log into your Asterisk server as root and issue the following commands:

cd /var/www/html/asteridex
rm -f callboth.php
wget http://nerdvittles.com/trixbox11/callboth.zip
unzip callboth.zip
rm -f callboth.zip
chown asterisk:asterisk callboth.php
chmod 775 callboth.php


AsteriDex Prerequisites. To make all this work, we recommend you install TrixBox using our soup-to-nuts tutorial. It won't cost you a dime if you have an old clunker PC lying around. Otherwise, you'll need to install Flite, freePBX, the Apache web server with PHP, phpMyAdmin, and MySQL support on your Asterisk machine. Also make certain that your Asterisk server is secure before exposing your web server to the Big Bad Internet. You can read all about it here. Finally, we recommend using an SSH client and/or a secure FTP client to load and configure stuff on your Asterisk machine unless you just like sitting in front of your server. SSH comes with every Mac and the syntax is simple: ssh root@AsteriskIPaddress. If you're still chained to Microsoft, download Putty from the Mother Country, and you can do the same thing using any Windows machine.

Downloading AsteriDex. Step 1 is to download the application, and you can do that by clicking here. We've packaged AsteriDex in a ZIP file so save it to your Desktop and unzip the file so you can get to the asteridex folder. If you're upgrading from a previous version of AsteriDex, export your asteridex MySQL database and then import it into your TrixBox system. We'll show you how below.

Installing AsteriDex Into MySQL. If you're using AsteriDex for the first time, here's how to load the MySQL database for AsteriDex. Access your TrixBox system using a web browser and go to Asterisk->System Administration->phpMyAdmin. When the program loads, look in the left pane immediately below the phpMyAdmin logo and click on the SQL icon. When the SQL window opens, click on the Import Files tab and then the Choose File button. Click on Desktop->Asteridex->mysql and choose the asteridex.sql file. The file name now should be displayed in the SQL window pane. Using the default utf-8 character set, click the Go button to load the database into MySQL. You should get a pretty display which says, "Your SQL query has been executed successfully." Just to be sure, click on the user1 table in the left pane, and then click the Browse tab at the top of the right pane. This is one way to make changes to your Asteridex address book: Asterisk->System Administration->phpMyAdmin->Asteridex database->user1 table->Browse. You can click the pencil icon beside an entry you want to modify, or click the red X icon to delete an entry from your table. It's permanent so be careful. To Add new entries to the table, click the Insert tab at the top of the right phpMyAdmin panel. Leave the ID and DialCode fields blank. ID will get filled in automatically, and DialCode is the speed dial entry for this person. Enter a name for the person or business. For people, we recommend Lastname, Firstname. If you leave the asterisk (*) in the IN field, AsteriDex will call you on your default phone before placing the outbound call. We'll get to default calls in a minute. If you'd prefer to always be called at a specific extension, enter the extension number, e.g. 204. Do not enter sip/204! We'll do the heavy lifting for you. Congratulations! You're now a database expert. Just come back and fill up your Little Black Book once we get finished with the installation. Actually, you won't have to use phpMyAdmin, but we wanted you to know it's always an option.

Upgrading AsteriDex Using an Existing AsteriDex MySQL Database. If this is your first time using AsteriDex, you can skip this section. If you've been using AsteriDex with an Asterisk@Home or Asterisk system and want to move your database over to a new TrixBox system, here's how. On your old system, use phpMyAdmin to access MySQL. It's under the Maintenance tab in AMP with Asterisk@Home systems. Once you're in, click on the Export link in the right frame. Click on asteridex in the database column to select it, and then uncheck Use hexadecimal for binary fields. Finally, click the Save As File checkbox and then the Go button to export the database to your desktop. You'll end up with a file named localhost.sql on your Desktop. That completes the export.

To import your MySQL database into your new TrixBox system, point your web browser at the IP address of your machine. Then click System Administration and enter maint for your username and whatever password you assigned when you set up your system. Now click on phpMyAdmin and follow the installation steps above except use localhost.sql from your Desktop when prompted for the name of the database to import.

Configuring TrixBox for AsteriDex. There are a couple configuration steps for the AsteriDex application before we can drop in the web code and try it out. We need to add a dialout context at the bottom of the extensions_trixbox.conf file. A copy of the context is included in the /freePBX subfolder of the asteridex folder on your desktop. Here's the code you'll need, but you can't just drop it in. First, you need to figure out which dialout trunk will be used to place the outbound leg of the AsteriDex calls. Just keep in mind that, using the web interface, AsteriDex actually places two calls, one to you and one to the person you want to talk to. So be sure you have a channel for each of the calls if you opt to use a non-local extension for your incoming call. Anyway, what you need below is the trunk number that you want to use for the outbound calls. You can look these up by going to TrixBox->System Administration->Config Edit->extensions_additional.conf. Then look at the Global variables OUT_0, OUT_1, etc. Identify the number of the one for the VoIP provider you want to use and then replace the bolded 0 in line 3 below with that number. If you want a fallback provider in case your first choice is down, then copy the line 3 code below to the next line, substitute your second choice provider number for 0, and then renumber the lines: 1, 2, 3, 4, and 5. Once you get the code the way you want it, cut and paste just the code snippet below to the end of the extensions_trixbox.conf file and restart Asterisk.

[custom-callboth]
exten => _1NXXNXXXXXX,1,Wait(1)
exten => _1NXXNXXXXXX,2,Background(pls-wait-connect-call)
exten => _1NXXNXXXXXX,3,Macro(dialout-trunk,0,${EXTEN},)
exten => _1NXXNXXXXXX,4,Macro(outisbusy) ; No available circuits


Editing the Caller Location. One more configuration step, and we'll be ready to drop in our web application. Open the asteridex folder on your desktop and then, using your favorite text editor, open callboth.php (nano -w callboth.php). We're going to set four variables (beginning on line 26) to meet your local needs. The variables look like this now.

$INdefault = "SIP/200" ;
$INtrunk="SIP" ;
$LDprefix="1" ;
$CallerID="6781234567" ;

Move to the above lines using your editor, and set $INdefault to the extension you want to ring where you want to take phone calls being placed with AsteriDex. If it's a SIP phone or a PSTN phone connected to an ATA, the sip syntax shown is correct. Just plug in the appropriate extension. If you'd prefer to send the calls to a ring group so multiple phones ring when you place a call, the syntax is local/222@from-internal where 222 is the number of the ring group you want to use. If you're using an IAXy extension, the syntax is IAX2/244. You also have the option of ringing any other telephone or cellphone even though it's not a local extension on your Asterisk PBX. Just make sure you have sufficient outbound trunks to support two simultaneous calls. The syntax for an external phone is SIP/telasip-gw/16785551212. Substitute your VoIP provider for telasip-gw and plug in the phone number with the prefix, if any, required to place calls through this provider. For those lucky enough to have GrandStream's GXP-2000 IP phone with AutoAnswer, you can configure the GrandStream phone to automatically answer and activate the speakerphone for incoming calls on a specified extension. To take advantage of this, just set $INdefault to this extension (SIP/267), and your GrandStream will go off-hook automatically each time you place a call using AsteriDex. Too cool! P.S. Some Aastra/Sayson IP phones can do the same trick.

$INtrunk defines the protocol which will be used to place calls to you (i.e. inbound) assuming you make entries in your database that specify an actual extension rather than using an asterisk (*) to force incoming calls to the $INdefault setting. For SIP phones or PSTN phones through an ATA, use SIP. For IAXy extensions, use IAX2. For PSTN calls using Asterisk cards, use ZAP.

$LDprefix defines the dialing prefix to be used for outbound calls to numbers stored in your database. Our recommendation is to enter all phone numbers in your AsteriDex database as 10-digit numbers. Then control the required dial string for your outbound provider by adding this dialing prefix. If your provider doesn't require a prefix for outbound calls, just delete the 1 above and leave the two double quotes with no space between them.

$CallerID defines the CallerID string for your outbound call. Most VoIP providers (other than TelaSIP) don't let you change this so just enter the 10-digit number associated with your outbound trunk, if any.

When you finish making all the entries above, save the file in ASCII text format.

Loading AsteriDex On Your Apache Web Site. The web site that is served by your Asterisk machine is stored in /var/www/html. For use behind your firewall/router, you can access the site at http://192.168.0.133/ substituting the private IP address of your Asterisk machine, of course. What we want to do now is copy the asteridex folder on your desktop to /var/www/html so that the site can be accessed at http://192.168.0.133/asteridex/. Don't forget the trailing slash mark, or you may see nothing. If you have turned on Internet access to your web server by mapping http and port 80 traffic to the private IP address of your Asterisk server, then keep in mind that ANYONE can run the application by simply going to your public IP address/asteridex with a web browser. This probably isn't a real good idea. There are numerous methods to protect the AsteriDex web site if you decide to go "public." The most secure way is to copy the asteridex folder into /var/www/html/maint. Apps in this folder require your maint username and password for access. So you then could access AsteriDex at this site address: http://192.168.0.133/maint/asteridex/ (substituting the private IP address of your Asterisk machine or your public IP address, of course)

Activating AsteriDex Admin Interface. You didn't really think we'd leave you with nothing but phpMyAdmin to maintain your AsteriDex database, did you? Well, you were right. There is an admin interface for AsteriDex. But, before you can use it, you have to designate the IP address of the desktop machine you'll be using with it. Go to the AsteriDex directory on your Asterisk web site: cd /var/www/html/asteridex. Now carefully edit the admin interface program: nano -w admin.php. On the second line, you'll see the following IP address: 192.168.0.107. Unless this just happens to be the IP address of your desktop machine that you want to use to administer AsteriDex, it needs to be changed to the correct IP adddress. Don't change anything else including the punctuation. Now save your changes: Ctrl-X, Y, then press enter. You now should be able to call up the Admin interface with the following link: http://asteriskboxIPaddress/asteridex/admin.php. That's a big pain in the rear if the only person that will be using this system is you. So here's a shortcut. While you're in the AsteriDex directory, enter the following command: echo 123 > admin and press enter. That will create a file called admin with 123 as the contents. Henceforth, when you run AsteriDex, the admin option will appear as an additional tab. You still have to be using the correct machine to access it, however. Not sure of your machine's IP address? Just access the Admin option once, and it will quietly return you to the ABC tab. But, if you look in your browser's command window, it will have the IP address of your workstation identified following ip= on the command line. That's the IP number you need to insert on the second line of the admin.php file. We're going to gamble that once you see the interface, you'll be able to figure it out on your own. Just a word of warning: the delete entry option does just that. No warnings. No second chances.

Taking AsteriDex For A Test Run. Once you drop the folder in place on your web site and get it named, you should be ready to roll. Use your favorite web browser to call up AsteriDex and click on one of the included airlines to place a test call. Your web browser will display the contact's phone number as you drag the mouse over an entry. Once you click on a link, a separate browser window will pop up momentarily, and then the default phone you designated should start to ring. Pick it up, and your outbound call will be placed. Book a nice trip to Hawaii for your friend, Ward Mundy, and then hang up and send me the ticket. Wasn't that easy!

Activating the RoboDialer. We mentioned at the outset that this updated version of AsteriDex now lets you place calls from any touchtone phone using your AsteriDex phonebook. Here's how. First, as you add new entries, specify a one to five-digit DialCode for the entry. These codes must be numbers that correspond to the numbers on your touchtone phone obviously. You can make them anything you like. We prefer a number that matches the first four characters of our friends' first names, but again that's up to you. Once you get your database loaded up with DialCodes, then we need to drop another little block of code in the top section of the extensions_trixbox.conf file. Here's what the code looks like so just add it to the [from-internal-trixbox] context at the top of the file. This setup will use your default TrixBox dialing rules for the calls:

exten => _00.,1,SayDigits(${EXTEN:2},) ; extensions dialed with 00 prefix get looked up in AsteriDex
exten => _00.,2,EAGI(asteridex.agi|${EXTEN})
exten => _00.,3,GotoIf($["${DIAL:0:2}" = "00"]?97)
exten => _00.,4,NoOp(Number to Dial: ${DIAL})
exten => _00.,5,NoOp(Person to Dial: ${DUDE})
exten => _00.,6,Flite("Connecting to: ${DUDE}. One moment please.")
exten => _00.,7,Goto(outbound-allroutes,${DIAL},1)
exten => _00.,8,Hangup()
exten => _00.,97,Playback(num-not-in-db)
exten => _00.,98,Playback(goodbye)
exten => _00.,99,Hangup()

Finally, we have an AGI script which you'll find in the agi-bin folder of the asteridex code you downloaded to your desktop. The file name is asteridex.agi. Copy this file to the /var/lib/asterisk/agi-bin folder on your TrixBox server and, while logged in as root, change the ownership of the file: chown asterisk:asterisk /var/lib/asterisk/agi-bin/asteridex.agi. And then change the file permissions to make the file executable: chmod 775 /var/lib/asterisk/agi-bin/asteridex.agi. After you reload Asterisk (amportal restart), you should be all set. Pick up a phone on your system and dial 00 plus the DialCode of someone in your database and Shazam!

Configuring AsteriDex for Multiple Sites. The web-based interface of AsteriDex is designed to call you at a specific phone number or ring group when you click on a contact in the database. But suppose you want to use AsteriDex either in multiple locations or with simultaneous users each with a different phone number. The only trick here is to decide up front whether all of the sites and/or users will be sharing the same phone book.

If all of the users or sites will be sharing the same phone book, then it's quite simple to customize AsteriDex for multiple users or locations. Just copy the /var/www/html/asteridex directory to a new location with a new name, e.g. /var/www/html/lakehouse or /var/www/html/janet. Once you've copied all the files, you'll need to adjust the callback number and IP address of this site or user. To adjust the callback number, review the Editing the Caller Location section above. To adjust the IP address, review the Activating AsteriDex Admin Interface section above.

If you want each user or site to have their own phone book, then the project is more complex. You either have to make duplicate copies of the asteridex database (with different names, of course) or you have to make additional user1 tables such as user2, user3, etc. You'll also need to create a duplicate asteridex.agi script with a new name for each user. Then you'd edit the asteridex_lookup subroutine to match your new database or table name. Next you'll need to repeat the steps above to duplicate the asteridex web directory. Once you have the new directory in place, you'll need to edit each of the php files and change all instances of either the database or table name and the agi script name to match your new file names. Finally, you'll need to adjust the dialplan code in Activating the RoboDialer to match your new script name. HINT: As currently written, AsteriDex really wasn't designed to have different databases for different users. In case you haven't caught on yet, it would be just about as easy to start over as to try and rework our code to make the square peg fit in the round hole. Note that the existing database does have a facility to support different call back numbers for different entries in your database. So it's really quite easy to build entries which ring different phones based on the entry. For the Contact Name, you might want to use a prefix such as Lake: Wendy's which would mean ring the lake house phone when I want to call Wendy's. Then, for the Your Extension entry, enter the phone number of the lake house phone instead of an asterisk. Piece o' cake!

AsteriDex for Smartphones. Since this article was originally published, we've added a new piece of code for those that happen to have a smartphone or PDA phone and want access to your AsteriDex database for dialing. You'll need something like a Blackberry, 6700 smartphone, Treo 650 or 700 that includes a real web browser (not WAP!) and web service from your cellphone provider. Install AsteriDex as outlined above. Then open up port 80 on your firewall and point it to the private IP address of your TrixBox system so that you can access the web server running on your TrixBox system. To install the smartphone software, log into your server as root and execute the following commands:

cd /var/www/html
mkdir cellphone
cd cellphone
wget http://nerdvittles.com/wp-content/cellphone.zip
unzip cellphone.zip
rm -f cellphone.zip
chown asterisk:asterisk index.php
chmod 775 index.php

Now you can access your AsteriDex database entries from the web browser on your cellphone by pointing the browser to: http://PublicIPaddress/cellphone/ or http://AsteriskFQDN/cellphone/. If your smartphone is fairly "smart" you can also dial any number in your AsteriDex database by simply clicking on the desired phone number. At least with Sprint cellphones, you also have the option of sending a text message to anyone with a cellphone by clicking on any phone number entry. Please note that these outbound calls will be made directly through your cellphone provider, not through your Asterisk system (as was the case with the original AsteriDex web-dialing project). The reason is pretty simple. Most smartphones don't support simultaneous use of your web browser and phone so there's no way for your Asterisk box to call you without getting your voicemail. Yes, we did try it!

Update for International Calling. The robodialer originally only supported 10-digit phone numbers. That's now been fixed thanks to chandave, our non-resident Perl genius.

Enhancing CallerID with AsteriDex. Once you get AsteriDex up and running, learn how to use it to look up CallerID names for all your incoming calls. Click here (including all the comments) for details. We're going to revisit this project especially for TrixBox in the next week or two.

Nerd Vittles Demo Hot Line. You now can take a number of Nerd Vittles projects for a test drive... by phone! The current demos include NewsClips for Asterisk (latest news headlines in dozens of categories), MailCall for Asterisk with password 1111 (retrieve your email by phone), and Nerd Vittles Weather Forecasts by U.S. Airport Code. Just call our Stanaphone 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.

Hosting Provider Special. 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 up to 6 domains with 30GB of disk storage and 750GB of monthly bandwidth. Free domain registration is included for as long as you have an account. That almost doubles last month's deal, and it really doesn't get any better than that. Their hosting services are flawless! We oughta know. We've tried the best of them. If you haven't tried a web hosting provider, there's never been a better time. Just use our link. You get a terrific hosting service, and we get a little lunch money.

Want More Projects? For a complete catalog of all our previous Asterisk projects, click here. For the most recent articles, click here and just scroll down the page.

Headline News for the Busy Executive and the Lazy Loafer. Get your Headline News the easy way: Planet Asterisk, Planet Gadget, Planet Mac, and Planet Daily. Quick read, no fluff.

Got a PDA or Web-Enabled Smartphone? Check out our new PDAweather.org site and get the latest weather updates and forecasts from the National Weather Service perfectly formatted for quick download and display on your favorite web-enabled PDA, cellphone, or Internet Tablet. And, of course, it's all FREE!