This article has been updated. Go to this link for the most recent version.

Want a rock-solid PBX at a rock-bottom price: free! Well, it's been two days since our tutorial on AAH 2.4 but here we go again! Asterisk@Home 2.5 has hit the street because of another serious bug-fix release of Asterisk®. Now you get version 1.2.4 of Asterisk, and you also get the latest and greatest version of Linux, CentOS 4.2; the latest Festival Speech Engine (1.96); the latest version of the Asterisk Management Portal (1.10.010); the Flash Operator Panel (version 0.24); Open A2Billing; Digium card auto-configuration; NVfaxdetect support; loads of AGI scripts including weather forecasts and wakeup calls; xPL support; the SugarCRM Contact Management System with the Cisco XML Services interface and Click-to-Dial support; plus lots more. And, yes, it still fits on a single CD! NOTE: Virtually nothing has changed between version 2.4 and 2.5 except a new release of Asterisk minus memory leaks. If you waded through the 2.4 install with us, much of what follows will be very familiar. Our apologies! We're as tired of doing this every week as you are. Hopefully, this will be IT for a while.

Effective March 13, 2006, this article has been superceded by our new Soup-to-Nuts Guide for Asterisk@Home 2.7.

The installation process is pretty straightforward. You need a dedicated machine for this install although, for Windows users, here's another option that doesn't require a dedicated machine. To begin, download the 2.5 ISO image from here, burn a CD (click here if you need a refresher course), use an old clunker PC or a $200 WalMart special (see inset), insert the CD you made, plug your machine into the Internet and turn it on. Then watch while Asterisk@Home loads CentOS/4.2 and all the Asterisk and Linux goodies imaginable: Apache, SendMail, Comedian Mail, SugarCRM, MySQL, PHP, phpMyAdmin, SSH, Bluetooth, the Asterisk Management Portal, the Flash Operator Panel, Call Detail Reporting, and on and on. We've covered how to use most of the Linux products in our Mac HOW-TO's (see sidebar), and they work exactly the same way with Asterisk@Home so keep reading. And, yes, this install will reformat (aka ERASE) your hard disk before it begins, but it now warns you first.

Loading CentOS/4 and Asterisk 1.2.4. Here's how the 2.5 install went for us, and we'll walk you through getting everything set up so that it can be used as a production server. Once the install begins, you can expect to eat up about 25 minutes with the CentOS 4.2 install. The install CD then will eject itself, reboot the system, and begin the Asterisk compile and installation. That takes about 25 more minutes to complete.

Securing Your Passwords. When it's finished and reboots, log in as root with password as your password. Type help-aah for a listing of the five passwords that need to be changed. Change them all NOW!

passwd
passwd admin
passwd-maint
passwd-amp
passwd-meetme


Getting the Latest CentOS Updates. Once your system is secure, load all of the application updates for CentOS 4.2. There now are over 50 updates and installs so be patient. The update command to issue is yum -y update.

Activating Bluetooth Support. Once the updates are completed, activate Bluetooth support if you plan to use it with our Follow-Me Phoning proximity detection application. Run setup, down arrow to System Services, press ENTER, down arrow to bluetooth and press the space bar, tab to OK, press ENTER, tab twice to Quit and press ENTER.

Rebuilding Zaptel. First, reboot your system: shutdown -r now. Because a new version of the kernel is installed as part of the yum update, you'll need to rebuild support for ZAP devices. Log in as root and type the following command: rebuild_zaptel. Then reboot your system: shutdown -r now. Now log in as root again and type genzaptelconf. Reboot once more and you're all set to go: shutdown -r now. You only need to rebuild Zaptel when there is a kernel update as there was with this yum update.

Simplifying SSH. If you're going to be connecting to other servers from your new Asterisk@Home 2.5 system using SSH or SCP, then build your new RSA key pair now. This lets you use SSH and SCP (secure copy) without having to enter a password each time. You can also automate backups and proximity detection scripts as we've explained previously here. Log in to your new Asterisk@Home 2.5 server as root. From the command prompt, issue the following command: ssh-keygen -t rsa. Press the enter key three times. You should see something similar to the following. The file name and location in bold below is the information we need:

Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
1d:3c:14:23:d8:7b:57:d2:cd:18:70:80:0f:9b:b5:92 root@asterisk1.local

Now copy the file in bold above to your other Asterisk servers, Linux machines, and Macs. There's probably a way on PCs as well, but I've given up on that platform particularly after Sony's latest security stunt so you're on your own there. From your Asterisk@Home 2.5 server using SCP, the command should look like the following (except use the private IP address of each of your other Asterisk or Linux servers instead of 192.168.0.104). Provide the root password to your other servers (one at a time) when prompted to do so.

scp /root/.ssh/id_rsa.pub root@192.168.0.104:/root/.ssh/authorized_keys

On a Mac running Mac OS X, the command would look like this (using your username and your Mac's IP address, of course):

For user access only: scp /root/.ssh/id_rsa.pub wardmundy@192.168.0.104:/Users/wardmundy/.ssh/authorized_keys
For full root access: scp /root/.ssh/id_rsa.pub root@192.168.0.104:/var/root/.ssh/authorized_keys


Once the file has been copied to each server, try to log in to your other server from your Asterisk@Home 2.5 server with the following command using the correct destination IP address, of course:

ssh root@192.168.0.104

You should be admitted without entering a password. If not, repeat the drill or read the complete article and find where you made a mistake. Now log out of the other server by typing exit.

Installing WebMin. We don't build Linux systems without installing WebMin, the Swiss Army knife of the Linux World. You can use it to start and stop services, check logs, adjust startup scripts, manage cron jobs, babysit your SendMail server, and many, many other tasks that are downright painful without it. If you ever need help from others, WebMin is a great tool for letting others help you.

There are lots of ways to install WebMin. We prefer the easy way which is to issue the following commands at a Linux prompt after logging in as root. Note: WebMin updates come out all the time. If you want to be sure you start with the latest and greatest version, go to their web site first and write down the number of the current version. Then substitute it below when issuing these commands. Note that there is a new version of WebMin since our previous article on Asterisk@Home 2.2 was published.

cd /root
mkdir webmin
cd webmin
wget http://internap.dl.sourceforge.net/sourceforge/webadmin/webmin-1.260-1.noarch.rpm
rpm -Uvh webmin*


WebMin runs its own web server on port 10000. To start WebMin, issue this command: /etc/webmin/start. You access it with a web browser pointed to the IP address of your Asterisk box at that port address, e.g. http://192.168.0.108:10000. The login name is root. Then type in your root password and press enter. The main WebMin screen will display. We really don't want the WebMin server starting up each time the OS reboots so do the following. Once you're logged in to WebMin, choose System->Bootup and Shutdown and then click on webmin. Click the No button beside Start at boot time, and then click the Save button. Before we forget, we need to also make one change to the new Asterisk@Home configuration to avoid problems down the road. The default RTP listening ports for Asterisk@Home are set to 10000 to 20000 so there's a conflict on port 10000 with WebMin. Log in as root and, using an editor, call up the rtp.conf file: nano /etc/asterisk/rtp.conf. Now change the rtpstart port from 10000 to 10001 and save the change: Ctrl-W, Y, and press Enter. Then restart Asterisk: amportal restart. Finally, to stop WebMin when you're finished using it, issue this command: /etc/webmin/stop. You can start it any time you need it, and then use a web browser to access it. But there's no need to consume processing resources running a second web server when you're not using it.

IP Configuration for Asterisk. We need a consistent IP address or domain name both on your internal network and externally if you expect to receive incoming calls reliably. There are three pieces to the IP configuration: (1) setting the internal IP address of your Asterisk server, (2) configuring an external qualified domain name which will always point to your router/firewall, and (3) configuring your router to transfer incoming Asterisk packets to your Asterisk server. Log into your server as root using your new password. Now type ifconfig eth0 (that's "e-t-h-zero") then enter, and write down both your inet addr and your HWaddr on the Ethernet 0 interface, eth0. Inet addr is the internal IP address of your Asterisk box assigned by your DHCP server (i.e. your router/firewall). HWAddr is the MAC address of your Asterisk server's eth0 network card. To assure a consistent internal IP address, you can either configure your router/DHCP server to make certain that it always hands out this same address to your Asterisk machine, or you can manually configure an IP address for this machine which is not in the range of addresses used by your DHCP server. Almost all routers now make it easy to preassign DHCP addresses so we prefer option 1. It's generally under the tab for LAN IP Setup and is generally called something like Reserved IP table. Just add an entry and call it Asterisk PBX and specify the IP address and MAC address that you wrote down above. Now each time you reboot your Asterisk server, your router will assign it this same IP addreess. To assure a consistent external address is a little trickier. Unless you have a static (fixed) IP address, you'll want to use a Dynamic DNS service such as dyndns.org and configure your router to always advertise its external IP address to dyndns.org. DynDNS.org will take care of revising the IP address associated with your domain name when your ISP changes your dynamic IP address. Then you can configure your VoIP provider account using your fully-qualified dyndns.org domain name, e.g. windswept.dyndns.org provides access to our beach house network even though Time Warner cable hands out dynamic IP addresses which change from time to time. Finally, you'll need to log into your router and redirect certain incoming packets to the internal IP address of your Asterisk machine. If you want external access to the Apache web server on your Asterisk machine, then map TCP port 80 to the internal IP address of your Asterisk system. For WebMin external access, map TCP port 10000 to your Asterisk system. If you want remote access to your Asterisk system via SSH, then map TCP port 22 to the internal IP address of your Asterisk system. If you want external IP phones or other Asterisk servers to be able to communicate with your Asterisk system, then map the following UDP port ranges to the internal IP address of your Asterisk system:

SIP 5004-5082
RTP 10001-20000
IAX 4569

For more details, read our article on the subject.

Basic System Configuration. To get a basic Asterisk system up and running, you only need to do a few things. First, you need an Outbound Trunk to actually deliver your outbound calls to Plain Old Telephones (POTS). Second, you need to configure an Outbound Route to tell Asterisk which trunk to use to deliver your outbound calls to the intended recipients. Third, you need to configure at least one extension so that you can plug in some sort of telephone instrument to place and receive calls using your new Asterisk server. The phone can be a hardware device such as an IP telephone or a POTS phone, or it can be a software device such as a free IP softphone. The advantage of IP telephones and softphones is that they require no additional hardware besides your Asterisk server. A POTS phone or our favorite, a 5.8GHz wireless phone system with up to 10 extensions, both require an additional piece of hardware although some of the newer IP wireless phones give you the best of all worlds (see inset). To use a POTS phone, the hardware required is either a circuit board with an FXS port or an external black box (ATA device) such as a Sipura SPA-1001. If you also want to connect your Ma Bell phone line to your Asterisk server, then you need a circuit board with an FXO port or an external black box (ATA device) such as a Sipura SPA-3000. Our favorite is the SPA-3000 because it has both FXO and FXS ports in a box the size of a pack of cigarettes for under $100.

Setting Up An Outbound Trunk. You configure an outbound trunk using your web browser and the Asterisk Management Portal (AMP). But first, you have to have an account with a service provider. This is the company that carries your calls from your Asterisk server to plain old phones in your neighbor's house or Aunt Betty's in California. With VoIP, it's a good idea to have two providers, but today let's start with one. We'll save you some time and lots of money. Unless you make substantial international calls regularly, use TelaSIP/VoipExpress. If you want to know why, read the full article here. Or just try a free call for yourself using our server. Basically, $5.95 a month gets you a local number in your choice of area code with free incoming calls, and 2¢ per minute for outbound calls to anywhere in the U.S. $9.95 a month buys you all of that plus free outbound calls in the area code of the phone number you select. $14.95 a month gets you a number in the area code of your choice with unlimited incoming calls and unlimited outbound calls to anywhere in the U.S. There are no sneaky add-on fees and no obnoxious terms of service. Just be sure to tell them to configure your account for use with Asterisk. They also have very reasonable business plans. If, on the other hand, you'd prefer to try another provider, take a look at our easy setup guides for most of the major VoIP providers here.

Once you have your account name and password, point your web browser to the IP address of your new Asterisk@Home 2.5 server and log in as maint with the password you selected. Then choose AMP->Setup->Trunks->Add SIP Trunk assuming you're using TelaSIP. NOTE to existing users: if you already have an Asterisk server using your TelaSIP account, don't use the same account at the same time on your new Asterisk@Home 2.5 server! Plug in the CallerID number you were assigned for your account. Set Maximum Channels to 2. For the Dial Rules, use the following (substituting your local area code for 404 below):

1|NXXNXXXXXX
NXXNXXXXXX
404+NXXXXXX

In the Outgoing Settings section, name your trunk telasip-gw. Then enter the following for the Peer Details using your own account name for username and fromuser and using your own assigned password for secret. Be sure to enter the correct host that was assigned to your account:

context=telasip-in
dtmfmode=rfc2833
fromuser=youraccountname
host=gw4.telasip.com
insecure=very
secret=yourpassword
type=peer
username=youraccountname

Leave the Incoming Settings section blank, and in the Registration String, enter the following using your account name and password:

youraccountname:yourpassword@gw4.telasip.com

Click the Submit Changes button, and then click the red bar to reload Asterisk. Now we need to add the context which will actually process the incoming calls from TelaSIP. Choose AMP->Maintenance->Config Edit->extensions_custom.conf and add the following code at the bottom of the file substituting your new phone number for 4041234567. Save the file and reload Asterisk to finish the setup. See the Comments to this post for a more versatile approach which will let you use your TelaSIP line for Ring Groups.

[telasip-in]
exten => 4041234567,1,NoOp(Incoming call on TelaSIP #4041234567)
exten => 4041234567,2,Dial(local/200@from-internal,20,m)
exten => 4041234567,3,VoiceMail(200@default)
exten => 4041234567,4,Hangup


Configuring an Outbound Route. Now we need to tell Asterisk where to send our outbound calls when we dial them. To get started, we'll just send everything to the TelaSIP trunk we just configured. Choose AMP->Setup->Outbound Routing->Add Route. For Route Name, use Outside. Leave the password blank. For Dial Patterns, enter the following:

NXXXXXX
NXXNXXXXXX
1NXXNXXXXXX

For the Trunk Sequence, choose SIP->telasip-gw from the drop-down list. Then click Submit Changes. Be sure you also delete the sample outbound route that came with the install, or your outbound calls may go nowhere. Finally, click the red bar to save your new Outbound Routing setup.

Configuring an Extension. You have to have an extension to make and receive calls with Asterisk@Home so let's build one. Choose AMP->Setup->Extensions->SIP to begin. For the Extension Number, let's use 200 to keep things simple. For the Display Name, make up something that tells where this phone will be located, e.g. Kitchen. For the Outbound CID, use 200. For secret, make up a password for this extension. For Voicemail and Directory, choose Enabled. Plug in your password again. Type in your email address, and, if you want to also be paged when you get a new voicemail, type in a pager email address. Click the Yes button beside Email Attachment, and leave the other settings alone. Now click the Submit button and then click the red bar to save your changes and reload Asterisk.

Downloading a Free Softphone to Test Asterisk. Unless you already have an IP phone, the easiest way to get started and make sure everything is working is to install an IP softphone. You can download a softphone for Windows, Mac, or Linux from CounterPath. Or download the pulver.Communicator. Here's a new IAX softphone for all platforms that's great, too, and it requires no installation: Idefisk. All are free! Just install and then configure with the IP address of your Asterisk@Home 2.5 server. For username and password, use your extension number and password from above. Once you make a few test calls, don't waste any more time. Buy a decent SIP telephone. We think the best value in the marketplace with excellent build quality and feature set is the under $100 GrandStream GXP-2000. It has support for four lines, speaks CallerID numbers, has a lighted display, and can be configured for autoanswer with a great speakerphone. Short of paying three times as much, that's as good as desktop phones get. If you want to use Asterisk throughout your home, buy a good 5.8GHz wireless phone system with plenty of extensions (our two favorites are shown in the insets below) and then purchase an SPA-3000 to connect up both your home phone line and all your cordless phones. Our tutorial will show you how. The final option is to use a wireless IP phone which is the best of both worlds, a cordless phone that talks IP telephony without an ATA blackbox such as the Uniden UIP1868 (see also insets above).

Activating Email Delivery of VoiceMail Messages. When you're out and someone leaves you a voicemail message, Asterisk@Home will let you forward that voicemail message to your email address as a .wav file which can be played within most email client software. Or you can have Asterisk@Home send an instant message to your cell phone or pager telling you who called, what their phone number was, and how long a voicemail message the person left for you. Or you can do both. In addition, you can tell Asterisk@Home whether to delete the voicemail from your Asterisk server after sending it to your email account. In short, you now can manage all of your incoming email and voicemail from a single place, your email client. In order to send out emails from your Asterisk@Home server, you'll need to make a few changes. First, make this adjustment to the /etc/hosts file on the server. Since anonymous emails are blocked by most ISPs, you'll need a fully-qualified domain name for your server. If you don't have your own domain, the easiest alternative is to use the fully-qualified domain name that your ISP assigns to the IP address for your broadband connection. Don't forget to update it when your ISP changes your IP address! To find out what your fully-qualified domain name is, go to a command prompt on your Asterisk server and type: nslookup 123.456.789.001 substituting your public IP address for the preceding numbers. Then write down the name entry without the trailing period. Now edit the hosts file: nano /etc/hosts. Move the cursor to the second line which reads 127.0.0.1 asterisk1.local , and then move the cursor over the first letter of the first domain name shown, usually asterisk1.local. Now type in the fully-qualified domain name you previously wrote down and add a space after your entry. Don't erase the existing entry! Save your settings: Ctrl-X, y, enter. Now restart network services on your Asterisk machine: service network restart. Next, you need to modify the email message which delivers your voicemails so that it includes your fully-qualified domain name. Don't do this in AMP, or you'll mess up the formatting of the email message. You can download a fresh copy here if you need it. Instead, use nano: nano -w /etc/asterisk/vm_email.inc. Press Ctrl-W, type /cgi, and press the enter key. You're now positioned where you need to type either the fully-qualified domain name for your Asterisk server or the private IP address if you only want to read your emails from behind your firewall. When you start typing, the text display is going to jump all over the place because of word wrap. Don't freak out. You haven't messed anything up. Once you complete your entry, don't erase or change anything else. Save the file: Ctrl-X,Y, then enter. Now go into AMP->Maintenance->Config Edit->vm_general.inc with a web browser. Change the serveremail entry to an email name at the fully qualified domain you used in your /etc/hosts file above. Then save your configuration and restart Asterisk. If you continue with this setup and still don't receive emails, here's another configuration change that is sometimes necessary. On the Asterisk terminal, log in as root. Switch to the directory where the SendMail configuration file is stored: cd /etc/mail. Make a backup of the config file: cp sendmail.cf sendmail.cf.bak. Then issue the following command: echo CGasterisk.dyndns.org >> sendmail.cf. Substitute the actual domain name of your Asterisk server for asterisk.dyndns.org, but be sure it's preceded by CG with no intervening spaces.Then reboot your server and try again: shutdown -r now. Finally, if your ISP doesn't permit downstream mail servers (that's you), then take a look at this link which will show you how to designate your ISP as your SMTP smart host using SendMail.

To configure the voice mail forwarding options, go into the Setup tab of the Asterisk Management Portal using a web browser. Click on Extensions and then click on an extension you already have configured. In the Voicemail and Directory section of the form, enter either (or both) your email address and your pager or cellphone's text messaging address. To email the voicemails as attachments, just click Yes beside Email Attachment. To delete the voicemail message from your voicemail inbox after sending it to your email address (not recommended until you first get it working correctly), click Yes beside Delete Vmail. For those using a dynamic IP address with phones at remote locations connecting to your Asterisk server, we'll show you how to automate the process of changing your Asterisk server's IP address in a future column.

Call Recording Fixed. This update fixes inbound and outbound call recording which now works reliably. You can set your preferences for call recording when you set up each extension. The recordings are stored in /var/spool/asterisk/monitor unless you set other preferences in agents.conf.

Paging Fixed. If you want to use paging with your Asterisk system, the sound card problems in Asterisk@Home 2.1 and Asterisk 1.2 have been resolved. Review this posting on SourceForge for additional details. It now works with full and half-duplex sound cards. Thanks, Tracy!

Wakeup Calls Good News & Bad News. The good news is that Asterisk@Home 2.5 includes a new version of the Wakeup Call program, and the default setup works. The bad news is that the "annoy" option which is supposed to force the user to key in a number to prove they're awake still doesn't work. And, the wakeup call application now uses a different method of scheduling wakeup calls which broke our TeleYapper and Telephone Reminder applications. Mental note for would-be developers, don't rely on someone else's code to keep your code working reliably. This is especially true in the open source marketplace. Everyone is full of new ideas, and they don't necessarily stop to think of the impact the improvements will have on other folks' applications. We'll have new versions of our applications ... soon.

Adjusting Call Parking Extensions. Traditionally, pressing the pound key (#) and dialing extension 700 parked a call on Asterisk@Home systems and notified you of the parked extension. The call then could be picked up by dialing the parked extension in the range of 701 to 799 from any extension on your system. The new setup is to press # and dial 70 to park a call and 71-79 to pick it up. If you prefer the old setup, you'll need adjust the settings in features.conf. Go to AMP->Maintenance->Config Edit->features.conf and make it look like this:

[general]
parkext => 700 ; What ext. to dial to park
parkpos => 701-799 ; What extensions to park calls on
context => parkedcalls ; Which context parked calls are in


Directory Lookup Fixed. Pressing the pound key (#) from any phone connected to your Asterisk server now calls up a directory lookup function using the Asterisk Management Portal (AMP).

Max Channels Bug Remains. A bug has been reported because of a deprecated command that makes Asterisk@Home's calculation of maximum channels invalid. To fix it, goto AMP->Maintenance->Config Edit->extensions.conf->macro-dialout-trunk and comment out line s,7 so that it looks like this:

;exten => s,7,CheckGroup(${OUTMAXCHANS_${ARG1}})

Then insert a new line s,7 just below it which looks like this:

exten => s,7,GotoIf($[ ${GROUP_COUNT()} > ${OUTMAXCHANS_${ARG1}} ]?108)

Then click the Update button and reload Asterisk to activate the change.

Syntax Error in extensions.conf Causes Failed Incoming Calls. One of our readers has discovered a nasty little bug in extensions.conf that will cause some incoming calls to fail. Edit extensions.conf->macro-dial and change line s,22 as follows. Then reload Asterisk.
Before:

exten => s,22,GotoIf($[$[${HuntMembers} >= 1]?30 )

After:

exten => s,22,GotoIf($[$[${HuntMembers}] >= 1]?30 )


[Feb. 5 update] Adding Cellphone Extensions. There was a typo in the After: code above when this article was first published so check your entry against the one shown now. Once you make the above change, it's really easy to add "extensions" which dial directly to your cellphones or phones in remote locations. Just create a new Ring Group, give it a Group Number that matches the extension number you want to dial to complete the call (e.g. 244), choose hunt for the Ring Strategy, enter your cellphone number in the extension field with a # on the end using a dial string that matches your outbound trunk requirements (e.g. 16781234567# if your provider requires a 1-areacode-number format), choose a ring time in seconds, and a destination if no answer. If you want to have Asterisk track you down, enter several different phone numbers in the extension list. If you change hunt to ringall then all of the numbers will be called simultaneously instead of sequentially. Save your Ring Group entry, click the Red bar to reload Asterisk, and then dial the Ring Group extension number from any phone on your system. Presto!

Tweaking SIP.conf. There are a few changes we recommend you make in the [general] context of the sip.conf file. Using the Asterisk Management Portal, go to AMP->Maintenance->Config Edit->sip.conf. It's a good idea to include your actual CallerID number of your default outbound trunk here instead of Default. We also recommend that you add allow=gsm just below the existing allow=alaw line in the file. You may also want to include progressinband=yes which assures that callers will hear ring tones when placing calls even if your provider doesn't provide them. This is a fairly common complaint with BroadVoice in particular. Don't forget to reload Asterisk once you make these changes: AMP->Setup->Incoming Calls->Submit Changes and then click the Red bar.

Connecting Remote Extensions or a Remote Asterisk Server. If you plan to connect remote extensions to your Asterisk server, then add the following entries to sip.conf above using your own fully-qualified domain name and the first three octets of the private IP address of your Asterisk server:

externip = myasteriskbox.dyndns.org
localnet=192.168.0.0/255.255.255.0
nat=yes

You'll also either need to define your Asterisk server as a DMZ device in your firewall setup, or you can open the following UDP ports and map all of them to the private IP address of your Asterisk box: 4569, 5004-5082, and 10000-20000. If you only hear half of a conversation with a remote extension, it's usually a NAT problem meaning you probably forgot to do the port mapping drill. We plan to cover remote extensions and interconnecting Asterisk servers in more detail in a future column so stay tuned. In the meantime, if you have a dynamic DNS connection that changes your IP address regularly and you don't want to wrestle with manually updating your Asterisk server each time there's a change, just download chandave's sip reload script and copy it to your /etc/asterisk directory. Then execute the following commands while logged in as root:

chown asterisk:asterisk /etc/asterisk/sip_reload.sh
export EDITOR=nano
crontab -e
00,05,10,15,20,25,30,35,40,45,50,55 * * * * root /bin/sh /etc/asterisk/sip_reload.sh >/dev/null 2>&1

Save your crontab addition in the usual nano way, and you're all set: Ctrl-X, y, then enter. This clever little script will make sure your Asterisk server always knows its own IP address regardless of how often your ISP changes it. And you'll never lose inbound connectivity from remote extensions or servers for over 5 minutes. If you'd like to read the full discussion, visit this link on the Voxilla forum.

Managing Incoming Calls. For long time readers of this column, you already know that our recommended strategy for handling incoming calls is to set up a simple Stealth AutoAttendant. Basically, this is a welcome message that greets your callers and then transfers them to an extension or ring group of your choice. The advantage of this approach is that it also lets callers like you press buttons to navigate through various options on your Asterisk system without advertising them to the public at large. If you're just getting started with Asterisk, you can read all about setting up a Stealth AutoAttendant here. If you'd prefer to manage your incoming calls with AMP, you'll still need to fix the [from-sip-external] context in the extensions.conf file, or all your incoming SIP and IAX calls will ring busy. To fix it, choose AMP->Maintenance->Config Edit->extensions.conf->from-sip-external. Comment out all the lines in the existing file by adding a semicolon at the beginning of each line. Then add the following line, save your changes, and reload Asterisk.

exten => _X.,1,Goto(from-pstn-timecheck,s,1)


New Custom Speed Dialing. Asterisk@Home 2.5 has a built-in speed dialing utility. The reserved speed dial numbers are 300 to 399. Adding a number to your speed dial list is easy. Just pick up an extension and dial 300-3xx-6781234567 where 3xx is the speed dial code you want to create and 6781234567 is the phone number you want dialed when you enter the speed dial code. Just make sure you enter the number to be called in a format that is supported by your Asterisk dialplan, i.e. if outside calls need to be preceded by a 1 or a 9, then the number should be entered in a matching format. You can look up speed dial numbers by dialing an asterisk followed by the 3-digit speed dial code, e.g. *301 would tell you the number stored in speed dial 301. If you need additional flexibility with both web browser and phone access as well as 1 to 5-digit speed dial codes, download our free AsteriDex robodialer.

Fixed A2Billing: Asterisk Calling Card Platform. This web-based application allows you to generate and issue calling cards to individuals so that they can place calls remotely through your Asterisk server. If you've always wanted to be just like AT&T, here's your Big Chance! There's very little that you can do with an AT&T calling card that can't be done as well or better by you using A2Billing. And, it won't take an M.B.A. to undercut AT&T's calling card rates and still make buckets of money. All you need now are a few customers. Heck, I'll sign up with you. I sign up for everything. But first, a word of caution. Assuming your Asterisk server has web exposure on the Internet, you need to secure the admin and root passwords in this application whether you use it or not. To access the application, go to http://192.168.0.104/a2billing/ using the actual internal IP address of your Asterisk server. Log in as root with a password of myroot. Click on the ADMINISTRATOR tab in the left column and then click Show Administrator. Now click on the Edit button beside each of the two administrator accounts and change the passwords to something secure. If you really would like to learn more about it, documentation for the application is available here. And, if you decide to use the application, you'll need to uncomment the 6 actual dialplan lines in extensions_custom.conf and reload Asterisk:

;[custom-callingcard]
;exten => s,1,Answer
;exten => s,2,Wait,2
;exten => s,3,DeadAGI,a2billing.php
;exten => s,4,Wait,2
;exten => s,5,Hangup

Footnote: The missing A2Billing code from Asterisk@Home 2.1 has been added. You can read all about the problem here. There's also a pretty good step-by-step setup guide for Asterisk@Home here.

SugarCRM Contact Management. Asterisk@Home includes the best open source contact management application on the planet, SugarCRM. You access the application with a web browser: http://192.168.0.104/crm/ substituting the private IP address of your Asterisk box, of course. Specify admin for your username and password for your password. Whether you use the application or not, change the admin password. It's easy. Just click the Administrator link under Welcome admin. Then click the Change Password button. Complete documentation for the application is available here. If contact management is your thing, knock yourself out, and we'll talk to you next spring when you finish getting everything set up to run your business. It's a great product, but be prepared to invest lots of time in the project if you expect to use it productively.

Conflict Between ZAP cards and Fax Modules. For those using ZAP cards, be aware that there is a reported conflict with the fax modules. See this link for details and updates.

Incoming Fax Support. The NVfaxdetect software that we showcased back in December, 2005, now is included in Asterisk@Home 2.5. The major advantage of NVfaxdetect is that it works with SIP and IAX trunks as well as ZAP lines. Unfortunately, you'll still need to manually configure the Asterisk Management Portal to use it. Thanks to Thunderbird in Australia, it's pretty easy to make the necessary changes. First, enable faxing support. Go to AMP->Setup->General Settings and set Extension of Fax Machine to system. Then fill in your email address. Click the Submit Changes button to save your changes. This sets the default route for incoming faxes. If you want to specify different fax destinations for different DID trunks, then set up Inbound Routing using AMP and define the fax extension as system (instead of default) with an email address for delivery of the fax for each particular DID. You'll also need to make sure you have outbound email functioning on your Asterisk server (see above), or none of the rest of this matters. NVfaxdetect converts your incoming faxes to PDF documents and then emails them to you. So the next step is to get that conversion functionality working. Log in to your Asterisk server as root and type the following command: install-pdf. Now make a backup copy of your extensions.conf file: cp /etc/asterisk/extensions.conf /etc/asterisk/extensions.conf.bak. We're going to do some heavy editing of the extensions.conf file so be careful with your cutting-and-pasting: nano -w /etc/extensions.conf. When you're finished, save your changes and restart Asterisk: amportal restart.

Find and delete the entire [from-pstn-reghours] context. Replace it with the following:

[from-pstn-reghours]
exten => s,1,GotoIf($[${FAX_RX} = disabled]?from-pstn-reghours-nofax,s,1:2) ; if fax detection is disabled, then jump to from-pstn-nofax - else continue
exten => s,2,Answer
exten => s,3,Playtones(ring) ; play fake ring so caller doesn't wonder what's going on
exten => s,4,NVFaxDetect(4) ; detect faxes while playing ring sound - goes to "fax" extension if detected
exten => s,5,SetVar(intype=${INCOMING})
exten => s,6,Cut(intype=intype,-,1)
exten => s,7,GotoIf($[${intype} = EXT]?8:9) ; If INCOMING starts with EXT, then assume its an extension
exten => s,8,Goto(ext-local,${INCOMING:4},1)
exten => s,9,GotoIf($[${intype} = GRP]?10:11) ; If INCOMING starts with GRP, then assume its a ring group
exten => s,10,Goto(ext-group,${INCOMING:4},1)
exten => s,11,GotoIf($[${intype} = QUE]?12:13)
exten => s,12,Goto(ext-queues,${INCOMING:4},1)
exten => s,13,Goto(${INCOMING},s,1) ; not EXT or GR1 - it's an auto attendant
exten => fax,1,Goto(ext-fax,in_fax,1)
exten => h,1,Hangup


Find and delete the entire [from-pstn-afthours] context. Replace it with the following:

[from-pstn-afthours]
exten => s,1,GotoIf($[${FAX_RX} = disabled]?from-pstn-afthours-nofax,s,1:2) ; if fax detection is disabled, then jump to from-pstn-nofax - else continue
exten => s,2,Answer
exten => s,3,Playtones(ring) ; play fake ring so caller doesn't wonder what's going on
exten => s,4,NVFaxDetect(4) ; detect faxes while playing ring sound - goes to "fax" extension if detected
exten => s,5,SetVar(intype=${AFTER_INCOMING})
exten => s,6,Cut(intype=intype,-,1)
exten => s,7,GotoIf($[${intype} = EXT]?8:9) ; If INCOMING starts with EXT, then assume its an extension
exten => s,8,Goto(ext-local,${AFTER_INCOMING:4},1)
exten => s,9,GotoIf($[${intype} = GRP]?10:11) ; If INCOMING starts with GRP, then assume its a ring group
exten => s,10,Goto(ext-group,${AFTER_INCOMING:4},1)
exten => s,11,GotoIf($[${intype} = QUE]?12:13)
exten => s,12,Goto(ext-queues,${AFTER_INCOMING:4},1)
exten => s,13,Goto(${AFTER_INCOMING},s,1) ; not EXT or GR1 - it's an auto attendant
exten => fax,1,Goto(ext-fax,in_fax,1)
exten => h,1,Hangup


Find and delete the entire [ext-fax] context. Replace it with the following:

[ext-fax]
exten => s,1,Answer
exten => s,2,Goto(in_fax,1)
exten => in_fax,1,StopPlaytones ; you must do this or it will play ring sounds over your fax
exten => in_fax,2,GotoIf($[${FAX_RX} = system]?3:analog_fax,1)
exten => in_fax,3,Macro(faxreceive)
exten => in_fax,4,Hangup
exten => analog_fax,1,GotoIf($[${FAX_RX} = disabled]?3:2) ;if fax is disabled, just hang up
exten => analog_fax,2,DBGet(DIAL=DEVICE/${FAX_RX}/dial);
exten => analog_fax,3,Dial(${DIAL},20,d)
exten => analog_fax,4,Hangup
exten => out_fax,1,txfax(${TXFAX_NAME}|caller)
exten => out_fax,2,Hangup
exten => h,1,system(tiff2ps -2eaz ${FAXFILE} | ps2pdf - ${FAXFILE}.pdf)
exten => h,2,system(mime-construct --to ${EMAILADDR} --subject "Fax from ${CALLERIDNUM} ${CALLERIDNAME}" --attachment ${CALLERIDNUM}.pdf --type application/pdf --file ${FAXFILE}.pdf)
exten => h,3,system(rm ${FAXFILE} ${FAXFILE}.pdf)
exten => h,4,Hangup()

Be aware that NVfaxdetect can be a bit quirky. You may need to fine tune the timing mechanism in the actual NVfaxdetect(4) lines above. If 4 is too long or too short a delay to detect a fax call, try 10 or nothing at all. 10 works for us. 4 works in Australia apparently. If you need more details, read our original article on this topic. It also explains how to get all of this working with the Nerd Vittles Stealth AutoAttendant if you're using it.

Asterisk Recording Interface. A new web-based utility for managing your voicemail now is included in AMP and can be accessed by clicking Voicemail & Recordings on the initial AMP screen at the IP address of your Asterisk system. It also can be accessed at http://Asterisk-IP-address/recordings/. To log in to the Asterisk Recording Interface (ARI), just enter an extension number on your Asterisk system and the password for that extension. From the web interface, you can manage your voicemail messages including playing them back, you can review the call log to this extension, and you can set your voicemail password as well as your desired setup for recording calls by setting the call monitor defaults for this extension. Very cool!

Other Out-of-the-Box Utilities. Asterisk@Home 2.5 comes bundled with a number of additional utilities. Here are some of them. You can retrieve the current time by dialing *60. If the time is wrong, you can reset your default time zone by logging into your server as root and typing config. A current weather report for New York is available by dialing *61. You can change the city by following our previous tutorial which is available here. Something has come unglued in the festival script, however, because there is a noticable 10-second delay between each line of text that is read now. To set up a wakeup call from any extension, dial *62. To determine the phone number of any extension, just dial *65. You can use the default MeetMe conferencing system from any or all of your extensions by dialing 8 plus the number of an existing extension. Additional conference rooms can be added by editing meetme_additional.conf. Finally, you can record customized voice prompts for your system by dialing 5678 from any extension. Before this will work, edit the extensions_custom.conf file (AMP->Maintenance->Config Edit->extensions_custom.conf) and uncomment the seven lines shown below which are located at the bottom of the file. Just remove the leading semicolons. You'll also need to uncomment the following line near the top of file at the beginning of the [from-internal-custom] context: ;include => custom-recordme.

;[custom-recordme]
;exten => 5678,1,Wait(2)
;exten => 5678,2,Record(/tmp/asterisk-recording:gsm)
;exten => 5678,3,Wait(2)
;exten => 5678,4,Playback(/tmp/asterisk-recording)
;exten => 5678,5,Wait(2)
;exten => 5678,6,Hangup

Once you make a recording, it needs to be moved to /var/lib/asterisk/sounds/custom with a new filename.gsm, e.g. mv /tmp/asterisk-recording.gsm /var/lib/asterisk/sounds/custom/hihoney.gsm. Then change the ownership of the file: chown asterisk:asterisk /var/lib/asterisk/sounds/custom/hihoney.gsm. You then can play the recording with a line like this in your dialplan: exten=>s,1,Playback(custom/hihoney) where hihoney is the name you assigned to the recording without its .gsm extension.

AAH Web Facelift. Last, but not least, the folks at KennonSoft have posted a new self-configuring AAH web interface (see inset). It automatically chooses icons to match the applications installed on your system. If you like it, here's how to install it. Log into your server as root and issue the following commands:

cd /var/www/html
wget http://www.kennonsoft.org/projects/asterisk/admin-ui.tar
tar -xvf admin-ui.tar
rm -f admin-ui.tar
mv index.html index2.html


NOTE: It's been reported that there may be a display formatting bug with IE 6. Line 2 of the code above should begin with wget.

In order for the bottom row of buttons to appear, you must install WebMin (installation instructions above), AsteriDex, and Phone Reminders 2.5. If you'd like to use our AsteriDex RoboDialer, install it from the link in this sentence and the icon will then appear. If you've moved your AsteriDex application to a directory different than /var/www/html/asteridex, make the necessary adjustment to ./asteridex in line 15 of the index.php file. To download and install the Telephone Reminders software, read our Telephone Reminders 2.5 update tutorial. Once its installed, the Telephone Reminders icon will appear when you access the main web page on your Asterisk server.

Free Directory Assistance Service. For those in the U.S. that just can't live without Directory Assistance, write this number down or add it to your Asterisk dialplan for free directory assistance calls in the United States: 1-800-411-6387. It's also a free VoIP call with the providers listed below once you set up an account with one of them. You can read our reviews of these providers here. Assuming you have an account, just add ONE of the following sets (that match the provider with whom you have set up an account) to the [from-internal-custom] context in extensions_custom.conf:


exten => 411,1,Dial(IAX2/goiax/18004116387)   ; GoIAX Free Call
exten => _1NXX5551212,1,Dial(IAX2/goiax/18004116387)
exten => _NXX5551212,1,Dial(IAX2/goiax/18004116387)

exten => 411,1,Dial(IAX2/teliax/18004116387)  ; Teliax Free Call
exten => _1NXX5551212,1,Dial(IAX2/teliax/18004116387)
exten => _NXX5551212,1,Dial(IAX2/teliax/18004116387)


Some Recent Nerd Vittles Articles of Interest...

Want a rock-solid PBX at a rock-bottom price: free! Well, it's almost Ground Hog's Day so here we go again! Asterisk@Home 2.4 has hit the street because of a serious bug-fix release of Asterisk®. Now you get version 1.2.3 of Asterisk, and you also get the latest and greatest version of Linux, CentOS 4.2; the latest Festival Speech Engine (1.96); the latest version of the Asterisk Management Portal (1.10.010); the Flash Operator Panel (version 0.24); Open A2Billing; Digium card auto-configuration; NVfaxdetect support; loads of AGI scripts including weather forecasts and wakeup calls; xPL support; the SugarCRM Contact Management System with the Cisco XML Services interface and Click-to-Dial support; plus lots more. And, yes, it still fits on a single CD! Note: A new version of Asterisk (1.2.4) was released yesterday to fix a serious memory leak so you can expect yet another version of Asterisk@Home and yet another soup-to-nuts tutorial shortly. Simply stated, don't put this version into production without at least implementing the Bleeding Edge 1.2.4 upgrade at the end of this article ... but we're making progress.

Editor's Note: This version of Asterisk@Home has been superceded. For the latest tutorial on or after March 13, click here.

The installation process is pretty straightforward. You download the 2.4 ISO image from here, burn a CD (click here if you need a refresher course), use an old clunker PC or a $200 WalMart special (see inset), insert the CD you made, plug your machine into the Internet and turn it on. Then watch while Asterisk@Home loads CentOS/4.2 and all the Asterisk and Linux goodies imaginable: Apache, SendMail, Comedian Mail, SugarCRM, MySQL, PHP, phpMyAdmin, SSH, Bluetooth, the Asterisk Management Portal, the Flash Operator Panel, Call Detail Reporting, and on and on. We've covered how to use most of the Linux products in our Mac HOW-TO's (see sidebar), and they work exactly the same way with Asterisk@Home so keep reading. And, yes, this install will reformat (aka ERASE) your hard disk before it begins, but it now warns you first.

Loading CentOS/4 and Asterisk 1.2.3. Here's how the 2.4 install went for us, and we'll walk you through getting everything set up so that it can be used as a production server. Once the install begins, you can expect to eat up about 25 minutes with the CentOS 4.2 install. The install CD then will eject itself, reboot the system, and begin the Asterisk compile and installation. That takes about 25 more minutes to complete.

Securing Your Passwords. When it's finished and reboots, log in as root with password as your password. Type help-aah for a listing of the five passwords that need to be changed. Change them all NOW!

passwd
passwd admin
passwd-maint
passwd-amp
passwd-meetme


Getting the Latest CentOS Updates. Once your system is secure, load all of the application updates for CentOS 4.2. There now are over 50 updates and installs so be patient. The update command to issue is yum -y update.

Activating Bluetooth Support. Once the updates are completed, activate Bluetooth support if you plan to use it with our Follow-Me Phoning proximity detection application. Run setup, down arrow to System Services, press ENTER, down arrow to bluetooth and press the space bar, tab to OK, press ENTER, tab twice to Quit and press ENTER.

Rebuilding Zaptel. First, reboot your system: shutdown -r now. Because a new version of the kernel is installed as part of the yum update, you'll need to rebuild support for ZAP devices. Log in as root and type the following command: rebuild_zaptel. Then reboot your system: shutdown -r now. Now log in as root again and type genzaptelconf. Reboot once more and you're all set to go: shutdown -r now. You only need to rebuild Zaptel when there is a kernel update as there was with this yum update.

Simplifying SSH. If you're going to be connecting to other servers from your new Asterisk@Home 2.4 system using SSH or SCP, then build your new RSA key pair now. This lets you use SSH and SCP (secure copy) without having to enter a password each time. You can also automate backups and proximity detection scripts as we've explained previously here. Log in to your new Asterisk@Home 2.4 server as root. From the command prompt, issue the following command: ssh-keygen -t rsa. Press the enter key three times. You should see something similar to the following. The file name and location in bold below is the information we need:

Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
1d:3c:14:23:d8:7b:57:d2:cd:18:70:80:0f:9b:b5:92 root@asterisk1.local

Now copy the file in bold above to your other Asterisk servers, Linux machines, and Macs. There's probably a way on PCs as well, but I've given up on that platform particularly after Sony's latest security stunt so you're on your own there. From your Asterisk@Home 2.4 server using SCP, the command should look like the following (except use the private IP address of each of your other Asterisk or Linux servers instead of 192.168.0.104). Provide the root password to your other servers (one at a time) when prompted to do so.

scp /root/.ssh/id_rsa.pub root@192.168.0.104:/root/.ssh/authorized_keys

On a Mac running Mac OS X, the command would look like this (using your username and your Mac's IP address, of course):

For user access only: scp /root/.ssh/id_rsa.pub wardmundy@192.168.0.104:/Users/wardmundy/.ssh/authorized_keys
For full root access: scp /root/.ssh/id_rsa.pub root@192.168.0.104:/var/root/.ssh/authorized_keys


Once the file has been copied to each server, try to log in to your other server from your Asterisk@Home 2.4 server with the following command using the correct destination IP address, of course:

ssh root@192.168.0.104

You should be admitted without entering a password. If not, repeat the drill or read the complete article and find where you made a mistake. Now log out of the other server by typing exit.

Installing WebMin. We don't build Linux systems without installing WebMin, the Swiss Army knife of the Linux World. You can use it to start and stop services, check logs, adjust startup scripts, manage cron jobs, babysit your SendMail server, and many, many other tasks that are downright painful without it. If you ever need help from others, WebMin is a great tool for letting others help you.

There are lots of ways to install WebMin. We prefer the easy way which is to issue the following commands at a Linux prompt after logging in as root. Note: WebMin updates come out all the time. If you want to be sure you start with the latest and greatest version, go to their web site first and write down the number of the current version. Then substitute it below when issuing these commands. Note that there is a new version of WebMin since our previous article on Asterisk@Home 2.2 was published.

cd /root
mkdir webmin
cd webmin
wget http://internap.dl.sourceforge.net/sourceforge/webadmin/webmin-1.260-1.noarch.rpm
rpm -Uvh webmin*


WebMin runs its own web server on port 10000. To start WebMin, issue this command: /etc/webmin/start. You access it with a web browser pointed to the IP address of your Asterisk box at that port address, e.g. http://192.168.0.108:10000. The login name is root. Then type in your root password and press enter. The main WebMin screen will display. We really don't want the WebMin server starting up each time the OS reboots so do the following. Once you're logged in to WebMin, choose System->Bootup and Shutdown and then click on webmin. Click the No button beside Start at boot time, and then click the Save button. Before we forget, we need to also make one change to the new Asterisk@Home configuration to avoid problems down the road. The default RTP listening ports for Asterisk@Home are set to 10000 to 20000 so there's a conflict on port 10000 with WebMin. Log in as root and, using an editor, call up the rtp.conf file: nano /etc/asterisk/rtp.conf. Now change the rtpstart port from 10000 to 10001 and save the change: Ctrl-W, Y, and press Enter. Then restart Asterisk: amportal restart. Finally, to stop WebMin when you're finished using it, issue this command: /etc/webmin/stop. You can start it any time you need it, and then use a web browser to access it. But there's no need to consume processing resources running a second web server when you're not using it.

IP Configuration for Asterisk. We need a consistent IP address or domain name both on your internal network and externally if you expect to receive incoming calls reliably. There are three pieces to the IP configuration: (1) setting the internal IP address of your Asterisk server, (2) configuring an external qualified domain name which will always point to your router/firewall, and (3) configuring your router to transfer incoming Asterisk packets to your Asterisk server. Log into your server as root using your new password. Now type ifconfig eth0 (that's "e-t-h-zero") then enter, and write down both your inet addr and your HWaddr on the Ethernet 0 interface, eth0. Inet addr is the internal IP address of your Asterisk box assigned by your DHCP server (i.e. your router/firewall). HWAddr is the MAC address of your Asterisk server's eth0 network card. To assure a consistent internal IP address, you can either configure your router/DHCP server to make certain that it always hands out this same address to your Asterisk machine, or you can manually configure an IP address for this machine which is not in the range of addresses used by your DHCP server. Almost all routers now make it easy to preassign DHCP addresses so we prefer option 1. It's generally under the tab for LAN IP Setup and is generally called something like Reserved IP table. Just add an entry and call it Asterisk PBX and specify the IP address and MAC address that you wrote down above. Now each time you reboot your Asterisk server, your router will assign it this same IP addreess. To assure a consistent external address is a little trickier. Unless you have a static (fixed) IP address, you'll want to use a Dynamic DNS service such as dyndns.org and configure your router to always advertise its external IP address to dyndns.org. DynDNS.org will take care of revising the IP address associated with your domain name when your ISP changes your dynamic IP address. Then you can configure your VoIP provider account using your fully-qualified dyndns.org domain name, e.g. windswept.dyndns.org provides access to our beach house network even though Time Warner cable hands out dynamic IP addresses which change from time to time. Finally, you'll need to log into your router and redirect certain incoming packets to the internal IP address of your Asterisk machine. If you want external access to the Apache web server on your Asterisk machine, then map TCP port 80 to the internal IP address of your Asterisk system. For WebMin external access, map TCP port 10000 to your Asterisk system. If you want remote access to your Asterisk system via SSH, then map TCP port 22 to the internal IP address of your Asterisk system. If you want external IP phones or other Asterisk servers to be able to communicate with your Asterisk system, then map the following UDP port ranges to the internal IP address of your Asterisk system:

SIP 5004-5082
RTP 10001-20000
IAX 4569

For more details, read our article on the subject.

Basic System Configuration. To get a basic Asterisk system up and running, you only need to do a few things. First, you need an Outbound Trunk to actually deliver your outbound calls to Plain Old Telephones (POTS). Second, you need to configure an Outbound Route to tell Asterisk which trunk to use to deliver your outbound calls to the intended recipients. Third, you need to configure at least one extension so that you can plug in some sort of telephone instrument to place and receive calls using your new Asterisk server. The phone can be a hardware device such as an IP telephone or a POTS phone, or it can be a software device such as a free IP softphone. The advantage of IP telephones and softphones is that they require no additional hardware besides your Asterisk server. A POTS phone or our favorite, a 5.8GHz wireless phone system with up to 10 extensions, both require an additional piece of hardware although some of the newer IP wireless phones give you the best of all worlds (see inset). To use a POTS phone, the hardware required is either a circuit board with an FXS port or an external black box (ATA device) such as a Sipura SPA-1001. If you also want to connect your Ma Bell phone line to your Asterisk server, then you need a circuit board with an FXO port or an external black box (ATA device) such as a Sipura SPA-3000. Our favorite is the SPA-3000 because it has both FXO and FXS ports in a box the size of a pack of cigarettes for under $100.

Setting Up An Outbound Trunk. You configure an outbound trunk using your web browser and the Asterisk Management Portal (AMP). But first, you have to have an account with a service provider. This is the company that carries your calls from your Asterisk server to plain old phones in your neighbor's house or Aunt Betty's in California. With VoIP, it's a good idea to have two providers, but today let's start with one. We'll save you some time and lots of money. Unless you make substantial international calls regularly, use TelaSIP/VoipExpress. If you want to know why, read the full article here. Or just try a free call for yourself using our server. Basically, $5.95 a month gets you a local number in your choice of area code with free incoming calls, and 2¢ per minute for outbound calls to anywhere in the U.S. $9.95 a month buys you all of that plus free outbound calls in the area code of the phone number you select. $14.95 a month gets you a number in the area code of your choice with unlimited incoming calls and unlimited outbound calls to anywhere in the U.S. There are no sneaky add-on fees and no obnoxious terms of service. Just be sure to tell them to configure your account for use with Asterisk. They also have very reasonable business plans. If, on the other hand, you'd prefer to try another provider, take a look at our easy setup guides for most of the major VoIP providers here.

Once you have your account name and password, point your web browser to the IP address of your new Asterisk@Home 2.4 server and log in as maint with the password you selected. Then choose AMP->Setup->Trunks->Add SIP Trunk assuming you're using TelaSIP. NOTE to existing users: if you already have an Asterisk server using your TelaSIP account, don't use the same account at the same time on your new Asterisk@Home 2.4 server! Plug in the CallerID number you were assigned for your account. Set Maximum Channels to 2. For the Dial Rules, use the following (substituting your local area code for 404 below):

1|NXXNXXXXXX
NXXNXXXXXX
404+NXXXXXX

In the Outgoing Settings section, name your trunk telasip-gw. Then enter the following for the Peer Details using your own account name for username and fromuser and using your own assigned password for secret:

context=telasip-in
dtmfmode=rfc2833
fromuser=youraccountname
host=gw3.telasip.com
insecure=very
secret=yourpassword
type=peer
username=youraccountname

Leave the Incoming Settings section blank, and in the Registration String, enter the following using your account name and password:

youraccountname:yourpassword@gw3.telasip.com

Click the Submit Changes button, and then click the red bar to reload Asterisk. Now we need to add the context which will actually process the incoming calls from TelaSIP. Choose AMP->Maintenance->Config Edit->extensions_custom.conf and add the following code at the bottom of the file substituting your new phone number for 4041234567. Save the file and reload Asterisk to finish the setup. See the Comments to this post for a more versatile approach which will let you use your TelaSIP line for Ring Groups.

[telasip-in]
exten => 4041234567,1,NoOp(Incoming call on TelaSIP #4041234567)
exten => 4041234567,2,Dial(local/200@from-internal,20,m)
exten => 4041234567,3,VoiceMail(200@default)
exten => 4041234567,4,Hangup


Configuring an Outbound Route. Now we need to tell Asterisk where to send our outbound calls when we dial them. To get started, we'll just send everything to the TelaSIP trunk we just configured. Choose AMP->Setup->Outbound Routing->Add Route. For Route Name, use Outside. Leave the password blank. For Dial Patterns, enter the following:

NXXXXXX
NXXNXXXXXX
1NXXNXXXXXX

For the Trunk Sequence, choose SIP->telasip-gw from the drop-down list. Then click Submit Changes. Be sure you also delete the sample outbound route that came with the install, or your outbound calls may go nowhere. Finally, click the red bar to save your new Outbound Routing setup.

Configuring an Extension. You have to have an extension to make and receive calls with Asterisk@Home so let's build one. Choose AMP->Setup->Extensions->SIP to begin. For the Extension Number, let's use 200 to keep things simple. For the Display Name, make up something that tells where this phone will be located, e.g. Kitchen. For the Outbound CID, use 200. For secret, make up a password for this extension. For Voicemail and Directory, choose Enabled. Plug in your password again. Type in your email address, and, if you want to also be paged when you get a new voicemail, type in a pager email address. Click the Yes button beside Email Attachment, and leave the other settings alone. Now click the Submit button and then click the red bar to save your changes and reload Asterisk.

Downloading a Free Softphone to Test Asterisk. Unless you already have an IP phone, the easiest way to get started and make sure everything is working is to install an IP softphone. You can download a softphone for Windows, Mac, or Linux from CounterPath. Or download the pulver.Communicator. Both are free! Just install and then configure with the IP address of your Asterisk@Home 2.4 server. For username and password, use your extension number and password from above. Once you make a few test calls, don't waste any more time. Buy a decent SIP telephone. We think the best value in the marketplace with excellent build quality and feature set is the under $100 GrandStream GXP-2000. It has support for four lines, speaks CallerID numbers, has a lighted display, and can be configured for autoanswer with a great speakerphone. Short of paying three times as much, that's as good as desktop phones get. If you want to use Asterisk throughout your home, buy a good 5.8GHz wireless phone system with plenty of extensions (our two favorites are shown in the insets below) and then purchase an SPA-3000 to connect up both your home phone line and all your cordless phones. Our tutorial will show you how. The final option is to use a wireless IP phone which is the best of both worlds, a cordless phone that talks IP telephony without an ATA blackbox such as the Uniden UIP1868 (see also insets above).

Activating Email Delivery of VoiceMail Messages. When you're out and someone leaves you a voicemail message, Asterisk@Home will let you forward that voicemail message to your email address as a .wav file which can be played within most email client software. Or you can have Asterisk@Home send an instant message to your cell phone or pager telling you who called, what their phone number was, and how long a voicemail message the person left for you. Or you can do both. In addition, you can tell Asterisk@Home whether to delete the voicemail from your Asterisk server after sending it to your email account. In short, you now can manage all of your incoming email and voicemail from a single place, your email client. In order to send out emails from your Asterisk@Home server, you'll need to make a few changes. First, make this adjustment to the /etc/hosts file on the server. Since anonymous emails are blocked by most ISPs, you'll need a fully-qualified domain name for your server. If you don't have your own domain, the easiest alternative is to use the fully-qualified domain name that your ISP assigns to the IP address for your broadband connection. Don't forget to update it when your ISP changes your IP address! To find out what your fully-qualified domain name is, go to a command prompt on your Asterisk server and type: nslookup 123.456.789.001 substituting your public IP address for the preceding numbers. Then write down the name entry without the trailing period. Now edit the hosts file: nano /etc/hosts. Move the cursor to the second line which reads 127.0.0.1 asterisk1.local , and then move the cursor over the first letter of the first domain name shown, usually asterisk1.local. Now type in the fully-qualified domain name you previously wrote down and add a space after your entry. Don't erase the existing entry! Save your settings: Ctrl-X, y, enter. Now restart network services on your Asterisk machine: service network restart. Next, you need to modify the email message which delivers your voicemails so that it includes your fully-qualified domain name. Don't do this in AMP, or you'll mess up the formatting of the email message. You can download a fresh copy here if you need it. Instead, use nano: nano -w /etc/asterisk/vm_email.inc. Press Ctrl-W, type /cgi, and press the enter key. You're now positioned where you need to type either the fully-qualified domain name for your Asterisk server or the private IP address if you only want to read your emails from behind your firewall. When you start typing, the text display is going to jump all over the place because of word wrap. Don't freak out. You haven't messed anything up. Once you complete your entry, don't erase or change anything else. Save the file: Ctrl-X,Y, then enter. Now go into AMP->Maintenance->Config Edit->vm_general.inc with a web browser. Change the serveremail entry to an email name at the fully qualified domain you used in your /etc/hosts file above. Then save your configuration and restart Asterisk. If you continue with this setup and still don't receive emails, here's another configuration change that is sometimes necessary. On the Asterisk terminal, log in as root. Switch to the directory where the SendMail configuration file is stored: cd /etc/mail. Make a backup of the config file: cp sendmail.cf sendmail.cf.bak. Then issue the following command: echo CGasterisk.dyndns.org >> sendmail.cf. Substitute the actual domain name of your Asterisk server for asterisk.dyndns.org, but be sure it's preceded by CG with no intervening spaces.Then reboot your server and try again: shutdown -r now. Finally, if your ISP doesn't permit downstream mail servers (that's you), then take a look at this link which will show you how to designate your ISP as your SMTP smart host using SendMail.

To configure the voice mail forwarding options, go into the Setup tab of the Asterisk Management Portal using a web browser. Click on Extensions and then click on an extension you already have configured. In the Voicemail and Directory section of the form, enter either (or both) your email address and your pager or cellphone's text messaging address. To email the voicemails as attachments, just click Yes beside Email Attachment. To delete the voicemail message from your voicemail inbox after sending it to your email address (not recommended until you first get it working correctly), click Yes beside Delete Vmail. For those using a dynamic IP address with phones at remote locations connecting to your Asterisk server, we'll show you how to automate the process of changing your Asterisk server's IP address in a future column.

Call Recording Fixed. This update fixes inbound and outbound call recording which now works reliably. You can set your preferences for call recording when you set up each extension. The recordings are stored in /var/spool/asterisk/monitor unless you set other preferences in agents.conf.

Paging Fixed. If you want to use paging with your Asterisk system, the sound card problems in Asterisk@Home 2.1 and Asterisk 1.2 have been resolved. Review this posting on SourceForge for additional details. It now works with full and half-duplex sound cards. Thanks, Tracy!

Wakeup Calls Good News & Bad News. The good news is that Asterisk@Home 2.4 includes a new version of the Wakeup Call program, and the default setup works. The bad news is that the "annoy" option which is supposed to force the user to key in a number to prove they're awake still doesn't work. And, the wakeup call application now uses a different method of scheduling wakeup calls which broke our TeleYapper and Telephone Reminder applications. Mental note for would-be developers, don't rely on someone else's code to keep your code working reliably. This is especially true in the open source marketplace. Everyone is full of new ideas, and they don't necessarily stop to think of the impact the improvements will have on other folks' applications. We'll have new versions of our applications ... soon. Bear with us while we hold off for Asterisk@Home 2.5 just so we don't have to repeat the drill again.

Adjusting Call Parking Extensions. Traditionally, pressing the pound key (#) and dialing extension 700 parked a call on Asterisk@Home systems and notified you of the parked extension. The call then could be picked up by dialing the parked extension in the range of 701 to 799 from any extension on your system. The new setup is to press # and dial 70 to park a call and 71-79 to pick it up. If you prefer the old setup, you'll need adjust the settings in features.conf. Go to AMP->Maintenance->Config Edit->features.conf and make it look like this:

[general]
parkext => 700 ; What ext. to dial to park
parkpos => 701-799 ; What extensions to park calls on
context => parkedcalls ; Which context parked calls are in


Directory Lookup Fixed. Pressing the pound key (#) from any phone connected to your Asterisk server now calls up a directory lookup function using the Asterisk Management Portal (AMP).

Max Channels Bug Remains. A bug has been reported because of a deprecated command that makes Asterisk@Home's calculation of maximum channels invalid. To fix it, goto AMP->Maintenance->Config Edit->extensions.conf->macro-dialout-trunk and comment out line s,7 so that it looks like this:

;exten => s,7,CheckGroup(${OUTMAXCHANS_${ARG1}})

Then insert a new line s,7 just below it which looks like this:

exten => s,7,GotoIf($[ ${GROUP_COUNT()} > ${OUTMAXCHANS_${ARG1}} ]?108)

Then click the Update button and reload Asterisk to activate the change.

Syntax Error in extensions.conf Causes Failed Incoming Calls. One of our readers has discovered a nasty little bug in extensions.conf that will cause some incoming calls to fail. Edit extensions.conf->macro-dial and change line s,22 as follows. Then reload Asterisk.
Before:

exten => s,22,GotoIf($[$[${HuntMembers} >= 1]?30 )

After:

exten => s,22,GotoIf($[$[${HuntMembers}] >= 1]?30 )


Tweaking SIP.conf. There are a few changes we recommend you make in the [general] context of the sip.conf file. Using the Asterisk Management Portal, go to AMP->Maintenance->Config Edit->sip.conf. It's a good idea to include your actual CallerID number of your default outbound trunk here instead of Default. We also recommend that you add allow=gsm just below the existing allow=alaw line in the file. You may also want to include progressinband=yes which assures that callers will hear ring tones when placing calls even if your provider doesn't provide them. This is a fairly common complaint with BroadVoice in particular. Don't forget to reload Asterisk once you make these changes: AMP->Setup->Incoming Calls->Submit Changes and then click the Red bar.

Connecting Remote Extensions or a Remote Asterisk Server. If you plan to connect remote extensions to your Asterisk server, then add the following entries to sip.conf above using your own fully-qualified domain name and the first three octets of the private IP address of your Asterisk server:

externip = myasteriskbox.dyndns.org
localnet=192.168.0.0/255.255.255.0
nat=yes

You'll also either need to define your Asterisk server as a DMZ device in your firewall setup, or you can open the following UDP ports and map all of them to the private IP address of your Asterisk box: 4569, 5004-5082, and 10000-20000. If you only hear half of a conversation with a remote extension, it's usually a NAT problem meaning you probably forgot to do the port mapping drill. We plan to cover remote extensions and interconnecting Asterisk servers in more detail in a future column so stay tuned. In the meantime, if you have a dynamic DNS connection that changes your IP address regularly and you don't want to wrestle with manually updating your Asterisk server each time there's a change, just download chandave's sip reload script and copy it to your /etc/asterisk directory. Then execute the following commands while logged in as root:

chown asterisk:asterisk /etc/asterisk/sip_reload.sh
export EDITOR=nano
crontab -e
00,05,10,15,20,25,30,35,40,45,50,55 * * * * root /bin/sh /etc/asterisk/sip_reload.sh >/dev/null 2>&1

Save your crontab addition in the usual nano way, and you're all set: Ctrl-X, y, then enter. This clever little script will make sure your Asterisk server always knows its own IP address regardless of how often your ISP changes it. And you'll never lose inbound connectivity from remote extensions or servers for over 5 minutes. If you'd like to read the full discussion, visit this link on the Voxilla forum.

Managing Incoming Calls. For long time readers of this column, you already know that our recommended strategy for handling incoming calls is to set up a simple Stealth AutoAttendant. Basically, this is a welcome message that greets your callers and then transfers them to an extension or ring group of your choice. The advantage of this approach is that it also lets callers like you press buttons to navigate through various options on your Asterisk system without advertising them to the public at large. If you're just getting started with Asterisk, you can read all about setting up a Stealth AutoAttendant here. If you'd prefer to manage your incoming calls with AMP, you'll still need to fix the [from-sip-external] context in the extensions.conf file, or all your incoming SIP and IAX calls will ring busy. To fix it, choose AMP->Maintenance->Config Edit->extensions.conf->from-sip-external. Comment out all the lines in the existing file by adding a semicolon at the beginning of each line. Then add the following line, save your changes, and reload Asterisk.

exten => _.,1,Goto(from-pstn-timecheck,s,1)


New Custom Speed Dialing. Asterisk@Home 2.4 has a built-in speed dialing utility. The reserved speed dial numbers are 300 to 399. Adding a number to your speed dial list is easy. Just pick up an extension and dial 300-3xx-6781234567 where 3xx is the speed dial code you want to create and 6781234567 is the phone number you want dialed when you enter the speed dial code. Just make sure you enter the number to be called in a format that is supported by your Asterisk dialplan, i.e. if outside calls need to be preceded by a 1 or a 9, then the number should be entered in a matching format. You can look up speed dial numbers by dialing an asterisk followed by the 3-digit speed dial code, e.g. *301 would tell you the number stored in speed dial 301. If you need additional flexibility with both web browser and phone access as well as 1 to 5-digit speed dial codes, download our free AsteriDex robodialer.

Fixed A2Billing: Asterisk Calling Card Platform. This web-based application allows you to generate and issue calling cards to individuals so that they can place calls remotely through your Asterisk server. If you've always wanted to be just like AT&T, here's your Big Chance! There's very little that you can do with an AT&T calling card that can't be done as well or better by you using A2Billing. And, it won't take an M.B.A. to undercut AT&T's calling card rates and still make buckets of money. All you need now are a few customers. Heck, I'll sign up with you. I sign up for everything. But first, a word of caution. Assuming your Asterisk server has web exposure on the Internet, you need to secure the admin and root passwords in this application whether you use it or not. To access the application, go to http://192.168.0.104/a2billing/ using the actual internal IP address of your Asterisk server. Log in as root with a password of myroot. Click on the ADMINISTRATOR tab in the left column and then click Show Administrator. Now click on the Edit button beside each of the two administrator accounts and change the passwords to something secure. If you really would like to learn more about it, documentation for the application is available here. And, if you decide to use the application, you'll need to uncomment the 6 actual dialplan lines in extensions_custom.conf and reload Asterisk:

;[custom-callingcard]
;exten => s,1,Answer
;exten => s,2,Wait,2
;exten => s,3,DeadAGI,a2billing.php
;exten => s,4,Wait,2
;exten => s,5,Hangup

Footnote: The missing A2Billing code from Asterisk@Home 2.1 has been added. You can read all about the problem here. There's also a pretty good step-by-step setup guide for Asterisk@Home here.

SugarCRM Contact Management. Asterisk@Home includes the latest and greatest version of the best open source contact management application on the planet, SugarCRM. You access the application with a web browser: http://192.168.0.104/crm/ substituting the private IP address of your Asterisk box, of course. Specify admin for your username and password for your password. Whether you use the application or not, change the admin password. It's easy. Just click the Administrator link under Welcome admin. Then click the Change Password button. Complete documentation for the application is available here. If contact management is your thing, knock yourself out, and we'll talk to you next spring when you finish getting everything set up to run your business. It's a great product, but be prepared to invest lots of time in the project if you expect to use it productively.

Incoming Fax Support. The NVfaxdetect software that we showcased back in December, 2005, now is included in Asterisk@Home 2.4. The major advantage of NVfaxdetect is that it works with SIP and IAX trunks as well as ZAP lines. Unfortunately, you'll still need to manually configure the Asterisk Management Portal to use it. Thanks to Thunderbird in Australia, it's pretty easy to make the necessary changes. First, enable faxing support. Go to AMP->Setup->General Settings and set Extension of Fax Machine to system. Then fill in your email address. Click the Submit Changes button to save your changes. This sets the default route for incoming faxes. If you want to specify different fax destinations for different DID trunks, then set up Inbound Routing using AMP and define the fax extension as system (instead of default) with an email address for delivery of the fax for each particular DID. You'll also need to make sure you have outbound email functioning on your Asterisk server (see above), or none of the rest of this matters. NVfaxdetect converts your incoming faxes to PDF documents and then emails them to you. So the next step is to get that conversion functionality working. Log in to your Asterisk server as root and type the following command: install-pdf. Now make a backup copy of your extensions.conf file: cp /etc/asterisk/extensions.conf /etc/asterisk/extensions.conf.bak. We're going to do some heavy editing of the extensions.conf file so be careful with your cutting-and-pasting: nano -w /etc/extensions.conf. When you're finished, save your changes and restart Asterisk: amportal restart.

Find and delete the entire [from-pstn-reghours] context. Replace it with the following:

[from-pstn-reghours]
exten => s,1,GotoIf($[${FAX_RX} = disabled]?from-pstn-reghours-nofax,s,1:2) ; if fax detection is disabled, then jump to from-pstn-nofax - else continue
exten => s,2,Answer
exten => s,3,Playtones(ring) ; play fake ring so caller doesn't wonder what's going on
exten => s,4,NVFaxDetect(4) ; detect faxes while playing ring sound - goes to "fax" extension if detected
exten => s,5,SetVar(intype=${INCOMING})
exten => s,6,Cut(intype=intype,-,1)
exten => s,7,GotoIf($[${intype} = EXT]?8:9) ; If INCOMING starts with EXT, then assume its an extension
exten => s,8,Goto(ext-local,${INCOMING:4},1)
exten => s,9,GotoIf($[${intype} = GRP]?10:11) ; If INCOMING starts with GRP, then assume its a ring group
exten => s,10,Goto(ext-group,${INCOMING:4},1)
exten => s,11,GotoIf($[${intype} = QUE]?12:13)
exten => s,12,Goto(ext-queues,${INCOMING:4},1)
exten => s,13,Goto(${INCOMING},s,1) ; not EXT or GR1 - it's an auto attendant
exten => fax,1,Goto(ext-fax,in_fax,1)
exten => h,1,Hangup


Find and delete the entire [from-pstn-afthours] context. Replace it with the following:

[from-pstn-afthours]
exten => s,1,GotoIf($[${FAX_RX} = disabled]?from-pstn-afthours-nofax,s,1:2) ; if fax detection is disabled, then jump to from-pstn-nofax - else continue
exten => s,2,Answer
exten => s,3,Playtones(ring) ; play fake ring so caller doesn't wonder what's going on
exten => s,4,NVFaxDetect(4) ; detect faxes while playing ring sound - goes to "fax" extension if detected
exten => s,5,SetVar(intype=${AFTER_INCOMING})
exten => s,6,Cut(intype=intype,-,1)
exten => s,7,GotoIf($[${intype} = EXT]?8:9) ; If INCOMING starts with EXT, then assume its an extension
exten => s,8,Goto(ext-local,${AFTER_INCOMING:4},1)
exten => s,9,GotoIf($[${intype} = GRP]?10:11) ; If INCOMING starts with GRP, then assume its a ring group
exten => s,10,Goto(ext-group,${AFTER_INCOMING:4},1)
exten => s,11,GotoIf($[${intype} = QUE]?12:13)
exten => s,12,Goto(ext-queues,${AFTER_INCOMING:4},1)
exten => s,13,Goto(${AFTER_INCOMING},s,1) ; not EXT or GR1 - it's an auto attendant
exten => fax,1,Goto(ext-fax,in_fax,1)
exten => h,1,Hangup


Find and delete the entire [ext-fax] context. Replace it with the following:

[ext-fax]
exten => s,1,Answer
exten => s,2,Goto(in_fax,1)
exten => in_fax,1,StopPlaytones ; you must do this or it will play ring sounds over your fax
exten => in_fax,2,GotoIf($[${FAX_RX} = system]?3:analog_fax,1)
exten => in_fax,3,Macro(faxreceive)
exten => in_fax,4,Hangup
exten => analog_fax,1,GotoIf($[${FAX_RX} = disabled]?3:2) ;if fax is disabled, just hang up
exten => analog_fax,2,DBGet(DIAL=DEVICE/${FAX_RX}/dial);
exten => analog_fax,3,Dial(${DIAL},20,d)
exten => analog_fax,4,Hangup
exten => out_fax,1,txfax(${TXFAX_NAME}|caller)
exten => out_fax,2,Hangup
exten => h,1,system(tiff2ps -2eaz ${FAXFILE} | ps2pdf - ${FAXFILE}.pdf)
exten => h,2,system(mime-construct --to ${EMAILADDR} --subject "Fax from ${CALLERIDNUM} ${CALLERIDNAME}" --attachment ${CALLERIDNUM}.pdf --type application/pdf --file ${FAXFILE}.pdf)
exten => h,3,system(rm ${FAXFILE} ${FAXFILE}.pdf)
exten => h,4,Hangup()

Be aware that NVfaxdetect can be a bit quirky. You may need to fine tune the timing mechanism in the actual NVfaxdetect(4) lines above. If 4 is too long or too short a delay to detect a fax call, try 10 or nothing at all. 10 works for us. 4 works in Australia apparently. If you need more details, read our original article on this topic. It also explains how to get all of this working with the Nerd Vittles Stealth AutoAttendant if you're using it.

Asterisk Recording Interface. A new web-based utility for managing your voicemail now is included in AMP and can be accessed by clicking Voicemail & Recordings on the initial AMP screen at the IP address of your Asterisk system. It also can be accessed at http://Asterisk-IP-address/recordings/. To log in to the Asterisk Recording Interface (ARI), just enter an extension number on your Asterisk system and the password for that extension. From the web interface, you can manage your voicemail messages including playing them back, you can review the call log to this extension, and you can set your voicemail password as well as your desired setup for recording calls by setting the call monitor defaults for this extension. Very cool!

Other Out-of-the-Box Utilities. Asterisk@Home 2.4 comes bundled with a number of additional utilities. Here are some of them. You can retrieve the current time by dialing *60. If the time is wrong, you can reset your default time zone by logging into your server as root and typing config. A current weather report for New York is available by dialing *61. You can change the city by following our previous tutorial which is available here. Something has come unglued in the festival script, however, because there is a noticable 10-second delay between each line of text that is read now. To set up a wakeup call from any extension, dial *62. To determine the phone number of any extension, just dial *65. You can use the default MeetMe conferencing system from any or all of your extensions by dialing 8 plus the number of an existing extension. Additional conference rooms can be added by editing meetme_additional.conf. Finally, you can record customized voice prompts for your system by dialing 5678 from any extension. Before this will work, edit the extensions_custom.conf file (AMP->Maintenance->Config Edit->extensions_custom.conf) and uncomment the seven lines shown below which are located at the bottom of the file. Just remove the leading semicolons. You'll also need to uncomment the following line near the top of file at the beginning of the [from-internal-custom] context: ;include => custom-recordme.

;[custom-recordme]
;exten => 5678,1,Wait(2)
;exten => 5678,2,Record(/tmp/asterisk-recording:gsm)
;exten => 5678,3,Wait(2)
;exten => 5678,4,Playback(/tmp/asterisk-recording)
;exten => 5678,5,Wait(2)
;exten => 5678,6,Hangup

Once you make a recording, it needs to be moved to /var/lib/asterisk/sounds/custom with a new filename.gsm, e.g. mv /tmp/asterisk-recording.gsm /var/lib/asterisk/sounds/custom/hihoney.gsm. Then change the ownership of the file: chown asterisk:asterisk /var/lib/asterisk/sounds/custom/hihoney.gsm. You then can play the recording with a line like this in your dialplan: exten=>s,1,Playback(custom/hihoney) where hihoney is the name you assigned to the recording without its .gsm extension.

Where To Go From Here. After you get a functioning Asterisk system, you're ready to move on to some really cool things that make Asterisk a one-of-a-kind PBX. There are customized weather reports, web and phone-based dialers from a MySQL address book, incoming fax to PDF conversion with email delivery, blacklisting of telemarketers, bluetooth proximity detection so that your home or office calls automatically transfer to your cellphone when you depart with your bluetooth device, and on and on. You'll also want to take a more in-depth look at many of the topics we've covered above. For a complete catalog of all of our Asterisk projects and everything else we've written about Asterisk@Home, go here. Then take a look at a terrific writeup from the other side of the globe: Asterisk@Home for Dumb-Me. Finally, there's an Asterisk@Home Handbook Wiki project under development that's worth a careful look.

The Bleeding Edge. For the pioneers that just can't wait for Asterisk@Home 2.5, here's a quick and dirty way to load the new, new Asterisk 1.2.4 today. Log in to your new Asterisk@Home 2.4 server as root. Then issue the following commands in order. Be aware that this probably will break a few things including inbound fax support. But you can follow our original fax tutorial to get that working again. Everything else seems to work just fine at least in our Zap-free test machine. Enjoy!

amportal stop

amportal start


It's free software day again at Nerd Vittles, and today we're building a telephone reminder system which lets you schedule reminders for future events. And when the appointed date and time arrives, Asterisk® will swing into action and place a call to the number you designate to deliver your customized reminder message. Asterisk@Home is bundled with a wakeup call system which lets you schedule one wakeup call per extension for any time during the next 24 hours. It's a great product. However, after using a terrific, web-based email reminder system in the Linux and Mac worlds, we wanted something a bit more flexible and robust for Asterisk. For those using Asterisk@Home 2.5 or later, click here for the updated version.

Some of the smarts for this system already have been incorporated into our TeleYapper Voice Messaging System. But that was a real-time system meaning it began calling immediately after you chose a group of people to call. This system is different in that you can schedule the calls for the near or distant future, you can specify different numbers for the calls, and you can customize the recorded message for each call. In short, it's perfect for appointment reminders, birthday reminders, anniversary reminders, and anything else you want to remember. You can even schedule a call to your cellphone to remind you to pick up little Suzie at school on Friday after Band Camp. And all it takes is a phone call to set up each reminder. There's no web page to fill in and no database required to manage the reminders. You can schedule as many reminders per phone number as your little fingers care to dial! Did we mention? It's also FREE! And to all you freeloaders, yes, some of your fellow readers chipped in to pay for the Allison IVR prompts so those are included at no cost as well.

Prerequisites. As with all of our newer projects, we've tested this with ISO-installed versions of Asterisk@Home 1.5 and Asterisk@Home 2.2. If you wish to use it with some other version of Asterisk@Home or with a "pure Asterisk" system, then you're on your own. We're also assuming you have a working wakeup call system on your Asterisk box. Dial *62 from any extension on your system, and enter a wakeup call for a few minutes in the future, and be sure you get a return call on schedule. If not, get that installed and working first. Here's a link to our Asterisk@Home 2.2 installation tutorial if you need assistance. Once all the prerequisites are satisfied, this project ought to take you about 30 minutes ... if you're a fast reader.

How It Works. The reminder system is actually quite simple to use. You dial extension 1-2-3 on your Asterisk system, enter your password, and then you'll be prompted to record a reminder message. Next you enter the phone number, date, and time for delivery of the reminder message. When the appointed date and time arrives, Asterisk will place the call to the number you specified using your default dialing rules and will play the customized reminder when the call is answered. If the call is not answered, the call will be repeated n number of times with a delay between calls of x minutes before giving up on the call. You'll get an email with the call reminder setup if desired. You also get to configure the number of retries and the delay between calls.

Finally, a word about failed calls. Reminders are important to most folks, or you wouldn't be scheduling them. So failed calls are problematic. On the one hand, you don't want to overburden your phone system placing thousands of reminder calls just because the calls continue to fail. You may have entered an incorrect phone number, for example. So our middle-of-the-road solution to failed calls is this. You can tell the system how many times to repeat the call and how much time to eat up between attempts. If the call still fails, the reminder will be deleted from the system. But the reminder message is preserved. If you look in /var/lib/asterisk/sounds/custom on your system, you will see some custom sound files (such as the reminder prompts which all begin with reminder). In addition, you will see the actual reminder messages for each of your reminders. The naming convention is HourMinute.Date.PhoneNumber.gsm. If you see entries in this directory with dates before today's date, those are failed call reminders. You can play the sound files on most computers by simply double-clicking on the files. You can delete old reminders while logged in as root on your Asterisk system with a command like this:

rm -f /var/lib/asterisk/sounds/custom/*.20060123.*.gsm

Just be sure you don't delete today's reminder messages or messages with a future date, or your entire reminder system will be up in smoke!

Here are the components that make up the complete system:

Limitations. There are a few limitations you need to be aware of. First, you can't schedule delivery of a reminder within the first 5 minutes after midnight each night. That's when the reminder system does its housekeeping. Second, you must schedule reminders at least 5 minutes after you place your call to set up the reminder. This gives the system ample time to generate the configuration files it needs and to put them in the right places. Third, the current reminder system does not fully support simultaneous scheduling of multiple reminders. The current system uses unique names to identify sound files generated by multiple simultaneous callers. However, it still is theoretically possible for two different callers to schedule two reminders for the same phone number and the same reminder time and to do so at the exact same time. This would cause one of the reminders to be discarded. We just wanted to alert you to this remote possibility. But we hasten to add that the chance of this happening is pretty small even in a very large Asterisk system with hundreds of users. There's also no present ability to link to a database for scheduling reminders. Nor can you schedule recurring reminders for events such as birthdays and anniversaries. But we'll get to some of these features one day soon if there's sufficient interest in the product.

License. This software is licensed for your use under a Creative Commons Attribution-ShareAlike 2.5 license. Before using this software, please read the terms of the license. A Plain English version of the license is available here. You may not charge a fee for something we are giving you for free. Finally, we ask that you preserve our copyright notice in any copies of the software you make. The same applies to derivative works. If you do not accept the terms of the license, do not use the software. Even if you accept the terms of the license, keep in mind that BY USING THIS SOFTWARE, YOU ASSUME ALL RISKS OF USE AND NO WARRANTIES EXPRESS OR IMPLIED ARE PROVIDED WITH THIS FREE SOFTWARE INCLUDING FITNESS FOR A PARTICULAR USE AND MERCHANTABILITY. In short, it's up to you to determine, at your risk, whether this software meets your needs. Don't assume that it will, and don't assume that the code is error-free. It's probably not.

The Game Plan. To get the Reminder System set up, we're first going to move all of the code into the proper places. This includes the modifications to the dialplan contexts, installation of the new Allison voice prompts, and installation of the PHP/AGI scripts. Then we'll walk you through configuring the system. And finally we'll schedule a reminder to make sure everything went according to plan.

Modifying Your Dialplan. Step #1 is to cut-and-paste some code into your dialplan. For those using Asterisk@Home or the Asterisk Management Portal (AMP), this code should go at the bottom of the extensions_custom.conf file in the /etc/asterisk directory on your system. If you're using Asterisk@Home 1.5, use this code. If you're using Asterisk@Home 2.x, use this code. For Step #2, you'll need to cut-and-paste the following code snippet into the top section of extensions_custom.conf in the [from-internal-custom] context:

exten => 123,1,Answer
exten => 123,2,Wait(1)
exten => 123,3,Authenticate(12345678)
exten => 123,4,Goto(reminder,s,1)

If, for some reason, you already are using extension 1-2-3 on your Asterisk system for some other purpose, then simply adjust the 123 extension in the four lines above to another number that works on your system. This is the number you will dial to schedule reminders. Line 3 is important as well. This is where you set a password for scheduling reminders on your system. Anyone that knows the password can schedule reminders. Simply replace 12345678 with a password that's secure enough for you to sleep well.

Finally, a head's up. When you do the cut-and-paste, double-check the long lines of code such as h,1 in [reminder9] and be sure all of the text ends up on a single line. Otherwise, things won't work correctly. Once you've added the two sections of code, save extensions_custom.conf and reload Asterisk.

Installing Reminder Voice Prompts. As some of you know, we mounted a campaign to raise a little dough to pay for Allison, the Voice of Asterisk, to record custom voice prompts for the new reminder system. To all that contributed, thank you! And, we have some money remaining to cover some things we'll be telling you about in the coming weeks. Incidentally, it's not too late to donate $5 if you are so inclined. All of the donations will be used to defray future Asterisk development project costs. It also guarantees you free voice prompts in future projects. At least for this project, the voice prompts are free for the taking subject to the terms of the license agreement whether you contributed or not. Just log into your Asterisk server as root and enter the following commands:

cd /var/lib/asterisk/sounds/custom
wget http://nerdvittles.com/reminder_voice.zip
unzip reminder_voice.zip
rm reminder_voice.zip
chmod 664 reminder*.gsm
chown asterisk:asterisk reminder*.gsm


Installing the Reminder PHP/AGI Scripts. While you're still logged in as root, let's install the final pieces of code that you'll need to get things working. Just execute the commands below which match the version of Asterisk@Home you're running.

For Asterisk@Home 1.x users:

cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/aah15/reminder.zip
unzip reminder.zip
rm reminder.zip
chmod 775 reminder.php
chown asterisk:asterisk reminder.php
chmod 775 check*.php
chown asterisk:asterisk check*.php
chmod 777 run_reminders
chown asterisk:asterisk run_reminders


For Asterisk@Home 2.x users:

cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/aah2/reminder.zip
unzip reminder.zip
rm reminder.zip
chmod 775 reminder.php
chown asterisk:asterisk reminder.php
chmod 775 check*.php
chown asterisk:asterisk check*.php
chmod 777 run_reminders
chown asterisk:asterisk run_reminders


Creating Reminders Directory. While you're still logged in as root, create the directory to store your reminders until the day arrives to execute them. Just issue the following commands:

su asterisk
cd /var/spool/asterisk
mkdir reminders
exit


Setting Up the Reminder Crontab Entry. Now we need to set up the cron job to actually move reminders into the wakeup calls directory on the day they are scheduled to run. While logged in as root, edit the crontab file: nano -w /etc/crontab. Be sure you typed the exit command in the last step, or you'll be logged in as asterisk instead of root. And you won't be able to edit the file! Now cut-and-paste the following command to the bottom of the crontab file. It should go on its own line immediately below the run_wakeups line which already is in the file and is used to schedule your wakeup calls.

0 0 * * * root /var/lib/asterisk/agi-bin/run_reminders >/dev/null 2>&1

Once you've added the line, save your changes: Ctrl-X, Y, then press Enter. Whew! That's it for the Reminder code. Now let's configure the system, and you'll be all set.

Configuring the Reminder System. To configure the reminder system, you'll need to edit the reminder.php script while logged in as root: nano -w /var/lib/asterisk/agi-bin/reminder.php. You'll notice a section of variables at the top of the file that looks like this:

$extensionmaxdigits=4 ;
$debug = 1;
$newlogeachdebug = 1;
$emaildebuglog = 0;
$email = "yourname@yourdomain" ;
$trunk = "local" ;
$callerid = "6781234567" ;
$numcallattempts=6 ;
$calldelaybetweenruns=300 ;
$timetoring=40 ;
$acctcode= "Reminder" ;

This is the only section of code you ought to mess with. When we update the code in coming months to add features, we'll assume everything else has been left intact. Be very careful when editing this file. Don't remove any semicolons or quotation marks, or nothing will work! Here's a quick run-down on what each of the above variables does:

Once you've configured the Reminder System to meet your needs, save your changes: Ctrl-X, Y, then press Enter. HINT: You may want to start with the defaults which will work well for most folks.

Scheduling A Reminder. We're ready to take the Reminder System for a trial run at this juncture. Make sure you've reloaded your Asterisk system, and then dial 123 from an extension on your system. Enter the password you set up for your system and then press the pound key.

Entering a Reminder Message. You'll first be prompted to record a reminder message. This is the message that will be played when someone answers the reminder call. If you're not scheduling this reminder for yourself, then the message ought to explain who's calling and what the purpose of the call is. Once you've recorded your message, press the pound key to end the recording. You can replay or rerecord the reminder if desired while you're in this step of the reminder creation process.

Entering the Callback Number. When prompted for the reminder callback number, there are a couple of things to keep in mind. First, if you've specified "local" as the trunk to use for reminders in the reminder.php script, then the phone numbers can be entered in any format supported by your dialplan. Press the pound key after entering the appropriate number. The calls will be placed using the trunks specified in your dialplan rules. The one exception is extensions on your local Asterisk system since these can't be routed by Asterisk@Home using your outbound calls dialplan rules. The way we handle extensions is by examining the length of the phone number. At the top of reminder.php, you can specify the maximum number of digits for local extensions by setting $extensionmaxdigits. So long as the callback number is less than or equal to this number of digits, the system has the smarts to correctly route the call to a local extension.

If you have designated a particular trunk for placement of reminder calls, then you'll need to make certain that the format of the phone numbers entered for reminders on your system matches a dial string supported for this outbound trunk in your dialplan. For example, if this trunk requires that calls be entered with a 1 and then an area code and 7-digit number, then that is the only format that should be used for entering callback numbers in your reminder system. Again, the one exception is calls to local extensions. So long as the number of a local extension is entered with less than or equal the number of digits set for the $extensionmaxdigits variable in reminder.php, the call will be routed properly to the local extension regardless of the trunk setting.

Finally, here's a shortcut that can be used if the phone you're using to schedule the reminder is the same one on which you want to get the reminder callback. In this case, just press the pound key when prompted for the number to which to deliver the reminder message. This will set the callback number as the caller ID of the phone you used to schedule the call. If it's a local extension, then the caller ID will be set to the local extension number of the phone from which you placed the reminder scheduling call. Just be sure your $extensionmaxdigits is set correctly or calls to local extensions will fail.

Entering the Date of the Reminder. Once you accept the reminder message, you'll be prompted to enter the date on which this reminder will be delivered. Dates are entered using a four-digit year, then a two-digit month, and then a two-digit day. There is some error correction but not much. You obviously can't schedule reminders in the past! And you don't need to press the pound key after entering the eight digits. Once you've entered a date, the system will tell you what date you entered including the day of the week. If the entry is correct, just press 1 to move on.

Entering the Time of the Reminder. Now you'll be prompted to enter the delivery time for your reminder. Times are entered as a two-digit hour and two-digit minute. For times less than 1200, you will be prompted whether you meant AM or PM. For those that understand military time, you can avoid this step by entering times using the format: 1345 which means 1:45 p.m. You don't need to press the pound key after entering the four-digit time for delivery of your reminder. Keep in mind that you cannot schedule a reminder for delivery in the first five minutes after midnight. Other times "in the midnight hour" should be entered in the format: 0045 which means 12:45 a.m. Keep in mind that reminder times always must be at least 5 minutes in the future. Finally, you cannot schedule two reminders for the exact same date and time for delivery to the same phone number. Once you enter a delivery time, the system will play back both the date and time for the reminder as a precaution. Press 1 to accept your entries and store the reminder to disk.

Where Reminders Are Stored. There are actually two files that make up each reminder: the .call file which places the actual call and the .gsm file which is the reminder message itself. The file naming convention is HourMinute.Date.PhoneNumber with either a .call or .gsm extension. The sound files are all stored in /var/lib/asterisk/sounds/custom. Prior to the delivery date of the reminder message, the .call file is stored in /var/spool/asterisk/reminders. Then, at midnight on the date the reminder is scheduled for delivery, the run_reminders script in /var/lib/asterisk/agi-bin moves the affected .call files to /var/spool/asterisk/wakeups. The .call files in the wakeups directory are reviewed every minute of the day by the run_wakeups script which is stored in /var/lib/asterisk/agi-bin. By examining the first four digits of the filename, the scripts look for a match with the current hour and minute of the day. Once the time for the call arrives, the .call file is moved to /var/spool/asterisk/outgoing where the Asterisk system itself processes the .call script and places the call. All dialing retries are handled internally by Asterisk with no user or program control so it's important to set your default values correctly in the reminder.php script as explained above. Once the .call file is processed, Asterisk discards the file whether the call was successful or not. As noted above, the reminder message file is only discarded if the call is completed successfully. So, from time to time, you do need to review the contents of /var/lib/asterisk/sounds/custom and discard reminder messages, if any, with dates in the past.

Just another word of caution about the reminder message files: be very careful in deleting these files. The message files and .call files are linked by filename only, and there is no error detection or correction if the message file gets discarded before the time for the reminder call arrives. What would happen in such a situation is the call would be placed, someone would answer, Allison would say "please hold for an important reminder," and then there would be a brief silence followed by Allison saying "to repeat this reminder, press 1; otherwise, press 2" which is not entirely helpful.

Reminder and Wakeup Call Processing. It has been documented that flooding Asterisk with a bunch of .call scripts simultaneously can cause some of the scripts to be discarded without being executed. To avoid this problem, the run_wakeups script (which handles both wakeup calls and reminder message delivery) inserts a 5-second pause after each .call file is moved to the Asterisk queue. Should you experience dropped calls, one solution would be to increase the 5-second delay to a larger number, but we would caution against doing so unless you experience delivery problems with either your reminder messages or wakeup calls.

When you're first getting started with the reminder system, it's probably a good idea to fire up Asterisk's Command Line Interface (CLI): asterisk -r. Then you can watch as the reminders are scheduled and reminder calls are placed. Just schedule a reminder for five minutes from the time you begin the reminder call, and you'll be all set.

For Programmers Only. If you're just getting into PHP and AGI programming with Asterisk, then have a second look at reminder.php. In particular, take a look at the section of code that begins with parse agi headers into array. As best we can tell, this is the first version of this subroutine written in PHP that actually works. If you review the log file (reminder.txt), you will see a listing of all the AGI headers which are passed by Asterisk to PHP. But this is the first code we've seen that correctly reads the headers into variables where you can actually retrieve the content. Call it a feature! For example, the commented out line ($tmp = $agi['dnid']) shows the syntax to retrieve the DNID value from Asterisk. Just make a mental note that the parse AGI headers code in reminder.php actually works. Some of our previous code inherited the mistakes of others, but we've now taken the time to get this functioning properly because we needed it for something else. Here's the complete list of AGI headers that can be saved to variables in your PHP code should the need ever arise:

read: agi_request: reminder.php
read: agi_channel: SIP/204-6a1a
read: agi_language: en
read: agi_type: SIP
read: agi_uniqueid: 1138010325.1367
read: agi_callerid: "Line2" <204>
read: agi_dnid: 123
read: agi_rdnis: unknown
read: agi_context: reminder9
read: agi_extension: h
read: agi_priority: 2
read: agi_enhanced: 0.0
read: agi_accountcode:

You'll also want to take note of a little quirk in Asterisk (compared to some PBXs). To decipher the extension which actually placed a call, you must parse the agi_channel variable for the data between the slash and hyphen characters since the DNID (dialed number identifier) returns the extension being called (as opposed to the originating extension) when an internal call is placed. Here's one PHP approach to get the answer which in this case happens to be extension 204. Regex wizards could probably save a line of code, but who cares.

$CallingID = substr(stristr($agi['channel'],"/"),1);
$CallingID = substr($CallingID,0,strrpos($CallingID,"-"));


Wish List? Well, that about covers version 1 of our shiny new Reminder System for Asterisk. If you have enhancement suggestions or other recommendations for version 2, we'd love to hear from you. Just post a comment to this topic, and we'll have a look. In the meantime, enjoy!

Other Asterisk Projects? For a complete catalog of all our previous Asterisk projects, click here. For the most recent articles including those you missed over the Christmas and New Year's holidays, click here and scroll down the page.

It's free software day again at Nerd Vittles, and today it's Part II of TeleYapper, an Asterisk@Home-based telephone broadcasting service for neighborhoods, schools, little leagues, fundraisers, municipal governments, and anyone else that just wants to pester folks with annoying, but free, prerecorded phone calls. Everything you'll need to get TeleYapper working is in this article, so there's no need to begin with Part I unless you just want to. TeleYapper works like this. You create a recorded message using Asterisk®. Then you create a list of phone numbers to call in a MySQL database using a tool such as phpMyAdmin which is bundled with Asterisk@Home. Finally, you place a phone call either to kick off TeleYapper or to redial calls that failed the first time around. The software will dutifully swing into action and call qualifying phone numbers from any of ten calling categories that you specify when you set up your database of callees. TeleYapper then will deliver the message you've recorded. It works much like call-em-all.com and numerous other telephone broadcasting services with one important difference: TeleYapper is FREE! So, instead of paying 15¢ a call or $35 to $100 a month for a commercial service or spending thousands of dollars for a commercial dialer, now you can do it yourself using TeleYapper and your (also free) Asterisk@Home 1.5 or 2.2 PBX. Today we'll actually get TeleYapper making calls and emailing you the results of those calls. Don't be intimidated by the length of the article. You can still complete this project in about 30 minutes. It's mostly a cut-and-paste exercise. We've done all the hard work for you. NOTE: For those using Asterisk@Home 2.4 or later, use this updated tutorial and software.

Legalese. For those that are used to buying flawless software such as Microsoft Windows or Microsoft Office, let's be sure we're all on the same page up front. First, you're not buying this software. It's FREE! And, yes, sometimes you get what you pay for. Second, don't assume today's version is error-free. It's probably not. We try pretty hard to write reliable code, but even the best among us make mistakes. Third, by downloading or using this software, you are agreeing to assume all risks associated with use of the software. NO WARRANTIES EXPRESS OR IMPLIED INCLUDING ITS FITNESS FOR USE OR MERCHANTABILITY ARE PROVIDED WITH THIS SOFTWARE. And, finally, read or reread Part I of this series concerning Do Not Call statutes in your jurisdiction and make sure you are in compliance before placing any calls. Failure to heed this advice may subject you to serious criminal and civil penalties. If any of this gives you heartburn, exercise your constitutional right to not use the software.

Overview. One of the reasons we continue to write software applications for Asterisk is to document for others how easy it is to create really useful software for this terrific open source platform. When we began using Asterisk, there was precious little code available with sufficient documentation to give much of a hint on how to write applications. There were lots of reasons for this not the least of which was a desire by existing Asterisk developers to protect their livelihood. We don't want to jeopardize anyone's ability to make a living, but the spread of an open source PBX with good applications will only lead to more business, not less. Today's installment provides a good framework for anyone wanting to write Asterisk AGI scripts using PHP. The code is well-documented to demonstrate how to pass variables to an AGI script from your dialplan and how to retrieve variables from an Asterisk AGI script into your dialplan. We needed this for TeleYapper because we're using a phone call to an Interactive Voice Response (IVR) session embedded in the dialplan to begin the calling process. We use the IVR session not only to determine which group of callees to call but also to give the caller the option of placing a call to everyone in the group or just those to whom the initial call was unsuccessful. After the caller hangs up, the results are passed to the teleyapper.php application to do the heavy lifting. The PHP program takes advantage of an AGI script's ability to actually set dialplan code in motion once a call is answered. In order to log calls and track which ones are successful, we have to pass variables into that dialplan code and then execute another PHP script when the call is completed. Stated another way, every call requires two round-trips from the Asterisk dialplan to PHP/AGI scripts. So, if you can't figure out how to pass variables back and forth using this application, you probably need to take up another line of work. For those that just want to use the TeleYapper application and not learn much of anything about programming, you're welcome to do that subject to the license agreement which follows. We hope you'll put it to good use for the betterment of a school, an intramural sports program, or a neighborhood in which you live.

Licensing. We are retaining ownership of this software as well as the copyright. It is licensed for use under the terms of the Creative Commons Attribution Non-Commercial license. A Plain English summary is available here. We've done this primarily to do our part to stamp out the telemarketing creeps of the world. Those wishing to use TeleYapper in a commercial environment must first request a license outlining your proposed terms of use. We will promptly respond with a yay or nay. Telemarketers need not apply!

Asterisk Version Issues. In our first installment, we were ambushed by some changes in the way the new version of Asterisk handles management of memory variables. We're trying not to fall in the same trap again. Suffice it to say, the Asterisk developers decided to change the name of the verb, and the syntax, and the functionality of storing data to memory variables. There may be a good reason for it, but we can't think of any. And we certainly can't think of a reason why you would eliminate the old way of doing things in a product that is barely a year old. Nevertheless, we're all stuck with it. The bottom line is that, so long as we try to maintain versions of our applications for both Asterisk@Home 1.5 and Asterisk@Home 2.2, you'll need to download code that is compatible with the version of Asterisk you are running.

TeleYapper in a Nutshell. Before we get to the code, let's briefly cover how this message broadcasting system works. When you dial 674, the TeleYapper system will answer and prompt you for your password. Once you correctly enter the password, an interactive voice response (IVR) system will swing into action and give you several choices. That's what the [yapper] context handles. Pressing 1 lets you listen to your prerecorded TeleYapper message (if you have one). You don't yet so don't press 1. Pressing 2 lets you record a new TeleYapper message. This is handled by the [yapper2] context. Do this first and record something ... anything. You can rerecord a new message at any time by choosing option 2 again. Pressing 3 lets you kick off a TeleYapper dialing spree. It's handled by the [yapper3] context. Don't do this until we add your new database below, or you'll get smoke out of your system. If you choose option 3 to initiate a TeleYapper calling session, the system will first prompt you for a group option number to use. This is managed by the [yapper-options] context. Simply stated, when you build your database of callees for TeleYapper, you can specify a one-digit group number for each entry in the file. Then, when you begin a calling session, you can narrow down the calling group by telling TeleYapper which group of callees to call. If you want a callee to be in more than one group, you simply enter that callee into the database multiple times with different group numbers. If you want everyone in the same group, then enter 0 for every person in your database.

Once you specify the group number during your TeleYapper session, the system will actually look up and report back how many messages will be delivered to the callee group you've chosen. Allison will say something like this assuming there were 146 calls to be placed: "The number I have is one hundred and forty six messages." This will give you the count of qualifying records in the database and the option of proceeding with the calls, cancelling the transaction, or just redialing the numbers of the calls that failed to this group on the previous pass through the database. As noted previously, we've endeavored to build this entire application using the voice prompts that are delivered with Asterisk@Home 1.5 or 2.x so they're not quite perfect. But they work reasonably well once you understand how the pieces fit together. You're supposed to be nodding in agreement now. If not, reread the last two paragraphs.

TeleYapper's Calling Process. For those that like lists, it may help to visualize how all the TeleYapper code fits together by laying out the actual program steps in a typical call:

The TeleYapper Components. Last week we provided the beginnings of the TeleYapper application for you to experiment with. This included the MySQL database and some chunks of code for your AAH dialplan (depending upon which version of AAH you were using) plus checkgroup.php (used to compute the number of callees in the group selected by caller). Today we want to update some of the original code. Then we'll add some additional pieces of code so that the application can do something meaningful ... like calling people with your broadcast message.

Actually, the new code not only handles the actual dialing of the callees you've entered in your MySQL database (teleyapper.php), it also plays your message when a callee answers (dialplan contexts), and documents what happened during the calls (teleyapper2.php). Call progress is documented in two ways. First, when a call is completed, TeleYapper will log the date and time of the call as well as a best guess of what happened during the call in your MySQL database. So browsing entries in your TeleYapper database will always show the date, time, and status of the last completed call to each callee. We'll build a web interface for this one of these days. Second, when you install the TeleYapper PHP components, there are some configuration options which will also let you create a detailed log of what happened during the TeleYapper calls. If you have email working reliably on your Asterisk system, you also can enter your email address and tell TeleYapper to email you every log that is produced. There are log entries for the initial call setup (handled by teleyapper.php) and for the placement of the individual calls (handled by teleyapper2.php). Finally, you have the option of creating a new log with each series of calls that are placed (the default setting), or you can configure TeleYapper to keep adding to the end of the initial log. In the latter case, it's up to you to erase the log before it fills up your disk. Individual call entries, if logged, will be appended to the main TeleYapper call setup log (/var/log/asterisk/teleyapper.txt).

To keep things simple, everything you'll need to make TeleYapper work is covered in this article even though we covered some of it last week. Where there is overlap with last week's article, we'll tell you, and you can skip that step. It simply didn't make much sense for new visitors to have to jump back and forth between the two articles to get a working system. That's one of the limitations of the blog format unfortunately. Here are the components that make up the complete TeleYapper system, and we'll cover them below in the order which simplifies the installation process:

Creating the TeleYapper Database. We use Asterisk@Home's MySQL database management system to manage the list of callees for TeleYapper to dial. It can handle a database of almost any size and generally stands up well in performance comparisons with Oracle. So you're covered on the database front. If you downloaded and installed this database in Part I, you can skip this section. Nothing has changed since Part I.

To create the MySQL database to support TeleYapper, the easiest way is using the Asterisk Management Portal (AMP) to gain access to phpMyAdmin: AMP->Maintenance->phpMyAdmin. When phpMyAdmin loads, click on the SQL icon in the left column. When the SQL window appears, clear the existing SQL query and then cut-and-paste the following SQL code into that box and then click the Go button. When the import completes, click the teleyapper.callees table entry in the left column to open the file. Then click the Insert tab at the top of the right column to add entries to the table. You only need to add information for the name, phonenum, and group fields in the corresponding values column. The id, lastokcall, and lastcall fields should be left as is. The id field gets calculated automatically. The lastokcall will record the time and date of the last successful call using TeleYapper. And the lastcall field identifies what happened during the last call to this person, e.g. ok means the call was completed successfully, no answer means no one answered the call, or answering machine means an answering machine took the call.

You can add up to two records at a time and, by clicking the Insert Another New Row button, you will be returned to this data entry screen after you save your entries by clicking the Go button. The name field allows you to quickly review entries you've made. It won't be used when making TeleYapper calls. The phonenum field is the important one. This is the exact dial string required to place a call on your Asterisk system to this callee using whatever VoIP or PSTN outbound trunk you plan to use with TeleYapper. For example, if your preferred provider requires 11-digit phone numbers with a 1, area code, and number, then that's the way the numbers should be entered into the TeleYapper database. The group field has already been discussed. Just enter a number between 0 and 9 to identify the group with whom this individual should be associated. Finally, after adding records to the table, you can click the Browse tab to review your entries. And, while Browsing, you can click the Pencil icon beside any record entry to edit it. Clicking the red X icon beside a record entry deletes the record. If, for some reason, you wish to delete ALL the records in the file, click the Empty tab at the top of the right column. Under no circumstances should you click on the Drop tab as this removes not only the table's contents but also the table structure itself. In short, you'd have to import the database table again.

Answering the Incoming Call. This is a simple addition to your dialplan to actually answer calls to M-S-G (extension 674) and pass them to the TeleYapper contexts for processing. If you went through Part I, you can skip this step. Nothing has changed. Using a web browser, open the Asterisk Management Portal (AMP) by entering the IP address of your Asterisk machine. To add TeleYapper to your dialplan, just cut-and-paste the following code into the [from-internal-custom] context near the top of extensions_custom.conf: AMP->Maintenance->Config Edit->extensions_custom.conf. Be sure to change the 1234 password below to something secure for your system since this will be used to gain access to your TeleYapper system!

exten => 674,1,Answer ; dial MSG on any extension to manage your TeleYapper system
exten => 674,2,Wait(1)
exten => 674,3,Authenticate(1234)
exten => 674,4,Goto(yapper,s,1)

If you're a long-time reader of Nerd Vittles and you're using either our Stealth AutoAttendant or some other AutoAttendant, then you already know why you need to be careful about putting extensions like 6-7-4 in your extensions_custom.conf file because anyone can call you, dial 6-7-4 while your AutoAttendant is playing, and insert their own obscene message into your TeleYapper system. The solution is adding your own secure password in line 3 above rather than using the default 1234. Another precaution you should always perform is to first play your outgoing TeleYapper message to yourself to make certain it says what you think it should before you kick off a dialing spree to a thousand of your closest friends or business associates.

AutoAttendant Contexts for TeleYapper. The simplest solution for those that read Part I of the TeleYapper series is to just block delete the [yapper], [yapper2], [yapper3], [yapper-options], and [yapper-gen] contexts at the bottom of your extensions_custom.conf file. Then, for new and old readers alike, insert one of the following chunks of code at the bottom of extensions_custom.conf depending upon your version of Asterisk@Home. Last week we actually presented three approaches. Two used checkgroup.php to retrieve the group count for the autoattendant dialogue while one(for AAH 1.5 only) actually performed the MySQL group count lookups in the dialplan itself. We've given up on the latter approach as something we want to support. The Asterisk developers barely do, and it doesn't appear to work in Asterisk@Home 2.2 (Asterisk 1.5.1) anyway. For those that are curious, we've documented how it works in Part I if you want to wrestle with it.

For users of Asterisk@Home 1.5, open the Asterisk Management Portal (AMP) by entering the IP address of your Asterisk machine. Cut-and-paste the following six contexts into the bottom of extensions_custom.conf: AMP->Maintenance->Config Edit->extensions_custom.conf:

[yapper]
exten => s,1,DigitTimeout(7)
exten => s,2,ResponseTimeout(10)
exten => s,3,Background(T-to-hear-cur-ancmnt)
exten => s,4,Background(press-1)
exten => s,5,Background(to-rerecord-yr-message)
exten => s,6,Background(press-2)
exten => s,7,Background(to-place-outgoing-call)
exten => s,8,Background(press-3)
exten => s,9,Background(to-hear-menu-again)
exten => s,10,Background(press-4)
exten => s,11,Background(to-hang-up)
exten => s,12,Background(press-5)
exten => 1,1,Playback(custom/broadcast)
exten => 1,2,Wait(2)
exten => 1,3,Goto(s,3)
exten => 2,1,Goto(yapper2,s,1)
exten => 3,1,Goto(yapper-options,s,1)
exten => 4,1,Goto(s,3)
exten => 5,1,Playback(goodbye)
exten => 5,2,Hangup
exten => t,1,Goto(s,3)
exten => i,1,Goto(s,3)
exten => o,1,Goto(s,3)
exten => h,1,Hangup

[yapper-redial]
exten => s,1,Playback(speed-dial)
exten => s,2,Playback(activated)
exten => s,3,Wait(1)
exten => s,4,Playback(goodbye)
exten => s,5,Hangup
exten => h,1,DeadAGI(teleyapper.php|${GROUP}|${COUNTER}|3)
exten => h,2,Hangup


For users of Asterisk@Home 2.2, open the Asterisk Management Portal (AMP) by entering the IP address of your Asterisk machine. Cut-and-paste the following six contexts into the bottom of extensions_custom.conf: AMP->Maintenance->Config Edit->extensions_custom.conf:

[yapper]
exten => s,1,DigitTimeout(7)
exten => s,2,ResponseTimeout(10)
exten => s,3,Background(T-to-hear-cur-ancmnt)
exten => s,4,Background(press-1)
exten => s,5,Background(to-rerecord-yr-message)
exten => s,6,Background(press-2)
exten => s,7,Background(to-place-outgoing-call)
exten => s,8,Background(press-3)
exten => s,9,Background(to-hear-menu-again)
exten => s,10,Background(press-4)
exten => s,11,Background(to-hang-up)
exten => s,12,Background(press-5)
exten => 1,1,Playback(custom/broadcast)
exten => 1,2,Wait(2)
exten => 1,3,Goto(s,3)
exten => 2,1,Goto(yapper2,s,1)
exten => 3,1,Goto(yapper-options,s,1)
exten => 4,1,Goto(s,3)
exten => 5,1,Playback(goodbye)
exten => 5,2,Hangup
exten => t,1,Goto(s,3)
exten => i,1,Goto(s,3)
exten => o,1,Goto(s,3)
exten => h,1,Hangup

[yapper-redial]
exten => s,1,Playback(speed-dial)
exten => s,2,Playback(activated)
exten => s,3,Wait(1)
exten => s,4,Playback(goodbye)
exten => s,5,Hangup
exten => h,1,DeadAGI(teleyapper.php|${GROUP}|${COUNTER}|3)
exten => h,2,Hangup


Call Processing Contexts for TeleYapper. All of this code is new. For new and old readers alike, insert one of the following chunks of code at the bottom of extensions_custom.conf depending upon your version of Asterisk@Home.

For Asterisk@Home 1.5 users, cut-and-paste the following two contexts:

[broadcast]
exten => s,1,Answer
exten => s,2,Wait(2)
exten => s,3,Playback(system-status-msg)
exten => s,4,Wait(2)
;exten => s,5,BackgroundDetect(custom/broadcast|1000|50|3000)
exten => s,5,Playback(custom/broadcast)
exten => s,6,Goto(talk,1)
exten => t,1,Goto(talk,1)
exten => i,1,Goto(talk,1)
exten => o,1,Goto(talk,1)
exten => h,1,NoOp(Callee hung up call before menu. Dialed: ${DIAL} ID: ${ID}.)
exten => h,2,SetGlobalVar(STATUS='EarlyHangup')
exten => h,3,DeadAGI(teleyapper2.php|${ID}|${STATUS}|${DIAL})
exten => h,4,Hangup
exten => talk,1,Goto(broadcast2,s,1)

[broadcast2]
exten => s,1,SetGlobalVar(STATUS='Answered')
exten => s,2,DigitTimeout(4)
exten => s,3,ResponseTimeout(4)
exten => s,4,Background(to-hear-msg-again)
exten => s,5,Background(press-1)
exten => s,6,Background(to-blklist-last-caller)
exten => s,7,Background(digits/2)
exten => s,8,Background(otherwise-press)
exten => s,9,Background(digits/3)
exten => t,1,NoOp(Callee's Answering Machine probably answered. Dialed: ${DIAL} ID: ${ID}.)
exten => t,2,SetGlobalVar(STATUS='AnsMachine')
exten => t,3,Background(restarting)
exten => t,4,Wait(1)
exten => t,5,Playback(custom/broadcast) ; playing again for ans machine
exten => t,6,Background(goodbye)
exten => t,7,Hangup
exten => h,1,DeadAGI(teleyapper2.php|${ID}|${STATUS}|${DIAL})
exten => h,2,Hangup
exten => i,1,Goto(1,1)
exten => o,1,Goto(1,1)
exten => 1,1,SetGlobalVar(STATUS='ReplayedMsg')
exten => 1,2,Goto(t,3)
exten => 2,1,SetGlobalVar(STATUS='Zap')
exten => 2,2,Background(num-was-successfully)
exten => 2,3,Background(removed)
exten => 2,4,Background(goodbye)
exten => 2,5,NoOp(Callee Requested to have number removed. Dialed: ${DIAL} ID: ${ID}.)
exten => 2,6,Hangup
exten => 3,1,SetGlobalVar(STATUS='OK')
exten => 3,2,Background(goodbye)
exten => 3,3,NoOp(Callee Acknowledged Call. Dialed: ${DIAL} ID: ${ID}.)
exten => 3,4,Hangup


For Asterisk@Home 2.2 users, cut-and-paste the following two contexts:

[broadcast]
exten => s,1,Answer
exten => s,2,Wait(2)
exten => s,3,Playback(system-status-msg)
exten => s,4,Wait(2)
;exten => s,5,BackgroundDetect(custom/broadcast|1000|50|3000)
exten => s,5,Playback(custom/broadcast)
exten => s,6,Goto(talk,1)
exten => t,1,Goto(talk,1)
exten => i,1,Goto(talk,1)
exten => o,1,Goto(talk,1)
exten => h,1,NoOp(Callee hung up call before menu. Dialed: ${DIAL} ID: ${ID}.)
exten => h,2,Set(STATUS='EarlyHangup'|g)
exten => h,3,DeadAGI(teleyapper2.php|${ID}|${STATUS}|${DIAL})
exten => h,4,Hangup
exten => talk,1,Goto(broadcast2,s,1)

[broadcast2]
exten => s,1,Set(STATUS='Answered'|g)
exten => s,2,DigitTimeout(4)
exten => s,3,ResponseTimeout(4)
exten => s,4,Background(to-hear-msg-again)
exten => s,5,Background(press-1)
exten => s,6,Background(to-blklist-last-caller)
exten => s,7,Background(digits/2)
exten => s,8,Background(otherwise-press)
exten => s,9,Background(digits/3)
exten => t,1,NoOp(Callee's Answering Machine probably answered. Dialed: ${DIAL} ID: ${ID}.)
exten => t,2,Set(STATUS='AnsMachine'|g)
exten => t,3,Background(restarting)
exten => t,4,Wait(1)
exten => t,5,Playback(custom/broadcast) ; playing again for ans machine
exten => t,6,Background(goodbye)
exten => t,7,Hangup
exten => h,1,DeadAGI(teleyapper2.php|${ID}|${STATUS}|${DIAL})
exten => h,2,Hangup
exten => i,1,Goto(1,1)
exten => o,1,Goto(1,1)
exten => 1,1,Set(STATUS='ReplayedMsg'|g)
exten => 1,2,Goto(t,3)
exten => 2,1,Set(STATUS='Zap'|g)
exten => 2,2,Background(num-was-successfully)
exten => 2,3,Background(removed)
exten => 2,4,Background(goodbye)
exten => 2,5,NoOp(Callee Requested to have number removed. Dialed: ${DIAL} ID: ${ID}.)
exten => 2,6,Hangup
exten => 3,1,Set(STATUS='OK'|g)
exten => 3,2,Background(goodbye)
exten => 3,3,NoOp(Callee Acknowledged Call. Dialed: ${DIAL} ID: ${ID}.)
exten => 3,4,Hangup


Once you finish adding all of the new contexts to extensions_custom.conf, click the Update button to save your changes to disk. There's no need to reload Asterisk just yet. We've still got our AGI scripts to install.

For those that are curious, you'll notice there is a commented out line 5 in the [broadcast] context. It's an Asterisk command called BackgroundDetect. What this command is supposed to do is play a sound file while listening for silence at the callee's end of the call. Once silence is detected, the call processing drops to talk. We couldn't get it to work reliably so the current release blindly plays your message and then asks for an acknowledgment. If it doesn't get one, it plays your message again, and then hangs up. The theory here is that, even if a callee has an answering machine, the second playing of your message should get recorded. We'll see what the feedback from the pioneers reveals. Just be aware that there may be further adjustments in the coming days and weeks. So check back and read the latest comments to this blog entry.

Installing checkgroup.php AGI Script. We introduced this script in Part I to solve a bug in Asterisk@Home 2.2 which appears to be inherited from Asterisk 1.2.1. If you've already downloaded it, you can skip this section. Nothing has changed. For those just joining us, you'll need to install the checkgroup.php script in your /var/lib/asterisk/agi-bin directory and change file ownership and permissions on the file. Log in to your Asterisk server as root, and then execute the following commands:

cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/checkgroup.zip
unzip checkgroup.zip
rm checkgroup.zip
chmod 775 checkgroup.php
chown asterisk:asterisk checkgroup.php

This script includes a debug log. The default settings are to create a new log file (/var/log/asterisk/telecheck.txt) each time the script is executed. This doesn't take up much room and is always there for you to read if something comes unglued: cat /var/log/asterisk/telecheck.txt. There are some other options. You can turn off the log file entirely ($debug=0). You can choose not to erase the previous log file each time the script is run ($newlogeachdebug=0) in which case the file continues to grow until your hard disk fills up. And you can have the log file emailed to you each time the script is executed ($emaildebuglog=1) by adding your email address ($email=youremailaddress). The last option obviously assumes you have followed our previous tutorials and gotten outbound email working reliably on your system. The functions are controlled by the following lines at the top of the checkgroup.php file. 1 means yes, and 0 means no. Just edit the file carefully: nano -w checkgroup.php. And save your changes when you're finished: Ctrl-X, Y, then press Enter.

$debug = 1;
$newlogeachdebug = 1;
$emaildebuglog = 0;
$email = "yourname@yourdomain" ;


Installing teleyapper.php AGI Script. This code is new. New and old readers will need to install the teleyapper.php script in your /var/lib/asterisk/agi-bin directory, change file ownership and permissions on the file, and then set some configuration options. Log in to your Asterisk server as root, and then execute the following commands:

For Asterisk@Home 1.5 users:


cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/aah15/teleyapper.zip
unzip teleyapper.zip
rm teleyapper.zip
chmod 775 teleyapper.php
chown asterisk:asterisk teleyapper.php


For Asterisk@Home 2.2 users:


cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/aah2/teleyapper.zip
unzip teleyapper.zip
rm teleyapper.zip
chmod 775 teleyapper.php
chown asterisk:asterisk teleyapper.php


The teleyapper.php script has a number of configuration options including a debug log. Edit the file carefully while positioned in the correct directory: nano -w teleyapper.php. And save your changes when you're finished: Ctrl-X, Y, then press Enter. All of the options are shown below.

$numcallattempts=3 ;
$calldelaybetweenruns=20 ;
$callspread=1 ;
$debug = 1;
$newlogeachdebug = 1;
$emaildebuglog = 0;
$email = "yourname@yourdomain" ;
$trunk = "sip/telasip-gw" ;
$callerid = "6781234567" ;

The first two options are not yet implemented so leave them alone. The callspread variable determines the spacing of calls to your various callees. The default is one minute which means the call to the second callee begins one minute after the first one starts. If your broadcast message is more than about 20 seconds long, you probably will need to increase this number to 2 to allow sufficient time to complete the first call before the next one begins. Otherwise, calls will fail if you only have a single outbound trunk.

The debug flags in this file are set the same way as in the checkgroup.php script above: 1 means yes, and 0 means no. The default settings are to create a new log file (/var/log/asterisk/teleyapper.txt) each time the script is executed. This doesn't take up much room and is always there for you to read if something comes unglued: cat /var/log/asterisk/teleyapper.txt. There are some other options. You can turn off the log file entirely ($debug=0). You can choose not to erase the previous log file each time the script is run ($newlogeachdebug=0) in which case the file continues to grow until your hard disk fills up. And you can have the log file emailed to you each time the script is executed ($emaildebuglog=1) by also adding your email address ($email=youremailaddress).

[UPDATED: 1/13/05] Two settings you will need to adjust to get ANY calls to complete properly are the trunk and callerid variables. If you wish to use a specific trunk in your dialplan for outbound calls, the syntax for the outbound trunk is the same as it is in your dialplan, e.g. sip/telasip-gw or iax2/voxee. Look at the OUT settings at the top of your extensions_additional.conf file if you're not sure. At the request of a number of users, we've now added a new option which allows all outbound TeleYapper calls to be placed using the default dialplan rules on your server. The advantage of this approach is that different VoIP providers can be used automatically for different types of calls in your TeleYapper database. To use your default dial rules, set the trunk to local and TeleYapper will handle the rest of the setup for you. For those that installed TeleYapper before January 13, simply repeat the download and install steps for teleyapper.php above. Our thanks to both Tracy Carlton at VOIPSpeak and chandave at the Voxilla forum for the default dialplan solution.

The callerid variable should be set to the callerid number of your outbound trunk unless your service provider allows callerid spoofing (most don't!). The callerid setting is ignored if you choose to use your default dialplan rules with a trunk setting of local. Don't delete the variable! Just leave the default value.

Finally keep in mind that the format of the numbers to be dialed in your database must exactly match the syntax your trunk provider is expecting to see unless you're using your default dialplan rules. Otherwise, all of the outbound calls will fail. For example, if your provider requires that calls begin with a 1 followed by a 3-digit area code and 7-digit number, then that's the way the numbers must be entered in your TeleYapper database.

Installing teleyapper2.php AGI Script. This code is also new. Install the teleyapper2.php script in your /var/lib/asterisk/agi-bin directory, change file ownership and permissions on the file, and decide if you want to adjust the default debug configuration setup. Log in to your Asterisk server as root, and then execute the following commands:

For Asterisk@Home 1.5 users:


cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/aah15/teleyapper2.zip
unzip teleyapper2.zip
rm teleyapper2.zip
chmod 775 teleyapper2.php
chown asterisk:asterisk teleyapper2.php


For Asterisk@Home 2.2 users:


cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/aah2/teleyapper2.zip
unzip teleyapper2.zip
rm teleyapper2.zip
chmod 775 teleyapper2.php
chown asterisk:asterisk teleyapper2.php


The only configuration options in the teleyapper2.php script are for the debug log on individual calls that are placed. We recommend you leave the existing settings, or you'll get a new email every time a call is placed by TeleYapper. You can edit the file while positioned in the correct directory: nano -w teleyapper2.php. And save your changes when you're finished: Ctrl-X, Y, then press Enter. All of the options are shown below.

$debug = 1;
$emaildebuglog = 0;
$email = "yourname@yourdomain" ;

The debug flags in this file are set the same way as in the teleyapper.php script above: 1 means yes, and 0 means no. The default settings are to append individual call information onto the teleyapper.txt log file (/var/log/asterisk/teleyapper.txt) each time a new call is placed. Unless you're planning to call hundreds of thousands of people, this doesn't take up much room and is there for you when something comes unglued. The other options are as follows. You can turn off the individual call logging entirely ($debug=0). And you can have the entire teleyapper.txt log file emailed to you each time a call is placed ($emaildebuglog=1) by also adding your email address ($email=youremailaddress). For your initial test calls, this may be desirable just so you can see what's going on ... if you're too lazy to read the log. In the words of Forest Gump, "That's all I wanna say about that."

Taking TeleYapper for a Spin. Once you restart Asterisk (amportal stop then amportal start), you should have a Broadcast Message System that works. First, start up the Asterisk Command Line Interface (CLI) by typing asterisk -r from the command prompt on your system after you’ve logged in as root. Then issue the following command: set verbose 10. The CLI now will track the progress of your TeleYapper sessions.

Using phpMyAdmin, add your cellphone number to your TeleYapper database and specify Group 0 for the entry. Now dial 674 and provide your password, record a message (Option #2), and then place a call (Option #3) to Group 0. Press 1 to kick off the TeleYapper calling spree. Check your CLI and TeleYapper logs if your cellphone doesn't ring in the next two minutes. Enjoy!

TeleYapper Wish List. Some things are still on our TO-DO list, and we'll get to them one of these days. For those with loads of outbound trunks, we'll try to add a feature that lets you adjust the number of simultaneous oubound calls. For those that want to use the system to send out appointment reminders on dates in the future, we've completed that project. Here's the link. TeleYapper does not yet automatically redial failed calls except in the reminder system, but we plan to address that down the road, too. We also plan to build a web interface to the MySQL database which will let you add, edit, and delete entries as well as run some simple reports. If you have other suggestions, post a comment.

Want More Projects? For a complete catalog of all our previous Asterisk projects, click here. For the most recent articles including those you missed over the Christmas and New Year's holidays, click here and just scroll down the page.

From Our Legal Department, moi: The TeleYapper product name (our feeble attempt at humor through parody) has absolutely no affiliation with TeleZapper, the terrific hardware product designed to keep telemarketers from bugging the hell out of you while you're eating your dinner. We confess that our sense of humor got the better of us in coming up with the name for this non-commerical (aka "free") utility designed primarily as an educational vehicle to assist the Asterisk community in recognizing the almost limitless potential of AGI and PHP programming. Our parody seeks to amuse, not to confuse. Our telephony software Yaps. Their telephony hardware Zaps. Other than a telephone line, there is no product similarity as the two conjoined words make clear. And, yes, that is the whole point! The products are opposites, not identical nor even similar. One letter makes all the difference in Night and Light. So it is with Yapper and Zapper. Brand confusion in trademark law arises from synonyms, not antonyms. It is systems like what we're writing about today that TeleZapper is designed to protect against. And it does that very well. In fact, we use TeleZapper hardware in our own home and have for many years. The only problem, of course, is when that tornado comes rolling down the neighbor's street, it would have been nice to get that automated phone call from TeleYapper at the neighborhood headquarters. But, who cares, right? It's only your house. Class dismissed.

Nerd Vittles Allison Fund. One of our next projects will be an Appointment Reminder System. Using a touchtone phone, you can schedule an unlimited number of customized voice reminders for delivery at any future time to any phone numbers you desire. To make it work, we need customized voice prompts for the IVR interface. Some of our future projects will need these as well. Unfortunately, these cost money. Allison, who records the Asterisk voice prompts for Digium, needs to eat. And so do we. We're springing for the costs of these voice prompts up front, but this is your golden opportunity to contribute to the cause. Provided we raise enough money to cover the costs, we'll put the voice prompts in the public domain. If not, when the project is presented, those that didn't contribute will have to record their own voice prompts in order to use the system. The rest will get the Allison prompts either on a password-protected web site or by email. Seems fair, right? To make a $5 or $10 contribution via PayPal using any major credit card, just click on this link. If the pot grows to over a million bucks, we promise never to ask for money again. Thanks in advance for your support.

Who Is This Guy? Ward Mundy, the author of this Asterisk@Home series of articles, is a retired attorney who spent more than 30 years providing legal and technology assistance to the federal courts in the United States. Today he serves as a principal in Ward Mundy & Associates, a technology consulting firm in Atlanta, Georgia.