AsteriDex 4.0

Web-Based RoboDialer & Kitchen Sink

AsteriDex is a web-based dialer and address book application for Asterisk, the open source PBX. It lets you store and manage phone numbers of all your friends and business associates in an easy-to-use MySQL database. You simply call up the application with your favorite web browser and click on the contact you wish to call. AsteriDex first calls you at the number you designated for this contact, and then AsteriDex connects you to your contact through another outbound call made using your Asterisk server.

AsteriDex also automatically looks up CallerID names in your MySQL database for all incoming calls. And, it can be configured to function as a speed dialer for your phone system. Just 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 places the call after announcing the name of the called party. Finally, AsteriDex can be used as a Click-to-Call system for customer service applications, or it can be configured to minimize cellphone charges on some cellphone plans by allowing callers to dial outbound calls through a web interface after which AsteriDex calls the initiator of the call and then the second called party.

Security Alert: For those using versions of AsteriDex before 3.1, this is a critical update. A security vulnerability was discovered in the callboth.php script which is stored in your AsteriDex web directory (typically /var/www/html/asteridex). At a minimum, download and replace the callboth.php script as shown below after logging into your server as the root user. Unless you wish to upgrade to version 4.0, no other parts of the application need to be updated so long as you were currently running version 3.0. Because a security vulnerability now has been identified, you also are well advised to implement the additional two safeguards documented in the Hardening Your System section at the end of this article.

cd /var/www/html/asteridex (this should be adjusted if you installed AsteriDex in an alternate location)
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

Prerequisites

To use all of the features of AsteriDex, you'll obviously need an Asterisk server. And we recommend our very own PBX in a Flash. Otherwise, you'll need to install Flite, FreePBX, Apache, PHP4, phpMyAdmin, and MySQL support on your existing Asterisk machine.

Design Considerations

The only real trick to getting AsteriDex to work reliably is making certain that the number format for your phone numbers is consistent in the AsteriDex database and configuration, in your Outbound Trunks, and in your Dialplan entries that actually place outbound calls. For those in the United States, the default settings should work fine with most providers. We recommend that numbers stored in your AsteriDex directory when coupled with the long distance prefix ($LDprefix) actually match the dial string that your outbound terminations provider is expecting to receive. To keep it simple, store area codes and numbers in the AsteriDex directory, and add an appropriate $LDprefix in the AsteriDex config file, config.inc.php, to match the dial string your trunk provider is expecting to receive when outbound calls are placed. This dial string also must match the search string entries inserted into your Dialplan, e.g. _1NXXNXXXXXX would identify U.S. phone numbers in the format 1 + area code + 7-digit local number. For those using AsteriDex in other countries, keep in mind that the dialing format needs to be consistent in all three places for AsteriDex to work reliably. If you hear a "goodbye" message or an "all circuits are busy" message when you attempt to place outbound calls, chances are there is a mismatch in one of the three places outlined above.

Server Download

We recommend installing AsteriDex directly from your Asterisk server. The process is covered in detail below. A separate download file is provided here for those that want to perform the installation from a desktop PC.

asteridex4.zip (11KB)

To install directly onto your server, log into your Asterisk server as root and issue the following commands:

cd /var/www/html
mkdir asteridex4
cd asteridex4
wget http://bestof.nerdvittles.com/applications/asteridex4/asteridex4.zip
unzip asteridex4.zip
rm -f asteridex4.zip
chown asterisk:asterisk *
chmod +x *
nano -w config.inc.php

Once the editor displays the config.inc.php script, scroll down to line 10 where you'll see settings for four variables that need to be configured to meet your requirements.

$INtrunk="SIP" ;
$defaultExt = "SIP/201" ;
$LDprefix="1" ;
$CallerID="5551234567" ;

$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 $defaultExt 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.

$defaultExt should be set to the extension you want to ring when you place calls with the AsteriDex web interface. If it's a SIP phone or a PSTN phone connected to an ATA, the sip syntax shown above is correct. In version 4, this default phone number can be adjusted through the web interface so that a cookie is stored on individual desktops in multi-user environments. Just set the appropriate extension number to ring on your system.

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 by your dialplan 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 $defaultExt to the extension number of your GrandStream phone, and it will go off-hook automatically each time you place a call using AsteriDex.

$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 pair of double quotes with no space between them.

$CallerID defines the CallerID string for your outbound call. Many VoIP providers don't let you change this on the fly so just enter the 10-digit number associated with your outbound trunk, if any.

Admin Setup

AsteriDex also needs to know the IP addresses of the machines on your network which will have Administrator access. These are the people that can actually add, edit, and delete entries in the AsteriDex Phonebook. To designate the appropriate addresses, edit the $local_net entry in config.inc.php. The default entry is to permit Admin access for anyone on the 192.168 subnet. Adjust it to meet your needs. Then save the file: Ctrl-X, Y, then Enter.

By default, the Admin pane never displays in AsteriDex. You have to manually call it up with your browser: http://ipaddress/asteridex4/admin.php. If your system is secure and you're the only user, here's how to modify that behavior. While in the asteridex web directory, issue the following command and press Enter:

echo 123 > admin

AGI Script Setup

While still logged into your Asterisk system as root, we need to copy the AGI Perl script to the appropriate directory:

cd /var/www/html/asteridex4/agi-bin
cp asteridex.agi /var/lib/asterisk/agi-bin/asteridex.agi
cd /var/lib/asterisk/agi-bin
chown asterisk:asterisk asteridex.agi
chmod +x asteridex.agi

Database Setup

While still logged into your Asterisk system as root, we need to install the AsteriDex MySQL database in which your directory entries are stored:

cd /var/www/html/asteridex4/mysql
./loadmysql.sh

Dialplan Setup

AsteriDex actually places two calls each time you choose someone from its Address Book. First, it calls you. We call this the inbound call. When you answer, it then places an outbound call to the person you chose from the web-based Address Book. Although not required, normally the inbound call is to an extension on your Asterisk system. The outbound call requires an outbound trunk on your system. Most folks have more than one trunk so you'll need to identify the one you want to use to place the outbound calls. If you want the inbound call delivered outside your Asterisk PBX, e.g. to a cellphone, then you'll also need to identify a separate trunk to handle that leg of the call unless your preferred provider offers more than one channel for outgoing calls.

The dialplan code that will be inserted below requires the trunk number for the channel that will be handling the outbound call. If you're running PBX in a Flash with FreePBX, point your web browser at the IP address of your Asterisk server. Then choose Administration->FreePBX and log in with admin username and password. Next click Tools->Config Edit->extensions_additional.conf. Look at the Global variables OUT_1, OUT_2, etc. Identify the numbers of the ones for the VoIP providers you want to use for placing outbound calls. Then close the extensions_additional.conf file.

While still in the Config Edit listing, choose extensions_custom.conf from the file listing. When the file opens, scroll to the bottom. Then cut-and-paste the following code into the file. Replace the number following dialout-trunk in both line 3's with the outbound trunk number you identified above. Save your changes by clicking the Update button.

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

If you want a fallback dialout trunk or to support different dial strings with different outbound trunks, make a duplicate of the dialout-trunk lines immediately below where it appears in the sample above. Then renumber the lines 1, 2, 3, 4, 5. Save your changes to the file by clicking the Update button and close the browser window when you're finished. The multiple dialout trunk code would look something like the following:

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

Once you've added the new code and saved the file, reload Asterisk from the command prompt to activate AsteriDex:

amportal restart

Adding AsteriDex to PBX in a Flash Admin Menu

To add AsteriDex as an option on the Administration Menu of the PBX in a Flash default web page, issue the following command after logging in as root. If you decide to change the directory name from asteridex4, be sure to make the same substitution below:

sed -i 's|\./asteridex|\./asteridex4|' /var/www/html/index.php

Robodialer Enhancement

AsteriDex now provides a speed dialer so that folks on your Asterisk system can dial an access code and then up to five characters to match individual's in your AsteriDex Phone Book. There are two steps to get this working. First, you have to manually add DialCode entries in the Phone Book for entry that you want to access using the RoboDialer. We recommend that the entries be 5 numbers in length and that the entries correspond to the first five letters (on the phone) in each person's name. First or last name is up to you. After you make all of the DialCode entries, then you have to modify your dialplan to support the RoboDialer. Add the following code snippet to the [from-internal-custom] context within the extensions_custom.conf file: nano -w /etc/asterisk/extensions_custom.conf.

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()

Once you've added the code, save the file. Then reload Asterisk to activate AsteriDex:

amportal restart

For our International Friends, yes, you can change the 00 prefix to something more suitable to your phone system. Make the change in the _00 entry on each line above. And don't forget to also adjust the "00" entry toward the end of line 3.

Cellphone Browser Enhancement

For those with browsers and Internet access on your cellphone, AsteriDex now supports access from these phones. You'll need something like a Blackberry, 6700 smartphone, iPhone, 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 PBX in a Flash system so that you can access the web server running on your PBX in a Flash system. To install the smartphone enhancement for AsteriDex, 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 +x index.php

Now you can access the cellphone version of AsteriDex by pointing the browser on your phone to the public IP address of AsteriDex for Cellphones. 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 and AT&T 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. 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.

http://publicIPaddress/cellphone/ or http://AsteriskFQDN/cellphone/

Using the AsteriDex Phonebook

Once you finish the installation, the next step is to add some folks to your AsteriDex Phone Book. Otherwise, you don't have anyone to call. Using a web browser on the desktop machine that you designated as your Admin system, call up Asteridex: http://ipaddress/asteridex4/admin.php. Click on the Admin tab which should display the Admin Menu. If instead you get the ABC Phone Book page, look in the Address bar of your browser where AsteriDex will have identified the IP address of the desktop machine you're using. Then reconfigure the Admin setting accordingly.

From the Admin Menu of AsteriDex, you can perform the following tasks:

Add Entry
Edit Entry
Delete Entry

A degree in Rocket Science isn't required to figure any of these out. The Edit and Delete options provide pull-down lists of everyone in your Phone Book. Point and click to the entry you want to change, make the changes or deletion, and you're done. Adding a new person to the Phone Book requires the Name of the person, their Phone Number, their DialCode for speed dialing, and the internal number to call when this person is chosen from the Phone Book. Leaving an asterisk in this field will cause the default Inbound Number ($defaultExt) specified in callboth.php to be used. When you click the Add new Entry button, the person will be added to the MySQL database.

To use AsteriDex, call it up in your browser: http://ipaddress/asteridex4/. Click on the tabs to see the entries in your AsteriDex Phone Book. Click on a Name to place the call. Your phone will start ringing. Pick it up, and the second leg of your call will be placed to the person you chose in the Phone Book.

To use the AsteriDex RoboDialer, pick up a phone and dial 00 followed by the five-digit code for the person you wish to call.

Incoming CallerID Support Using AsteriDex

For an excellent CallerID application for PBX in a Flash that includes support for AsteriDex and many other phone directory services, see this thread. Thanks, Tony.

Hardening Your System

Because a security vulnerability with prior versions of AsteriDex now has been published, you are strongly advised to implement both of the following additional security features to protect your Asterisk system. First, change the name of the web directories being used to access AsteriDex with a web browser. This includes /var/www/html/asteridex4 and /var/www/html/cellphone if you are using the separate cellphone web interface. Be sure to use directory names which are not obvious, e.g. gooberpeas or asteridex4932.

AsteriDex also has a built-in security key which has not been previously documented. It's a unique six-digit number which is paired between the web pages and the callboth.php file that actually places the calls for you. For anyone to attempt to dial calls independently of AsteriDex using the callboth.php application, they must have this six-digit number. Your mission is to change it to something that only you know. Make it six digits long and be sure to use the same number in all of the places where you make the following change. In the callboth.php file, modify line 61 and change the existing SEQ number to your new number. Now edit line 73 in index.php, and plug in the same SEQ number used in callboth.php. Save your changes. No change is necessary in the cellphone web page since it uses a different dialing method that doesn't rely upon Asterisk.

Special Thanks

Our extra special tip of the hat goes to James Van't Slot of Simple Reliable Networks in Seattle. He added some much needed streamlining to the code in this version of AsteriDex as well as providing cookie support to make AsteriDex much more useful in a multi-user environment. Thanks, James.