AsteriDex 3.1

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 previous versions of AsteriDex, 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, either download asteridex3.zip and replace the callboth.php script. No other parts of the application need to be updated so long as you were currently running version 3.0. In the alternative, you can log into your Asterisk server as root and issue the commands below. Because a security vulnerability now has been identified, you 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
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 either a TrixBox version of Asterisk (version 1.2.3 is highly recommended if stability matters to you) or Asterisk@Home. Otherwise, you'll need to install Flite, freePBX, Apache, PHP4, phpMyAdmin, and MySQL support on your Asterisk machine.

Desktop Download

[zip] asteridex31.zip (20KB)

Database Setup

After downloading the AsteriDex application to your Desktop, unzip the file on your Desktop. Then log into phpMyAdmin on your Asterisk system. If you're using a TrixBox system, point your web browser to the IP address of your Asterisk server. Then click System Administration, then phpMyAdmin. Enter maint as your username and whatever password you assigned when you set up your system.

When phpMyAdmin 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 to get to the mysql folder in the AsteriDex download. 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. A message will display shortly saying, "Your SQL query has been executed successfully." Close your browser.

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 TrixBox, point your web browser at your Asterisk server again. Then choose System Administration->Config Edit->extensions_additional.conf. Look at the Global variables OUT_0, OUT_1, etc. Identify the numbers of the ones for the VoIP providers you want to use for placing outbound calls. Now close the extensions_additional.conf file.

While still in the Config Edit listing, choose extensions_trixbox.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 with the outbound trunk number you identified above.

[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

If you want a fallback dialout trunk or to support different dial strings with different outbound trunks, make a duplicate of the dialout-trunk line immediately below where it appears in the sample above. Then renumber the lines 1, 2, 3, 4, 5. Save your changes to the file 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,0,${EXTEN},)
exten => _1NXXNXXXXXX,4,Macro(dialout-trunk,1,${EXTEN},)
exten => _1NXXNXXXXXX,5,Macro(outisbusy) ; No available circuits

Web Setup

Log into your Asterisk server as root and issue the following commands:

cd /var/www/html
mkdir asteridex
cd asteridex
wget http://nerdvittles.com/trixbox11/asteridex3.zip
unzip asteridex3.zip
rm -f asteridex3.zip
cd asteridex
chown asterisk:asterisk *
chmod +x *
nano -w callboth.php

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

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

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

$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 pair of 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 on the fly so just enter the 10-digit number associated with your outbound trunk, if any. Once you finish making all these entries, save the file by pressing Ctrl-X, then Y, then Enter.

Admin Setup

AsteriDex needs to know the IP address of the machine on your network which will have Administrator access. This is the person that can actually add, edit, and delete entries in the AsteriDex Phonebook. To designate the appropriate address, edit admin.php (nano -w /var/www/html/asteridex/admin.php). Replace 192.168.0.107 on the second line with the IP address you wish to use. 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/asteridex/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/asteridex/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

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-trixbox] context within the extensions_trixbox.conf file: nano -w /etc/asterisk/extensions_trixbox.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 in 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, 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 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 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/asteridex/. 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 ($INdefault) specified in callboth.php to be used. When you click the Add new Entry button, the person will be added to the MySQL database.

[Screenshot]

To use AsteriDex, call it up in your browser: http://ipaddress/asteridex/. 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.

If you've installed either Nerd Vittles PBX-in-a-Flash for TrixBox or the Nerd Vittles VMware version of TrixBox, then incoming calls will automatically be screened using the AsteriDex database. Where there's a match on the incoming number, the name of the person as entered in your AsteriDex Phone Book will be shown on your phone's CallerID display. AsteriDex also is integrated into our new CallerID Trifecta application for freePBX 2.2.0.

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/asteridex 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 65 and change the existing SEQ number to your new number. Now edit ALL of the following files and make the change using the same number on lines 53, 62, and 72. The files are index.php, def.php, ghi.php, jkl.php, mno.php, pqrs.php, tuv.php, and wxyz.php. No change is necessary in the cellphone web page since it uses a different dialing method that doesn't rely upon Asterisk.