Category Archives: Telephony

Tom Keating, whose column is one of our must-reads each week, recently wrote a piece about the new Area775 service. In a nutshell, this service attempts to merge the VoIP world with cellphones by giving you one number which simultaneously rings both your cell phone and your IP phone when you receive an incoming call. It also lets you transfer calls from your IP phone to your cellphone and receive your voice mail messages via email. Any of this sound familiar? The only gotcha with the Area775 "free" service is that calls you answer on your cell phone cost you $2 ... each unless you pay a $3.95 monthly fee. Ouch!

For those who have deployed a free Asterisk@Home 2.5 PBX or the new VMware version of Asterisk@Home on your Windows desktop, today we're going to walk you through configuring it to do the same thing at no cost using an IP phone and a phone number in New York or for about a penny a minute for calls answered on your cellphone. If you prefer unlimited incoming and outgoing calls in your area code ($9.95) or throughout the U.S. ($14.95) with no per minute fees, you still can't beat TelaSIP. And our previous column has already demonstrated all the neat CallerID stunts you can perform with a TelaSIP line. If you always wanted to be a Baby Bell, here's your chance.

But, we've digressed. Today, we're going to take the low road and show just how inexpensively you can deploy Follow-Me Roaming or, more accurately, One-Number Roaming using Asterisk@Home. First, you need a phone number to accept incoming calls. Then you'll need an outbound trunk so that calls can be relayed to your cellphone. Finally, we'll show you how to configure Asterisk@Home to either ring your local extensions and your cellphone(s) simultaneously or in a particular order. And, of course, you can transfer calls to your cellphone in a flash. We'll show you how.

Signing Up for a StanaPhone Number. Before you can receive incoming calls from Plain Old Telephones, you'll need a phone number. StanaPhone will give you one for free with a New York area code. Using a Windows PC, head over to StanaPhone.com, sign up for an account, and download their softphone. Once you receive your account number and password, log into their service with the softphone and sign up for a Stana-IN phone number in area code 347. It's FREE! Using your softphone, go to the configuration menu and write down your account number, password, and 347 phone number. Then disconnect from their service and be sure to kill the StanaPhone icon in your toolbar so that you really are disconnected. You can't be registered twice on their system at the same time, and we need that account to use as an inbound trunk on your Asterisk® system.

NOTE: With StanaPhone, you have to "use" their service at least once every 90 days to keep your number. StanaPhone is a little ambiguous about whether incoming calls count as use, but my guess would be that they probably don't. So you might want to make a $5 payment to your StanaPhone account and make at least one outbound call every few months to keep your number activated. Their rates aren't that bad: 1.6¢ a minute to most numbers in the U.S.

Configuring an Inbound Trunk. In Asterisk@Home lingo or for those using plain old Asterisk with the Asterisk Management Portal (AMP), inbound and outbound lines are called Trunks. And, at least for inbound trunks, you need a phone number associated with the trunk (DID) if you expect to receive incoming calls from Plain Old Telephones (POTS).

Now let's create a new Trunk using the Asterisk Management Portal (AMP). Using a web browser, substitute the IP address of your Asterisk server: http://ipaddress/admin/config.php. Login as user maint using the password you established for AMP when you first configured your system. Now click Setup->Trunks->Add SIP Trunk. For Outbound CallerID, enter the phone number assigned to you by StanaPhone. For Maximum Channels, enter 1. Leave the Dial Rules and Dial Prefix blank for the time being.

For Outgoing Settings, enter a Trunk Name of stanaphone. For Peer Details, enter the following using your assigned username and password. Be very careful to match the upper and lower case settings in your assigned password.

host=sip.stanaphone.com
insecure=very
nat=yes
secret=yourpassword
type=peer
username=yourusername


For Incoming Settings, enter a USER Context of from-pstn. This tells Asterisk to process incoming calls through this context in your dialplan. For USER Details, enter the following using your assigned username and password:

canreinvite=no
dtmfmode=rfc2833
host=sip.stanaphone.com
insecure=very
nat=yes
secret=yourpassword
type=peer
username=yourusername


For the Registration String, enter the following using your assigned username, password, and 347 phone number:

yourusername:yourpassword@sip.stanaphone.com/3471234567


Click the Submit Changes button and then click on the Red Bar to save your trunk settings and reload Asterisk. To be sure you have properly registered with Stanaphone, click the Maintenance tab and then Asterisk Info. Under SIP Peers, you should see an entry for sip.stanaphone.com showing a state of Registered. If not, check your username and password entries for typos.

Configuring an Outbound Trunk. Even though we're going to use Asterisk to transparently ring your cellphone whenever you have an incoming call on your inbound number, we still need an outbound trunk to connect the calls to your cellphone once Asterisk detects ringing on the inbound line. Remember, your cellphone isn't technically part of your Asterisk system. For outbound calls using your Asterisk system, you have a lot of choices. And more is better. When a VoIP provider's service goes down, having a a fallback provider is worth its weight in gold.

Payment plans for outbound VoIP calls also vary. You can pay by the minute and make as many simultaneous outbound calls as you like, or you can pay by the month for unlimited calls so long as you place the calls one at a time. For pay-by-the-minute, you can't beat the pricing and quality of calls with Voxee.com. Calls to most of the U.S. and Canada are 1.1¢ per minute billed in six second increments. Calls to Germany and the U.K. are 1.4¢ per minute. For pricing to other destinations, download this spreadsheet. If you prefer an All-You-Can-Eat plan, head over to TelaSIP and then follow our step-by-step tutorial to get it set up as your outbound trunk.

For today, we're assuming you've chosen the Voxee route. So go to their web site, sign up for an account, and put $5 in your account so you can start making calls. Using AMP, choose Setup->Trunks->Add IAX2 Trunk. Maximum channels only matters if you want to restrict how many simultaneous outgoing calls through Voxee can be made. For the Outgoing Dial Rules, enter the following:

1NXXNXXXXXX
1+NXXNXXXXXX

This tells Asterisk to dial outgoing calls through Voxee using a 1 followed by a 3-digit area code and 7-digit phone number. Now skip down to the middle of the form and under Outgoing Settings, name your trunk voxee. For the Peer Details, insert the following using your username and password assigned when you registered for an account:

type=friend
host=66.246.246.52
username=yourVoxeeAcctNumber
secret=yourVoxeePassword


Leave the Incoming section of the form blank since you won't be getting any inbound calls on your Voxee trunk. Now skip down to the Registration field and plug in the following:

YourAcctNoHere:YourVoxeePasswordHere@66.246.246.52

Save your settings and click the Red Bar to reload Asterisk. Check to make sure you're registered in the same way we did it for the inbound trunk with Stanaphone.

Configuring an Outbound Route. Now that we have an outbound trunk set up, we need to tell Asterisk to route outbound calls through this trunk. In AMP it's called Outbound Routing so click on that tab, and then click Add Route. When the blank form appears, enter OutVoxee for the Route Name. Leave the route password and dial pattern blank for now. For the trunk sequence, click on the pull-down and choose IAX2/voxee. Then click the Add button. Finally, click the Submit button and then the Red Bar to update your configuration. If OutVoxee isn't listed as your top (0) route, then click the Up arrow to the right of the entry sufficient times to move it up to the top position. This is the sequence that Asterisk walks through to place outbound calls, and we want to make sure that Voxee is always selected for outbound calls. Click the Red Bar again when you get OutVoxee moved to the top slot.

Configuring an Extension. We're assuming you've already set up your Asterisk@Home system and configured at least one extension. If not, go through our Asterisk@Home 2.5 tutorial, and get one or two extensions working before you continue here.

Configuring Follow-Me Roaming. Now, for the fun part. There are just a few more quick steps in order to enable Follow-Me Roaming with Asterisk@Home and AMP. First, you create a Ring Group to tell Asterisk which extensions or cellphones to ring when an inbound call is detected. Next, you tell Asterisk whether to ring all of the extensions and cellphones at the same time or one after another. And finally, we'll set up an Incoming Route using AMP's Inbound Routing option to tell Asterisk how to process incoming calls on the Stanaphone trunk we previously created. Then, you'll be ready to take your first call.

Creating a Ring Group with AMP. Using AMP, click Setup->Ring Groups to display the Add Ring Group form. Assign an extension to this ring group by entering a number for Group Number. Let's make it 333 to keep things simple. Ring Strategy is where you tell AMP how to process inbound calls to this number. AMP uses what are now called Ring Strategies to handle incoming calls to Ring Groups. You have three choices: ringall, hunt, and memory hunt. Ringall means just what it says. Inbound calls to this number ring all the numbers in the Ring Group simultaneously. Hunt means incoming calls start ringing the first number in the Ring Group and, if there's no answer, move down the list of numbers one at a time until someone answers. Memory Hunt works just like hunt except the second incoming call first rings the second number in the ring group, then moves down the list, and rings the first number in the ring group last.

For our Follow-Me Roaming project today, we want your local Asterisk extension and your cellphone to ring simultaneously so leave the Ring Strategy set to ringall. In the Extension List box, simply type the numbers of the phones you want to ring pressing the Enter key after each entry. For extensions on your Asterisk system, just enter the extension number. For cellphones or other phones that aren't part of your Asterisk system, enter the phone numbers like this: 16781234567# where 1 is the dialing prefix that Voxee expects, 67812234567 is the phone number to call, and the pound sign (#) says call it now. Leave the CID name prefix blank. For the Ring Time, you may need to experiment a bit. We recommend a number of 50 which will force unanswered calls to your cellphone voicemail system. If you don't want that to happen, set it to something like 30. Your local extension(s) will already be ringing while the cellphone call is being established by the way. Finally, tell AMP where to send the call if no one answers including your cellphone's voicemail system. We usually set this to a voicemail box on the Asterisk system which you check regularly or which delivers your voicemail messages via email. Now click the Submit Changes button and then the Red Bar to reload Asterisk.

Creating an Inbound Route. The last step is to configure Asterisk to forward inbound calls on your 347 number to Ring Group 333 which we just set up. Go to AMP->Setup->Inbound Routing. In the blank form which displays, enter your new 347 number in the DID Number and CallerID Number fields. Skip down to the Set Destination section and choose Ring Group 333. Now click the Submit Changes button and then the Red Bar to reload Asterisk.

Placing a Test Call. Using a telephone that's not in your Ring Group and not on your Asterisk system, dial your new 347 number. And, presto. Follow-Me Roaming is now soup. Phones should be ringing all over the place ... including your cellphone. Enjoy!

Ring Group Bug Fix. As luck would have it, there's a bug in the AMP code that causes the hunt and memory hunt Ring Group options not to work. If you want simultaneous ringing of all your inbound calls to all of the numbers in your ring group, then don't worry about it. Just skip this section. But, if you want a perfectly operating Asterisk system (don't we all?), we'll need to make a minor change in the [macro-dial] context of the extensions.conf file. Click AMP->Maintenance->Config Edit and then choose extensions.conf. Now click macro-dial in the left column of contexts. Move down to the line which begins exten => s,22. Immediately after {Huntmembers}, add a right bracket symbol which looks like this: ]. Click the Update button, and you're all set once you reload Asterisk.

Transferring Calls to Your Cellphone. Now that everything is working, let's assume a call has been answered on an extension in your Asterisk network. But now you want to forward the call to an outside number or your cellphone. It's easy. Hit the switchhook once or flash an IP phone by pressing #. At the dial tone, dial 1 plus the area code and number of your cellphone. When the call starts ringing, hang up. Call transferred! Now that wasn't hard, was it?

Hot Tip! O'Reilly's must-have book, Asterisk: The Future of Telephony, is still available for free download here under a Creative Commons license. This is a cleaned up version of the original PDF which fixes pagination and compresses the file size to 3.9MB using Acrobat's Reduce File Size tool. Requires at least Acrobat 4 to load. Special thanks to Alexander Burke for all the hard work cleaning this up.

Some Recent Nerd Vittles Articles of Interest...

It's free software day again at Nerd Vittles, and today we're updating our Telephone Reminder System for Asterisk@Home 2.5. The system 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 that would really show off the platform. The original version of this software got broken with Asterisk@Home 2.4 and later so today we're going to fix it. If you're still running an older version of Asterisk@Home, use our original tutorial and software.

[NOTE: This application has been updated. For the latest article, click here.]

The smarts for this system already have been incorporated into our new TeleYapper 2.5 Voice Messaging System. But that's a real-time system meaning it begins calling immediately after you choose 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. 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! And did we mention? It's still FREE! Some of your fellow readers chipped in to pay for the Allison IVR prompts so those are included at no cost as well.

Prerequisites. We've tested version 2.5 of Telephone Reminders with an ISO-installed version of Asterisk@Home 2.5 only. 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. It won't work with version 1.x of Asterisk@Home, but it'll probably be fine with subsequent releases. Let us know by posting a comment. And the software to schedule reminders is no longer dependent upon the wakeup call system which ships with Asterisk@Home. You should be able to install this project and get everything working in about 30 minutes.

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.

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 own 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. Paste this 2.5 code update to the bottom of the extensions_custom.conf file in the /etc/asterisk directory on your system.

For Step #2, 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 above, 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 original version of the reminder system. To all that contributed, thank you! Whether you contributed to the cause or not, those voice prompts are free for the taking subject to the terms of the license agreement, and they all still work for version 2.5. 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. Now we're getting to the new code for version 2.5. 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:

cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/aah2/reminder25.zip
unzip reminder25.zip
rm reminder25.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


Update: For those using Asterisk@Home 2.7 and those who have applied a yum update after early April 2006 which loaded a new Linux kernel, a problem has been reported by a couple of folks indicating that the reminders fail because the time stamps don't get properly preserved when a reminder is moved to Asterisk's outgoing directory. We haven't seen the problem on our test system but, if you experience the problem with reminders not reminding when they're supposed to, use the following code instead of the above. Our special thanks to Wolf Paul for the fixes including an all-new run_reminders Perl script.

cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/aah2/reminder27.zip
unzip reminder27.zip
rm reminder27.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 Asterisk call processing 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 very bottom of the crontab file. It should go on its own line. There is no longer an entry for wakeup calls (if you read the original tutorial).

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 using the time zone of the Asterisk system running the Telephone Reminders System. 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. An enhancement in version 2.5 is that you now can press the pound key (#) instead of entering an 8-digit date, and the system will set the reminder date to today. 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 using the time zone of the Asterisk system running the Telephone Reminders System. 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/outgoing. The .call files in the outgoing directory are reviewed every minute of the day by Asterisk. By examining the time stamp of the file, Asterisk looks for a match with the current hour and minute of the day. Once the time for the call arrives, Asterisk 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. Note also that, if you begin scheduling a reminder and change your mind and hang up after recording a reminder message, that message will still exist in /var/lib/asterisk/sounds/custom.

Finally, a 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. We hope this has been resolved in Asterisk 1.2.4, but just be alert to the possibility of a problem if multiple calls are scheduled at exactly the same time to different numbers.

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 to give it a whirl.

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, our initial tutorial on Telephone Reminders was the first version of this subroutine written in PHP that actually worked. We've tried to repeat our success here. 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. We 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,"-"));


Finally, it appears that Asterisk's outgoing call queue now relies exclusively on the timestamp of files in the directory to determine when to execute each call. In short, Asterisk no longer uses the name of a file to determine when to execute it. Great idea! That, in turn, means that our reliance on a separate folder for reminders on future dates may no longer be necessary. We haven't finished testing this and wanted to get a working application back in circulation for those that were already using version 1 when AAH 2.5 was released. As soon as we can document that this new functionality is 100% reliable, we will revise the code a bit and eliminate the necessity of using a separate cron job and directory to move files around each day. That also will eliminate the slight delay at midnight which is referenced in the existing tutorial.

Web Interface to Telephone Reminders. We've built a very simple web page that will let you review which reminders are pending on your system. Once installed with the newly enhanced Asterisk@Home Menu System (see below), it can be accessed by going to the IP address of your Asterisk system with a web browser and then choosing the Telephone Reminders button. Or you can access it directly at http://192.168.0.111/reminders/ using the IP address of your Asterisk system. To install the Telephone Reminders web interface, log into your Asterisk system as root and then issue the following commands:

cd /var/www/html
mkdir reminders
cd reminders
wget http://nerdvittles.com/aah2/webreminder.zip
unzip webreminder.zip
rm webreminder.zip


Be advised that we are just getting started with a web interface to the Telephone Reminders application. Stay tuned for loads of additional features!

AAH Web Facelift. Last, but not least, the folks at KennonSoft have posted an update to the AAH web interface (see inset). If you like it, here's how to install it. While still logged into your server as root, issue the following commands:

cd /var/www/html
wget http://www.kennonsoft.com/community/admin-ui.tar
wget http://nerdvittles.com/wp-images/asteridex.png
wget http://nerdvittles.com/wp-images/asterimind.png
tar -xvf admin-ui.tar
rm -f admin-ui.tar
wget http://nerdvittles.com/aah2/index.zip
unzip index.zip
rm -f index.zip


NOTE: It's been reported that there is a display formatting bug with IE 6. Lines 2, 3, 4, and 7 of the code above should all begin with wget. Also be advised that the last three lines of code above get you the third column of icons to support our AsteriDex and Telephone Reminder applications. If you don't want to use these applications, just don't execute the last 3 lines of code above.

If you'd like to use our AsteriDex RoboDialer, install it from the link in this sentence and the icon will get you there. If you've moved your AsteriDex application to a directory different than asteridex, make the necessary adjustment in the index.html file.

Security Reminder. If you plan to open the Asterisk web interface on your system to the public Internet, make sure to take security precautions to reduce the risk of a stranger trashing your system or running up your phone bill. Just click here and search for our articles on security to get your system up to speed.

Wish List? Well, that about covers version 2.5 of our shiny new Reminder System for Asterisk. We have some other bells and whistles we'll be adding over the next few days and weeks so check the bottom of this article from time to time for a New Enhancements section. For example, we plan to add a feature that will let you schedule dates by simply entering the number of days from today and pressing pound. And we want to do something similar for times so that you can enter something like 90# to schedule a reminder for a time slot 90 minutes from now. If you have other enhancement suggestions and recommendations for version 3, we'd love to hear from you. Just post a comment to this topic, and we'll have a look. In the meantime, enjoy!

Want More Projects? For a complete catalog of all our previous Asterisk projects, click here. For the most recent articles, click here and just scroll down the page. Get your Headline News the easy way: Planet Asterisk, Planet Gadget, Planet Mac, and Planet Daily. Quick read, no fluff.

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

Hot Tip! O'Reilly's must-have book, Asterisk: The Future of Telephony, is still available for free download here under a Creative Commons license. This is a cleaned up version of the original PDF which fixes pagination and compresses the file size to 3.9MB using Acrobat's Reduce File Size tool. Requires at least Acrobat 4 to load. Special thanks to Alexander Burke for all the hard work cleaning this up.

New Enhancements. Assuming you have email messaging working on your Asterisk system, Telephone Reminders now has the ability to deliver an email copy of reminders to the recipient in addition to a phone call. Be advised that, if the phone call is never completed, the email copy of the reminder will not be delivered. The reason for this is because Asterisk never passes the call to the context which handles delivery of the email message until the call is connected. So ... no connection, no email. However, if the recipient has an answering machine or voice mail, that would trigger delivery of the email message. If you can live with this shortcoming at least for the time being, here's how to activate delivery of email reminders. First, if you downloaded the Telephone Reminders contexts for extensions_custom.conf before 5 p.m. on Thursday, February 23, do it again from here. Then cut-and-replace only the last two contexts with the matching contexts at the bottom of your extensions_custom.conf file: [remindem] and [remindem2]. Save your changes and reload Asterisk.

Once you've installed the new contexts to support email messaging, step two is registering email addresses for extensions and phone numbers to which you want email reminders delivered. Log in to your Asterisk server as root, and start up the Command Line Interface (CLI): asterisk -r. For each extension and phone number for which you want to activate email reminders, enter a command at the CLI prompt that looks like this: database put EMAIL 6781234567 joe@schmo.com where 6781234567 is the phone number of the reminder recipient and joe@schmo.com is the recipient's email address. You can display all existing EMAIL addresses that have been entered into your Asterisk database with this command: database show EMAIL. If you need to modify an existing entry, simply delete it and reenter it. To delete an existing entry, use the following syntax: database del EMAIL 6781234567.

It's been a busy few weeks with two new versions of Asterisk@Home, but today we're back to the fun stuff: cleaning up the carnage from the new updates. We're beginning with TeleYapper 2.5, an updated version of our Asterisk@Home-based telephone broadcasting service that actually works with Asterisk@Home 2.5 (Asterisk 1.2.4 for "purists"). If you're running an earlier version of Asterisk, use our previous code and tutorial. And, just like the original, TeleYapper 2.5 can be used for neighborhood association announcements, 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 2.5 dialing away is in this article. And functionally, TeleYapper still works identically to version 1. The only problem was version 1 didn't work at all with AAH 2.4 and 2.5. For those new to TeleYapper, here's what happens. 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 2.5 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. But, first things first. We live in a litigious society so let's get the 'Miranda warnings' out of the way.

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. Today's installment provides a good framework for anyone wanting to write Asterisk AGI scripts using PHP with the latest version of Asterisk. 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, perhaps you should consider another endeavor. 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!

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 2.5 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.

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 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've covered some of this in the version 1 articles. 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.

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. Using a web browser, open the Asterisk Management Portal (AMP) by entering the IP address of your Asterisk@Home 2.5 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. Now insert the following chunk of code at 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. Finally insert the following chunk of code at the bottom of extensions_custom.conf:

[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 above 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.

Update: Asterisk 1.4 Modifications. If you plan to use this application on an Asterisk 1.4 system, a few minor changes in the autoattendant and call processing contexts need to be made. See Comment 26 below for details. Thanks, Bill.

Installing checkgroup.php AGI Script. Now let's 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 only works with Asterisk@Home 2.4 or 2.5. To install the teleyapper.php script in your /var/lib/asterisk/agi-bin directory, execute the following commands while logged into your server as root:

cd /var/lib/asterisk/agi-bin
wget http://nerdvittles.com/aah2/teleyapper25.zip
unzip teleyapper25.zip
rm teleyapper25.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.

$maxretries=1 ;
$retrytime=60 ;
$waittime=60 ;
$callspread=1 ;
$debug = 1;
$newlogeachdebug = 1;
$emaildebuglog = 0;
$email = "yourname@yourdomain" ;
$trunk = "local" ;
$callerid = chr(34) . "TeleYapper" . chr(34) . " <6781234567>" ;

The first three options are implemented but not fully tested. If you have more than one outbound trunk and you're using the local trunk setting, give us some feedback. What it's supposed to do is retry failed calls. 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).

Two settings you will need to review and perhaps adjust to get 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 in all lowercase letters to local and TeleYapper will handle the rest of the setup for you.

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. 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:

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.

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!

Real-World Test of TeleYapper. Be sure to check out our follow-up article on TeleYapper for a real-world example dialing 700+ neighbors with information about a rezoning meeting.

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 appointment reminders on dates in the future, we've completed that project for AAH 1.5 and 2.2. Here's the link. Within the next week or so, we'll have a new version that supports Asterisk@Home 2.5. We also plan to build a web interface to the TeleYapper 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, click here and just scroll down the page. Get your Headline News the easy way: Planet Asterisk, Planet Gadget, Planet Mac, and Planet Daily. Quick read, no fluff.

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

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.

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.

Some Recent Nerd Vittles Articles of Interest...

We've discussed inbound CallerID with Asterisk® in a previous column, but today we have an incredibly useful outbound CallerID trick. Our special thanks to Matt Avila for bringing it to our attention. As you probably know, most providers don't allow you to adjust the CallerID for your outbound calls. But there are exceptions such as Teliax. The only problem until now has been that using CallerID spoofing required that you pay for outbound calls by the minute. Well, if you're using Asterisk@Home 2.5 or Asterisk 1.2.4, all of that has changed ... with TelaSIP. As long time readers of this column know, in addition to being dirt cheap and honest, TelaSIP has always been our favorite provider, and this neat trick is merely icing on the proverbial cake. You can read all the other reasons why you should switch at this link.

NOTE: This article has been superseded. Continue reading the latest article here.

CallerID spoofing, despite the negative connotation, isn't always a bad thing. Let's cover a few real-world examples. The one we use that has been incredibly helpful is our One Ringy-Dingy free long distance calling service (which is sponsored by TelaSIP incidentally). Try it! Just dial our number in Charleston from a phone with CallerID, wait for a fast busy (so there's no charge for the call), hang up, and you'll promptly receive a return call. After entering the system provided random password, you'll get dialtone to make a free 10-minute long distance call to anywhere in the United States. What we wanted to do with this DISA outbound calling service was to provide the caller's CallerID number to the person being called rather than displaying either our CallerID number or no CallerID. Remember, both the called and calling parties are receiving incoming calls from our Asterisk server using TelaSIP trunks rather than from the actual caller's home or office phone line. That's why the call is free. By the way, we're using GSM compression for these calls so it will give you a good idea of what the call quality is like using a voice compression codec.

A more practical use is for those of you with multiple outbound trunks, multiple DIDs, and multiple users (such as kids), each of whom has (or at least wants) their own extension and outside phone number. With the new TelaSIP service and Asterisk@Home 2.5, you now can automatically customize your CallerID to meet your requirements using the Asterisk Management Portal (AMP). And today we'll show you how. For the truly evil out there, a word of caution. Failure to "send accurate originating calling party telephone number information" on interstate calls may violate the Federal Communications Act. In fact, that is exactly what we use CallerID spoofing to do: to send accurate originating calling party telephone number information, i.e. the true identity of the calling party. If you abuse this or any other service, the feds may very well track you down. And TelaSIP probably feels the same way if you abuse their service. See this article for details. Don't ruin a good thing by being a jerk. You will get caught. Asterisk logs make it incredibly easy to find (and hang) you.

Using AMP to Manage Incoming TelaSIP Calls. Let's start by examining what we want to accomplish. Suppose you have a single VoIP trunk with TelaSIP, but you have three teenagers that love their privacy and would like their own line. With TelaSIP, it's easy. Just order a single VoipXpress Premium account with unlimited U.S. inbound and outbound calling ($15.95) and two additional DID's in your favorite area code ($1.99 a month each), and you're all set. According to some readers, you may need to request that TelaSIP let you manage your own CallerID so you might want to include that in your note when you sign up. If you're feeling like a big spender, order an additional trunk just to use for inbound calls ($5.95) and add your two DID's to that trunk. That gives you two lines and four DIDs in your choice of area code for about the same monthly cost as a single Vonage line with a single DID. When you receive your username and password from TelaSIP, configure the TelaSIP outbound trunk settings in AMP using the example below (with your account name and password obviously) after naming the trunk TelaSIP-gw or TelaSIP-gw2:

disallow=all
allow=gsm
canreinvite=yes
context=telasip-in
dtmfmode=rfc2833
fromuser=youracctname
host=gw4.telasip.com
insecure=very
secret=yourpassword
sendrpid=yes
type=peer
username=youracctname

Leave the Incoming Settings section of AMP blank, and fill in your Register String in this format: youracctname:yourpassword@gw4.telasip.com.

You'll need the fromuser entry above if you're running more than one TelaSIP account on the same Asterisk server so TelaSIP can figure out how to route the call. If you have loads of bandwidth in both directions, delete the first two lines to use an uncompressed codec (ulaw): disallow=all and allow=gsm. All of the CallerID magic depends upon the line which reads sendrpid=yes. This tells TelaSIP that you'll be responsible for setting the CallerID for each outbound call over this trunk.

We could use AMP's DID Configurator to manage the inbound calls, but we've just never quite trusted AMP on this. Can you spell B-U-G-G-Y. Plus, our manual way isn't very hard and it gives you some extra flexibility. So add a new context at the bottom of extensions_custom.conf (AMP->Maintenance->Config Edit->extensions_custom.conf). Replace 8431234567 with the DID number for this line, replace the 201 in SIP/201 with the extension to be dialed for this call, and replace the 201 in 201@default with the voicemail account for this extension. To add a second trunk and extension, just duplicate the seven lines of code in the same context and repeat the drill using the second DID and extension. Save your changes and reload Asterisk. You're supposed to know how to do this by now!

[telasip-in]
exten => 8431234567,1,Answer
exten => 8431234567,2,Wait(1)
exten => 8431234567,3,Background(pls-hold-while-try)
exten => 8431234567,4,NoOp(Incoming call for Suzie on TelaSIP #8431234567)
exten => 8431234567,5,Dial(SIP/201,20,m)
exten => 8431234567,6,VoiceMail(201@default)
exten => 8431234567,7,Hangup

exten => 8431234568,1,Answer
exten => 8431234568,2,Wait(1)
exten => 8431234568,3,Background(pls-hold-while-try)
exten => 8431234568,4,NoOp(Incoming call for Timmy on TelaSIP #8431234568)
exten => 8431234568,5,Dial(SIP/202,20,m)
exten => 8431234568,6,VoiceMail(202@default)
exten => 8431234568,7,Hangup

Suppose you want to add a DID which automatically transfers inbound calls on that number to your cellphone, but you want to preserve the original caller's CallerID so you can see where the incoming call on your cellphone is coming from. Why would you want to do this? Well, it keeps your cellphone number a secret and gives you unlimited flexibility to block calls from creeps. Just search around on Nerd Vittles for the tutorials if you want to get fancy. You'll need two trunks from TelaSIP to make call transfers to your cellphone work. Or just sweet talk Gene into adding a second channel on your original trunk ... for a few cents more. It saves them the headache of maintaining two separate accounts for you. In this case, just adjust the number of channels in your trunk configuration to 2 instead of the original 1 setting.

For the example below, we'll assume you chose not to go the sweet talk route, and that telasip-gw is your inbound trunk with the extra DIDs and telasip-gw2 is your outbound trunk. You don't need extra DIDs for the outbound trunk since we can spoof the CallerID. Just add the code below to your [telasip-in] context using your DID number instead of 8431234569, your cellphone number instead of 6781234567, and whatever Asterisk voicemail box you want to use instead of 203 just in case your cellphone voicemail fails to pick up the call wihin 60 seconds.

exten => 8431234569,1,Answer
exten => 8431234569,2,Wait(1)
exten => 8431234569,3,Background(pls-hold-while-try)
exten => 8431234569,4,NoOp(Incoming call for Billy Bob cell on TelaSIP #8431234569)
exten => 8431234569,5,SetCallerID(${CALLERIDNUM})
exten => 8431234569,6,Dial(sip/6781234567@telasip-gw2,60,m)
exten => 8431234569,7,VoiceMail(203@default)
exten => 8431234569,8,Hangup


Managing Outbound CallerID for Different Extensions. We've resolved how to manage incoming calls with multiple DIDs and users. Now let's tackle the other issue. We want outbound calls from each extension to look like they came from different phone numbers even though we'll be using one outbound trunk to handle all the calls (not at the same time obviously). Of course, if you need simultaneous outbound calls, you can add additional outbound trunks, and we'll show you how to configure the outbound dialing to support it.

One of the great improvements in AMP 1.10.010 which is bundled with Asterisk@Home 2.5 is the ability to manage CallerID for individual extensions. For this to work, leave the CallerID entry in your TelaSIP trunk entries blank. Then, as you create your extensions (201 and 202 in the example above), fill in the CallerID you want to associate with outgoing calls from each extension in the Outbound CID field. If you want this setting to override your default trunk CallerID, be sure to use brackets around the number, e.g. <4041234567>. (Thanks, Matt!) Save your settings and click the Red bar to reload Asterisk. The only trick to this is making sure that your Outbound Routing in AMP is configured to route outgoing calls to your appropriate TelaSIP trunks for placing outgoing calls. If you want to use multiple TelaSIP trunks for outbound calls, then simply add each TelaSIP trunk name in the Trunk Sequence for your outbound route, and Asterisk will go down the list when your first priority trunk is busy. It doesn't get much easier than that.

But what about the cellphone? How do we make outbound calls from our cellphone using the CallerID number from one of the DIDs on the Asterisk system? Well, that's what DISA is for. Just add the following code above the 8431234569 lines in the sample assuming your cellphone number is 6781234567. Why do we require a password for the incoming call when we've specified the number of your cellphone? Because you aren't the only person on the planet that can spoof CallerID numbers. So change the password in line 3 to something VERY SECURE. It's your phone bill!

exten => 8431234569/6781234567,1,Answer
exten => 8431234569/6781234567,2,Wait(1)
exten => 8431234569/6781234567,3,Authenticate(1234)
exten => 8431234569/6781234567,4,DISA(no-password|telasip-out)
exten => 8431234569/6781234567,5,Hangup()


Next add the following code at the very bottom of your extensions_custom.conf file after all of the [telasip-in] code, save your changes, and reload Asterisk.

[telasip-out]
exten => s,1,Background(pls-hold-while-try)
exten => s,2,SetCallerID(8431234569)
exten => s,3,Dial(local/${EXTEN}@from-internal)
exten => s,4,Hangup

Then, to place outbound calls from your cellphone, "Phone Home" to 8431234569 and enter your DISA password. When you get dialtone, key in the number to call in a format that matches your outbound trunk(s) dialplan. When the phone rings at the other end, it will display the CallerID of your home DID trunk. Now wasn't that easy!

Some Recent Nerd Vittles Articles of Interest...

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