Search Results for: allison ivr

We began our 15-minute adventure last week with a turnkey install of Asterisk® onto a $199 Everex gPC2 using a fully-customized version of PBX in a Flash. If you haven't yet read the first article, start there. Today we want to cover what components are included and walk you through using most of them. When we're finished, you'll have a good idea why PBX in a Flash is not only different but also a quantum leap forward in the turnkey IP telephony marketplace. We'll also cover adding RAID 1 redundant drive support to your new server for about $40.

Putting Your Backup System Into Operation. Hopefully, you heeded our recommendation and purchased a $20 4GB USB flash drive to store backups of your new PBX in a Flash system. Cheap insurance! Now let's put it into production. In the /root folder of your new system, you'll find a PDF with complete documentation for the new Mondo Rescue backup system. If you flip to Appendix A, it will walk you through formatting your new flash drive for use with the backup software. Basically, you're going to delete the existing partitions on the drive, repartition it as a FAT32 partition (don't use the existing partition even if it says FAT32!!), and then reformat the drive. It takes under a minute to do it all. Once you're finished, let's initiate a backup just to be sure everything is working. Log into your server as root and type /etc/cron.weekly/disk-backup.cron. When the command prompt returns in about 30 minutes, type /root/usbcheck.sh to get a listing of the files on your USB flash drive. Now you can sit back and relax knowing that every Sunday night a new full system backup will be loaded onto your flash drive. Should something go horribly wrong with your main drive down the road, it's a simple matter to burn CDs of the ISO backup and reload everything, the same process you used to build your new system in the first place. Remember, we provided you a Mondo Rescue backup to build your system from ours so you know it works. For us at least, having automatic backups of your data is a critical component in any computer system, particularly your entire telephone system. While Asterisk aggregations are a dime a dozen these days, no one else has implemented any backup solution except PBX in a Flash.

Text-to-Speech on Steroids. The next thing you need to do is install Cepstral with Allison on your system. This gives something close to perfect text-to-speech capability for your entire phone system for under $25. And, yes, you can try it out first without spending a dime. Log into your server as root and type install-cepstral. Accept the defaults except create the missing directory when prompted. You're done. That was hard wasn't it. We'll test it out in a few minutes.

PiaF Software Update Service. At least for now, the PBX in a Flash Software Update Service continues to be a free option on all PBX in a Flash systems so by all means use it to keep your system current, bug-free, and secure. Log into your server as root and type update-scripts. Once the new scripts are loaded onto your system, type update-fixes. Yes, you can build an Asterisk system from many other ISO distributions. But you won't find another one that can keep your system current and secure without starting all over with a new ISO install. And when you want the latest and greatest version of Asterisk without missing a beat, that's easy, too. Just type update-source and have a cup of coffee while your system is upgraded. And don't forget to run update-fixes one more time to clean up any mess created by the upgrade.

Help at Your Fingertips. And, what if you forget all of these commands down the road and you're too lazy to pull out the documentation? Not to worry! Log into your server as root and type help-pbx.

What's Next? Now that you have a stable, secure, and up-to-date server, let's have some fun. We've loaded and preconfigured most of the Nerd Vittles applications in this build so all you have to do is learn the numbers to dial to use most of the applications. Here's a quick thumbnail sketch for each of the applications:

• AsteriDex RoboDialer and Telephone Directory
  This app gets you a phonebook, a web-based dialer using a browser or your cellphone, and a CallerID lookup source when used in conjunction with Ultimate CNAM. To add and update entries or lookup numbers, point your web browser to the IP address of your server: http://ipaddress/asteridex4/. For cell phone access, point the web browser on your cellphone to the public IP address or fully-qualified domain name of your server: http://publicIPaddress/cellphone/. Click on the link above for complete documentation and security suggestions.
• Telephone Reminders 4.0 with Support for Recurring Reminders and Web-based TTS Reminder Messages
  This app lets you schedule reminders for future events by telephone (dial 1-2-3) or with a web browser (http://ipaddress/reminders/). When the appointed date and time arrives, Asterisk swings into action and places a call to the number you designate to deliver a customized reminder message. Recurring reminders (daily, weekday, weekly, monthly, and annual) also are supported. And the text-to-speech web interface lets you schedule and deliver reminders using either Flite or Cepstral-generated messages with any web browser. For more info, click on the link above.
• NewsClips for Asterisk featuring Dozens of Yahoo News Feeds (TTS) - Dial 5-1-1
• Weather Reports by Airport Code (TTS) - Dial 6-1-1
• Weather Reports by ZIP Code (TTS) - Dial Z-I-P
• Worldwide Weather Forecasts (TTS) - Dial 6-1-2
• MailCall for Asterisk: Get Your Email By Telephone (TTS)
  This app reads your emails to you over the telephone. Some setup is required to plug in information about your email account. Once configured, dial 5-5-5 to retrieve your messages. Click on the link above for setup instructions.
• TeleYapper 4.0 Message Broadcasting System - Dial M-S-G (licensed for non-commercial use only!)
• CallWho for TTS Retrieval and Dialing of Entries in the AsteriDex Database (TTS)
  After entering contacts in AsteriDex, run http://serverIPaddress/asteridex4/dialcode.php to populate the dialcodes. Then dial 4-1-2 and enter the first three letters of anyone in your AsteriDex database to place a call.
• TFTP Server with preconfigured setups for 15 Aastra 57i SIP telephones - See setup instructions in last week's article

Of course, there are literally hundreds of things you can do with your PBX in addition to running the Nerd Vittles applications. Here's a short list of some of our favorites with some tips to get you started. The best source of information for more detail is our original article on PBX in a Flash 1.2 and the PBX in a Flash Forum.

• Stealth AutoAttendant with Welcome and Application IVRs
  Whenever an incoming call comes into your PBX, a generic greeting will play. If no button is pressed on the caller's phone, the call then will be routed to a ring group (700) for all of the extensions set up in that ring group. If no one answers, the call will be sent to the voicemail box for extension 701. While the greeting message is playing, the caller can press a digit on their phone to activate a hidden option in the Main IVR. As delivered, the only one that works is 0. This presents the caller with a list of Nerd Vittles apps from which to choose. You can add other options by modifying the Main IVR settings in FreePBX. To try out the Main IVR from any extension on your system, dial 7-7-7.
• Key Telephone Support Using Park and Parking Lot
  Most PBXs do not support shared line appearances like the old key telephones from Ma Bell. With these phones you could answer a call, place it on hold, and then someone else could pick up the call by pressing the blinking light on their phone. Our Aastra phone setup does much the same thing except, instead of placing a call on hold, you press the Park button. The parked extension number then will be read to you by Allison (starting with 71). Anyone else on your system can retrieve the parked call by pressing the ParkLot button on their Aastra phone and selecting the call to be retrieved by CallerID. Or, if the recipient knows the parking lot extension (e.g. 71), the recipient can pick up any phone and dial that extension number to retrieve the call.
• Intercom/Paging Support
  The Aastra phone setup for PBX in a Flash fully supports intercom calls and paging by pressing the ICom button on the phone. For more information, click Setup, Paging and Intercom from within the FreePBX web interface.
• Bluetooth Proximity Detection with Automatic Call Forwarding to Cell Phone
  Your system is preconfigured to support a USB Bluetooth dongle. No additional software installation is required. When properly configured, this lets you automatically forward your calls to your cellphone just by leaving your home or office with your Bluetooth-enabled cellphone. When you return, your calls will magically begin ringing on your local extension again. Click the link above for setup instructions.
• DISA
  Direct Inward System Access lets you call into your PBX and get dialtone to make an outbound call. To use it, you typically would add it as a hidden option on your IVR with a very secure password. We have preconfigured DISA support on your server. Just be sure you change the password to something very secure before activating it. To change the password, click Setup, DISA, DISAmain in FreePBX. Then save your changes and reload the Asterisk dialplan.
• Blacklisting with Web and Telephony Interfaces
  To block future calls from the last person who called you, dial *32. To block calls from a specific phone number, dial *30. To remove a number from the blacklist, dial *31. You also can use FreePBX to blacklist certain numbers. Just click Setup, Blacklist to access the web interface.
• CallerID Name Lookups from 8 Providers
  Most telephony providers reliably pass CallerID numbers but discard CallerID name info. With Ultimate CNAM which is preinstalled on your system, you can look up CallerID names from up to 8 different directory providers. To activate it, use FreePBX and click Setup, Inbound Routes, DefaultIncoming. Scroll down to CID Lookup Source and choose Ultimate CNAM from the dropdown box. Save your changes and reload the dialplan. For complete documentation, consult cnam_user_guide.pdf in the /root folder on your server. To choose the providers to use for the lookups, log into your server as root and type: cnam-config.pl
• Weekly Automated System Backups to a Flash Drive
  See the first section of today's article for the one-minute setup instructions.
• One Touch Day/Night Service
  With our Aastra phone setup, there is a DayNite button that toggles your system between Day and Night operation. As configured, the Night option transfers all calls to voicemail for extension 701. The Day option routes all incoming calls through the Main IVR which routes calls to the 700 Ring Group on timeout. To activate Night service from an Aastra phone, just press the DayNite button. To deactivate Night service, just press the button again. You also can dial *28 from any phone on your system to toggle Day/Night mode.
• Music on Hold
  Royalty-free music on hold is provided as part of the basic Asterisk install. Additional music can be added through the Music on Hold option in FreePBX. WAV files must be PCM Encoded, 16 Bits, at 8000Hz. See this thread for assistance. For other royalty-free and free music on hold, start here, choose Creative Commons for the License Type, and then click Go.
• Voicemail with Email Delivery of Messages and Pager Notification
  All of these settings are performed within FreePBX for each extension. Choose Setup, Extensions, and pick one of the extensions you already have created. Make certain that Voicemail Status is enabled. Then enter a valid email address and pager address. To include the voicemail as an attachment in the delivered email message, set Email Attachment to Yes. To include the CallerID in the voicemail message, set Play CID to Yes. To include the date and time of the call, set Play Envelope to Yes. To delete the voicemail message from the system after emailing it, set Delete Vmail to Yes. Don't ever do this until you're sure it's working reliably! If you want the option of calling back the caller when you retrieve your voicemail message by phone, set VMoptions to callback=from-internal. Submit your changes and reload the Asterisk dialplan to put the modifications into effect. If the emails are not delivered, then it may be because your ISP is blocking downstream SMTP traffic. To reconfigure your server to use gMail or Comcast as your SMTP host, click on one of the links.
• Voicemail Blasting
  This feature allows you to record a message and distribute it via voicemail to one or more extensions without actually calling the users. We've already configured extension 500 to send voicemail blasts to extensions 701 and 702. You can adjust the destinations in FreePBX by choosing Setup, Voicemail Blasts, Vmail (500). You also can add additional extensions to handle voicemail blasts to a different group of phones.
• Cell Phone Direct Dial
  There are two ways to make a cellphone an integral part of your PBX. The first involves setting up a specific extension for each cellphone and forwarding incoming calls to that extension to your cellphone. We've created extension 501 to show you how it's done. Once the extension is created, simply log into your server as root and issue a command like this where 6781234567 is your actual cellphone number:
  
asterisk -rx "database put CF 501 6781234567"

  When callers dial 501 on your system, your cellphone will automatically ring. Another option is to use FreePBX's Follow Me function under Setup. With this option, you can specify multiple destinations for incoming calls to a specific extension. Point to the Ring Strategy option and review the available choices. Choose the one that best meets your needs. Then enter the numbers to be called. Numbers outside your PBX should be in the format 6781234567# and must match your outbound dialing rules. You also can choose the time to attempt the call and what to do if no one answers. Very slick!
  
• Call Forward: All, Busy, No Answer
  While you can certainly use FreePBX's Follow Me functionality to accomplish any flavor of call forwarding, you also can dial codes from any extensions to activate call forwarding. To activate Call Forwarding All, dial *72; for Call Forwarding Busy, dial *90; for Call Forwarding No Answer, dial *52. To deactivate Call Forwarding All, dial *73; for Call Forwarding Busy, dial *91; for Call Forwarding No Answer, dial *53. To deactivate Call Forwarding All from a different extension, dial *74; for Call Forwarding Busy, dial *92. You also can activate and deactivate Call Forwarding from any Aastra phone using our default setup.
• Call Waiting
  To activate Call Waiting from any extension (which is the default), dial *70. To deactivate Call Waiting, dial *71.
• Call Pickup
  To pickup a call ringing on another extension, dial **.
• Zap Barge
  To barge into an existing call, dial 888.
• Call Transfer: Attended and Blind
  For attended call transfers where you can remain on the line until the other party answers, dial *2. For unattended call transfers, dial ## and then the number to which the call should be transferred.
• Dictation Service with Email Delivery
  Before using FreePBX's dictation service, you must activate Dictation Services for the specific extension to be used. Using FreePBX, go to Setup, Extensions, and click on the desired extension. Scroll down to the Dictation Services section of the form and enter your email address, the format of the sound files to be used, and change Dictation Service to Enabled. Save your settings and reload the dialplan. Then you can dictate your message by dialing *34. Once you finish your dictation, you can email it to your email address for this extension by dialing *35.
• Do Not Disturb
  To activate Do Not Disturb on any extension, dial *78. To deactivate Do Not Disturb, dial *79. There's also a button to accomplish the same thing with our Aastra phone setup.
• Phonebook Dial by Name - Dial 4-1-1
• VoiceMail Options
  To retrieve your voicemail from any phone, dial *97. To retrieve voicemail for a different extension, dial *98 or *98701 where 701 is the extension desired. To leave a voicemail message for any extension with voicemail enabled, dial *701 where 701 is the extension desired.
• Speed Dial
  To set up a user speed dial entry, dial *75. To call any previously established speed dial entry, dial *0 plus the speed dial number. To create or modify speed dial entries in FreePBX, click Tools, Asterisk Phonebook. You also can import entries from a CSV-formatted file.
• Flite and Cepstral Text to Speech (TTS)
  Flite TTS is installed by default with all PBX in a Flash systems using Asterisk 1.4. The Asterisk developers have broken Flite in the Asterisk 1.6-beta and refuse to fix it. Cepstral can be installed using the directions below with Asterisk 1.4 and 1.6-beta. To use Flite with Egor in your dialplan, here's the syntax:
  
exten => 444,5,Flite("Hello World.")

  To use Cepstral with Allison in your dialplan, use this syntax:
  
exten => 444,5,Swift("Hello World.")

• One-Click (almost) Cepstral TTS Install with Allison
  If our code didn't have a bug, you could have typed install-cepstral to install Cepstral. Instead, you need to type the following three commands:¹
  
sed -i 's|Cepstral_Allison-8kHz_x86-64|Cepstral_Allison-8kHz_i386|'↵
/usr/local/sbin/install-cepstral
sed -i 's|x86-64-linux|i386-linux|' /usr/local/sbin/install-cepstral
install-cepstral

  For detailed instructions on reconfiguring Nerd Vittles apps to use Cepstral instead of Flite, see this article. No software needs to be reinstalled. Simply change the dialplan and PHP app settings to use Cepstral as explained in the article. For more background on Cepstral, read this article. To register your newly installed Allison voice, go to this link. Be sure you select U.S. English language, Allison-8kHz voice, and Linux platform before you check out, or it's money down the drain. For 20% off your Cepstral license registration, use promo code “REALLUSIONTTS” when you check out. Write down the name, company (optional), and key that is issued once you fill in the blanks. Then log into your server as root, and type swift --reg-voice. Fill in the blanks with the information you wrote down above, and you're all set.
• Windows Networking with SAMBA
  Windows Networking with SAMBA is enabled by default in this special build. The default workgroup is "workgroup." To change the workgroup, log into your server as root and edit /etc/samba/smb.conf. Then restart SAMBA: service smb restart. You then can connect to your server from any computer that supports Windows networking using root as your username and whatever root password you created.
• Linux Firewall
  The IPtables firewall is enabled by default in all PBX in a Flash systems. For this build, we have enabled SAMBA access to your server. To disable it, log into your server as root, and issue the following commands:
  
cp /etc/sysconfig/iptables.nosamba /etc/sysconfig/iptables
service iptables restart

• WebMin
  WebMin is often described as the Swiss Army Knife of Linux. It provides a terrific web interface to Linux.everything. It is enabled by default in this install. To access it using a web browser, go to http://serverIPaddress:9001/ and login as root with the password you set up above for WebMin access. For complete documentation, go here.
• PBX in a Flash Software Update Service To Keep Your System Current
  To load current fixes for this build of PBX in a Flash, log into your server as root and type the following commands:
  
update-scripts
update-fixes

  To upgrade your system to the latest version of Asterisk 1.4, log into your server as root and type the following commands:
  
update-scripts
update-source
update-fixes


More Good News with the Everex gPC2. From the "Learn Something New Every Day Department," this news just in. The Everex gPC2 has built in hardware SATA RAID 1 support that actually works. What you'll need to get this going is a second 80GB hard disk to match the one delivered in your original box. Total cost: about $40. If one disk fails, the other kicks in automatically. Here's a link to purchase your drive. And here's the link that'll tell you how to get everything set up. Before you begin, make certain that you have a current ISO backup on your flash drive so that you can restore your system once the RAID setup is up and running. See the top of this article for the backup and testing procedure.

Special Thanks to Our Generous Sponsors

FULL DISCLOSURE: ClearlyIP, Skyetel, Vitelity, DigitalOcean, Vultr, VoIP.ms, 3CX, Sangoma, TelecomsXchange and VitalPBX have provided financial support to Nerd Vittles and our open source projects through advertising, referral revenue, and/or merchandise. As an Amazon Associate and Best Buy Affiliate, we also earn from qualifying purchases. We’ve chosen these providers not the other way around. Our decisions are based upon their corporate reputation and the quality of their offerings and pricing. Our recommendations regarding technology are reached without regard to financial compensation except in situations in which comparable products at comparable pricing are available from multiple sources. In this limited case, we support our sponsors because our sponsors support us.

BOGO Bonaza: Enjoy state-of-the-art VoIP service with a $10 credit and half-price SIP service on up to $500 of Skyetel trunking with free number porting when you fund your Skyetel account. No limits on number of simultaneous calls. Quadruple data center redundancy. $25 monthly minimum spend required. Tutorial and sign up details are here.

The lynchpin of Incredible PBX 2020 and beyond is ClearlyIP components which bring management of FreePBX modules and SIP phone integration to a level never before available with any other Asterisk distribution. And now you can configure and reconfigure your new Incredible PBX phones from the convenience of the Incredible PBX GUI.

VitalPBX is perhaps the fastest-growing PBX offering based upon Asterisk with an installed presence in more than 100 countries worldwide. VitalPBX has generously provided a customized White Label version of Incredible PBX tailored for use with all Incredible PBX and VitalPBX custom applications. Follow this link for a free test drive!
 

Special Thanks to Vitelity. Vitelity is now Voyant Communications and has halted new registrations for the time being. Our special thanks to Vitelity for their unwavering financial support over many years and to the many Nerd Vittles readers who continue to enjoy the benefits of their service offerings. We will keep everyone posted on further developments.
 

Some Recent Nerd Vittles Articles of Interest...

1. Join the text of a following line when you encounter this character: ↵ [↩]

Well, okay. We confess that today's creation doesn't quite measure up to the legendary Orgasmatron... but, look out Woody Allen, we're close. It's been a couple of years since we released our first preconfigured, turnkey Asterisk® install. Much has changed both in Asterisk and in the hardware and software environment since 2006. So today, to celebrate the six month anniversary of PBX in a Flash and the brand new PBX in a Flash 1.2 release, we're taking another stab at it. From the time you insert the CD 'til you have a functioning Asterisk PBX with all the bells and whistles imaginable... 15 minutes!

NOTE: This article and the Orgasmatron software have been updated. Click here to read the new article.

Coming January 19: Incredible PBX 11 & Incredible Fax for Asterisk 11 and FreePBX 2.11

Our approach today is a little different than the last time around. The processing overhead of CentOS 5.1 has made VMware problematic. Luckily, the price of hardware has dropped like a rock. So today we're comfortable recommending the best phone, the best PC, and the best provider on the planet. And you'll still have your arms and legs intact after you pay the piper. If you've been following along with our articles, you already know that we've identified what we believe to be the perfect Asterisk SIP phone, the Aastra 57i, and we've also identified a perfect small business/home computer on which to run a production Asterisk server for about 50 employees, the Everex gPC (aka "The WalMart Special"). Now that the second generation Everex gPC2 is readily available, we decided to preconfigure one of these systems from the ground up and then make a 2-disk ISO image backup of the whole system using Mondo. So, once you download the ISO images and burn your CDs, it's a 15-minute No-Brainer to install the entire image onto your own Everex gPC2. But you must have a gPC2 for this to work so accept no substitutes, and don't try this with any other hardware or you'll end up with an Electronic Brick instead of an Orgasmatron. The $199 gPC2 systems are available from WalMart and NewEgg among others.

We've preconfigured outbound and incoming trunks from some terrific providers as well as some extensions on your new system. So you literally can sign up for service with these providers, plug in your phones, and you can be in full operation in under an hour. Our only word of caution is not to use these ISO images on another type of computer. Everything has been specifically tailored to the stock gPC2 and chances are very good that the install would not proceed much past erasing and reformatting your hard disk on a different flavor machine. We also recommend that, if you want to add our recommended $25 extra gig of RAM to the gPC2, hold off on installing it until after you have loaded the new ISO image. So... what do you get with this preconfigured build?

In addition to all of the goodness of a stock PBX in a Flash 1.2 build including Asterisk 1.4 running under CentOS 5.1 with all the latest and greatest versions of FreePBX, Apache, MySQL, and PHP, you also get 10 preconfigured Nerd Vittles applications for openers:

• AsteriDex RoboDialer and Telephone Directory
• Telephone Reminders with Support for Recurring Reminders and Web-based TTS Reminder Messages
• NewsClips for Asterisk featuring Dozens of Yahoo News Feeds (TTS)
• Weather Reports by Airport Code (TTS)
• Weather Reports by ZIP Code (TTS)
• Worldwide Weather Forecasts (TTS)
• MailCall for Asterisk: Get Your Email By Telephone (TTS)
• TeleYapper 4.0 Message Broadcasting System
• CallWho for TTS Retrieval and Dialing of Entries in the AsteriDex Database (TTS)
• TFTP Server with preconfigured setups for 15 Aastra 57i SIP telephones

In addition, you get dozens of preconfigured telephony applications and functions that would take even an expert the better part of a year or two to build independently. And, unlike all of the other distributions, we build Asterisk from source so it's simple to modify and upgrade whenever you feel the need. Here's a short list of what you have to look forward to:

• Stealth AutoAttendant with Welcome and Application IVRs
• Key Telephone Support Using Park and Parking Lot
• Intercom/Paging Support
• Bluetooth Proximity Detection with Automatic Call Forwarding to Cell Phone
• DISA
• Blacklisting with Web and Telephony Interfaces
• CallerID Name Lookups from 8 Providers
• Weekly Automated System Backups to a Flash Drive
• One Touch Day/Night Service
• Music on Hold
• Voicemail with Email Delivery of Messages and Pager Notification
• Voicemail Blasting
• Cell Phone Direct Dial
• Call Forward: All, Busy, No Answer
• Call Waiting
• Call Pickup
• Zap Barge
• Call Transfer: Attended and Blind
• Dictation Service with Email Delivery
• Do Not Disturb
• Gabcast
• Phonebook Dial by Name
• Speed Dial
• Flite Text to Speech (TTS)
• Windows Networking with SAMBA
• Linux Firewall
• PBX in a Flash Software Update Service To Keep Your System Current
• One-Click Cepstral TTS Install with Allison... Just Type install-cepstral

Prerequisites. As mentioned, you'll need a $199 Everex gPC2 (WalMart or NewEgg ) to use this build. We also recommend an additional $25 gig of RAM for anything other than home use. We also recommend a 4GB USB flash drive on which to store automatic weekly backups of your new system. Finally, you'll need to cough up a whopping $5 to download the two-disk ISO image for this build. And, yes, we eat our own dog food. The ISO images you'll be downloading were captured as a backup on the flash drive of our gPC2 lab machine. If you use this special build, it seemed only fair that you cover the cost of the bandwidth to download it. As most of you know, we don't have the luxury of freeloading off SourceForge for our downloads. And we didn't want to impose upon our existing bandwidth providers to bring you this custom image. The good news is that, once you download the image from DreamHost, you are more than welcome to pass it along to one or more of your friends or business acquaintances at no charge. You can even do it electronically through the DreamHost Files Forever program. And, if you'd like to host this image for your fellow man at no cost, be our guest... and thank you! Bottom line: For about $250, you'll have the slickest, most reliable PBX on the planet with rock-solid weekly backups and, of course, the one-of-a-kind PBX in a Flash Software Update Service!

Getting Started. Once you have purchased your Everex gPC2, take it out of the box, plug it into your LAN with DHCP and DNS support and Internet connectivity. Having said that, we strongly recommend that you always keep your system running behind a NAT-based firewall/router. Almost any home router will do. Don't redirect any ports to the machine and don't turn the PC on just yet.

Download the two ISO images for the gPC2 from here. If you don't know how to create a CD from an ISO image, read that section from our article last week. In fact, read the whole article. It'll help you immensely down the road. Once you have the two CDs in hand, turn on the gPC2 and quickly insert Disk 1 into the CD/DVD drive and close the drive. If you don't see a Mondo Rescue screen within a minute or less, turn the machine off and then back on again. At the Mondo Rescue main screen, type nuke and press the Enter key. This will erase, repartition, and reformat your hard disk in case you didn't know. This is normal. If you get any kind of errors about incorrect drive or partition names, halt the install by pressing CTL-ALT-DEL and remove the CD. You'll need to install PBX in a Flash using our standard ISO which is available here. Otherwise, go have a cup of coffee and come back in about 12 minutes. When prompted, insert Disk 2 and press the Enter key to finish the install. When the CD ejects, remove it and your gPC2 will reboot after you type exit.

After the reboot finishes, type root at the login prompt for your username and password for your password. The IP address assigned by your DHCP server should appear near the top of the screen. Write it down. If there is no IP address, your machine does not have network connectivity or access to a DHCP server with an available IP address. Correct the problem and reboot.

Securing Passwords. We're going to change five passwords now. For the time being (until you've done some reading), think up one really difficult password (that you won't forget) and use it for all five passwords. At the root@pbx:~ $ command prompt, type the following commands and type in your new password when prompted. Don't forget your password or you'll get to put in your two CDs and start over.

passwd
passwd-maint
passwd-wwwadmin
passwd-meetme
/usr/libexec/webmin/changepass.pl /etc/webmin root yournewpasswordhere


Now, using a web browser, go to the IP address of your new PBX in a Flash server. Click Administration. Log in as admin:password. Then click Menu Config. Change Admin Pwd to a new password that you're NOT using elsewhere. Now click Update and then Done. Click Administration again and then Asterisk Mgmt (FreePBX). If you're prompted for username and password, use admin:password for now. After FreePBX loads, click Setup and then Administrators. In the far right column, click admin, fill in your new password, and click Submit Changes. Then do the same thing for maint. Finally, click on the orange Apply Configuration Changes button and then Continue with Reload. Whew!

Don't change any other passwords without first contacting us. Regardless of what you may read elsewhere, PBX in a Flash is now secure. If you want more details, read this article and this thread.

Permanently Setting the IP Address. There are different schools of thought on whether to use a fixed or dynamic IP address. Most hardware-based routers support DHCP IP address reservations. The simplest way to permanently secure the existing IP address for your server is to reserve it on your router. If you'd prefer to assign your own IP address, we have included the deprecated netconfig utility which can be run after logging into your server as root. Sometimes you will need to run it once, enter your settings, reboot, and then repeat the drill. Then you should be all set.

Adding Plain Old Phones. Before your new PBX will be of much use, you're going to need something to make and receive calls, i.e. a telephone. For today, you've got several choices: a POTS phone, a softphone, or a SIP phone (highly recommended). Option #1 and the best home solution is to use a Plain Old Telephone or your favorite cordless phone set (with 8-10 extensions) if you purchase a little device (the size of a pack if cigs) known as a Sipura SPA-1001. It's under $60. Be sure you specify that you want an unlocked device, meaning it doesn't force you to use a particular service provider. Once you get it, plug the SPA-1001 into your LAN, and then plug your phone instrument into the SPA-1001. Your router will hand out a private IP address for the SPA-1001 to talk on your network. You'll need the IP address of the SPA-1001 in order to configure it to work with Asterisk. After you connect the device to your network and a phone to the device, pick up the phone and dial ****. At the voice prompt, dial 110#. The Sipura will tell you its DHCP-assigned IP address. Write it down and then access the configuration utility by pointing your web browser to that IP address.

Once the configuration utility displays in your web browser, click Admin Login and then Advanced in the upper right corner of the web page. When the page reloads, click the Line1 tab. Scroll down the screen to the Proxy field in the Proxy and Registration section of the form. Type in the private IP address of your Asterisk system which you wrote down previously. Be sure the Register field is set to Yes and then move to the Subscriber Information section of the form. Assuming you're using the preconfigured extensions starting with 701, do the following. Enter House Phone as the Display Name. Enter 701 as the User ID. Enter 1234 as the Password, and set Use Auth ID to No. Click the Submit All Changes button and wait for your Sipura to reset. In the Line 1 Status section of the Info tab, your device should show that it's Registered. You're done. Pick up the phone and dial 1234# to test it out.

Downloading a Free Softphone. 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 another great SIP/IAX softphone for all platforms that's great, too, and it requires no installation: Zoiper 2.0 (formerly IDEfisk). All are free! Just install and then configure with the IP address of your PBX in a Flash server. For username and password, use one of the extension numbers and passwords which you set up with freePBX. Once you make a few test calls, don't waste any more time. Buy a decent SIP telephone. We think the best phone out there is the Aastra 57i for under $200. Another $100 buys you the Aastra 57i CT with a cordless DECT phone.

Configuring Aastra 57i SIP Phones. Your new system comes preconfigured to automatically configure up to 15 Aastra 57i phones. Plug each phone into your network and wait for it to boot. Once it boots, press the Option button, then Phone Status (3), then IP & MAC Address (1). Write down each phone's IP address and MAC address. Then press Done to exit from the menus.

Next, we need to tell your phone to use your new server as the TFTP server to obtain its setup. Press the Option button again, then Admin Menu (5). Type 22222 for the admin password and press Enter. Then choose Config Server (1), then TFTP Settings (2), then Primary TFTP (1), enter the IP address of your new server, and press Done a half dozen times.

Log back into your server. Switch to the TFTP directory: cd /tftpboot. You'll notice that there are config files for up to 15 phones. Simply choose the extension number you wish to use for each phone and rename the file from 701.cfg to the MAC address of each phone.cfg. Do NOT use hyphens in the MAC address. One final step and you'll be ready to load up your phones. We need to set the correct IP address to tell each phone where your server is located. So... issue the following command using the IP address of your new server instead of 192.168.0.123. Leave the rest of the command as it is!

sed -i 's|192.168.0.0|192.168.0.123|g' /tftpboot/aastra.cfg


Now restart each phone by pressing the Option button and then Restart Phone (6) and then the Restart button. Once the phone reboots, you can make a test call by dialing 1-2-3-4. You can get the latest news by dialing 5-1-1. Or get a weather forecast by airport code (6-1-1) or zip code (Z-I-P).

A Word About Ports. For the techies out there that want to configure remote telephones or link to a server in another town, you'll need to know the ports to remap to your new server from your firewall. Here's a list of the ports available and used by PBX in a Flash. We don't recommend exposing UDP 5038 which is used to communicate with Asterisk via the Asterisk Manager.

TCP 80 - HTTP (needed if you want to access the web sites on your new server from the Internet)
TCP 22 - SSH (needed if you want remote SSH access)
TCP 9001 - WebMin (needed if you want remote WebMin access, not recommended)
UDP 10000-20000 - RTP (needed for SIP communications)
UDP 5004-5037 - SIP (ditto)
UDP 5039-5082 - SIP (ditto)
UDP 4569 - IAX2 (needed for IAX communications typically between Asterisk servers)


Setting Up Trunks for Outgoing and Incoming Calls. If you want to communicate with the rest of the telephones in the world, then you'll need a way to route outbound calls (terminations) to their destination. And you'll need a phone number (DIDs) so that folks can call you. Unlike the Ma Bell world, you need not rely upon the same provider for both. And nothing prevents you from having multiple outbound and incoming trunks to your new PBX. At a minimum, however, you do need one outbound trunk and one inbound phone number unless you're merely planning to talk to other extensions set up on your system. We've actually put all the hooks in place to make it easy for you to interconnect to other Asterisk servers, but we'll save that for another day. For today, we want to get you a functioning system so that you can place outbound calls to anywhere in the world and can receive incoming calls from anywhere in the world. Thanks to our friends at Vitelity, this is not only an easy process, but it's also an incredible deal... but only for PBX in a Flash users.

Vitelity: The Best Provider and Pricing on the Planet. If you're seeking the best flexibility in choosing an area code and phone number plus the lowest entry level pricing plus high quality calls, then Vitelity is the hands-down winner. Vitelity provides Tier A DID inbound service in over 3,000 rate centers throughout the US and Canada. And, when you use our special link to sign up, the Nerd Vittles and PBX in a Flash projects get a few shekels down the road while you get an incredible signup deal as well. The going rate for Vitelity's DID service is $7.95 a month which includes up to 4,000 incoming minutes on two simultaneous channels with terminations priced at 1.45¢ per minute. Not any more! For PBX in a Flash users, here's a deal you can't (and shouldn't) refuse! Sign up before the end of June, and you can purchase a Tier A DID with unlimited incoming calls for just $3.79 a month and you get a free hour of outbound calling to test out their call quality. To check availability of local numbers and tiers of service from Vitelity, click here. Do not use this link to order your DIDs, or you won't get the special pricing! After the free hour of outbound calling, Vitelity's rate is just 1.44¢ per minute for outbound calls in the U.S. You can't beat the price OR the call quality! Trust us. We've tried just about everybody. Update: This offer has been extended until July 15.

To sweeten the pot a bit more, we've preconfigured both inbound and outbound Vitelity trunks for you. For the vitel-inbound trunk, all you'll need to do is plug in your username, password, and host assigned by Vitelity and adjust the registration string to match your assigned username and password. In FreePBX, click Setup, Trunks, SIP/vitel-inbound and make the changes. Then adjust the vitel-outbound trunk to reflect your actual username in the fromuser and username entries, your real password in the secret entry, and the correct host provided by Vitelity for your outbound calls, and you're all set. In FreePBX, click Setup, Trunks, SIP/vitel-outbound and make the changes.

To test things out, pick up a phone configured on your system and dial an area code and number of someone in the United States or Canada. Now get someone to call you using your new number. Presto! You have inbound and outbound phone service.

An Alternate Outbound Calling Solution. As we said, it costs you almost nothing to add an alternate outbound calling solution to your new system. As luck would have it, adding a second outbound calling provider is now a breeze because AOL just entered the SIP terminations market with a product called AIM Call Out. We wrote about it recently, and you can read the article here. All you need is an AOL or AIM account name and $5 to get you started. The system you've just installed is preconfigured to use AIM Call Out. All you have to do is plug in your username and password, and you can immediately make calls to anywhere in the United States for under 2¢ per minute. Adding international calling is as easy as inserting the correct dial string. If you never use it, it doesn't cost you a dime. So $5 is mighty cheap insurance in our book.

First things first. Sign up for the service at this link. Your username will look something like this: johndoe@aim.com. You also will be assigned a password. Using your web browser, open FreePBX by pointing to the IP address of your new server and choosing Administration, then FreePBX. Type in admin as your username and the password you assigned to your system. From the main FreePBX menu, choose Setup, Trunks, and click on SIP/AIM in the far right column. Scroll down to the Peer Details section of the form and replace yourAIMpassword with your new password. Then replace yourAIMaccountname with your actual AIM account name. Now click the Submit Changes button and then Apply Configuration Changes and Continue with Reload.

Setting Up an Alternate DID for Incoming Calls. You also may want to consider a second phone number where people can call you. For example, if Grandma and Grandpa happen to be in another state and still have an old fashioned telephone, you might consider adding an additional DID to your system in their area code. They then can make a local call to reach you by dialing the local DID. On the les.net pay-as-you-go plan, it costs less than a dollar a month plus a penny a minute for the calls. Money well spent if we do say so... and you'll sleep better.

If this setup looks a bit complicated, don't be intimidated. Remember, we're connecting your PBX to the rest of the world so people can call you! With les.net, you have a choice of rate plans for most DIDs. You either can pay $3.99 a month for unlimited inbound calls with two concurrent channels or 99¢ per month and 1.1¢ per minute with four concurrent channels. Just visit their site and click Signup to register. Once you are registered, click Login and then Order DIDs. Pick a phone number. Then click Peers/Trunks and Create New Peer. Write down the Peer Name as you will need it in a minute to set up your connection. Choose SIP for Peer Technology, RFC2833 for DTMF Mode, G.711 for Codecs, Registration for Peer Type, enter the public IP address of your server for Peer Address, make up a secure password and write it down also, specify an Outbound CallerID for your calls, and check the 10-digit dialing box. Leave voicemail unchecked since you'll handle this on your end. Save your changes.

Now choose Your DIDs and click on the one you just ordered. We now need to tie the phone number to the Peer setup you just created above. Click on the DID and select the Route to Peer which you just created. Check the Send DID Prefix box and leave everything else blank. Click Save Changes and you're finished at the les.net end. Now let's set up your inbound DID trunk in Asterisk using FreePBX.

Log into FreePBX using a web browser. Click Setup, Trunks and then Add SIP Trunk. Fill in the CallerID and then drop down to the Outgoing Settings section of the form. For Trunk Name, use the Peer Name that you created above and wrote down. It ought to look something like this: 1092832198. For Peer Details, enter the following using the Peer Name and Password you assigned at les.net:

canreinvite=no
context=from-trunk
fromuser=1092832198
host=did.voip.les.net
insecure=very
nat=yes
secret=yourpassword
type=peer
username=1092832198

For Incoming Settings, use from-pstn for the User Context and enter the following User Details:

canreinvite=no
context=from-pstn
dtmfmode=rfc2833
insecure=very
nat=yes
type=user

For the registration string, enter a string like the following using your Peer Name and Password:

1092832198:yourpassword@did.voip.les.net/1092832198

Now click the Submit Changes button and then Apply Configuration Changes and Continue with Reload.

Choosing a Preferred Provider. Finally, you'll need to decide whether to use AOL or Vitelity as your primary terminations provider. HINT: Vitelity is less costly. So we've set them up as your primary terminations provider with AOL as the backup. This is handled in FreePBX in the Outbound Routes tab under the AllCalls entry.

A Word About Mondo Rescue. We would be remiss if we didn't mention what a fantastic open source product Mondo Rescue is. It's the sole reason that today's build was possible. Our special thanks go to the development team: Bruno Cornec, Andree Leidenfrost, and Hugo Rabson. It is the first (and only) backup software for Linux builds that actually works reliably. The best way to prove that for yourself is to download this build and try it for yourself on your Everex gPC2. It has much more flexibility than what you will experience, but that would take another dozen pages to explain. We'll save that for another day. In the meantime, if you'd like more information, visit the Mondo Rescue web site.

Where To Go From Here. Well, we've covered a good bit of territory today so we're going to save the really fun stuff for our next installment. In the meantime, you have a new phone system that works. And there are a number of PDF documents in the /root folder on your new system which are worth a read. Better yet, you can browse through all of the documentation which is available for PBX in a Flash by going here. You also can dial D-E-M-O on your new system and see just how powerful direct SIP connections can be to other Asterisk hosts (in this case, ours!)... at no cost. Finally, you can log into your server and type help-pbx for access to a treasure trove of additional features. Enjoy!

Continue reading Part II...

Special Thanks to Our Generous Sponsors

FULL DISCLOSURE: ClearlyIP, Skyetel, Vitelity, DigitalOcean, Vultr, VoIP.ms, 3CX, Sangoma, TelecomsXchange and VitalPBX have provided financial support to Nerd Vittles and our open source projects through advertising, referral revenue, and/or merchandise. As an Amazon Associate and Best Buy Affiliate, we also earn from qualifying purchases. We’ve chosen these providers not the other way around. Our decisions are based upon their corporate reputation and the quality of their offerings and pricing. Our recommendations regarding technology are reached without regard to financial compensation except in situations in which comparable products at comparable pricing are available from multiple sources. In this limited case, we support our sponsors because our sponsors support us.

BOGO Bonaza: Enjoy state-of-the-art VoIP service with a $10 credit and half-price SIP service on up to $500 of Skyetel trunking with free number porting when you fund your Skyetel account. No limits on number of simultaneous calls. Quadruple data center redundancy. $25 monthly minimum spend required. Tutorial and sign up details are here.

The lynchpin of Incredible PBX 2020 and beyond is ClearlyIP components which bring management of FreePBX modules and SIP phone integration to a level never before available with any other Asterisk distribution. And now you can configure and reconfigure your new Incredible PBX phones from the convenience of the Incredible PBX GUI.

VitalPBX is perhaps the fastest-growing PBX offering based upon Asterisk with an installed presence in more than 100 countries worldwide. VitalPBX has generously provided a customized White Label version of Incredible PBX tailored for use with all Incredible PBX and VitalPBX custom applications. Follow this link for a free test drive!
 

Special Thanks to Vitelity. Vitelity is now Voyant Communications and has halted new registrations for the time being. Our special thanks to Vitelity for their unwavering financial support over many years and to the many Nerd Vittles readers who continue to enjoy the benefits of their service offerings. We will keep everyone posted on further developments.
 

Some Recent Nerd Vittles Articles of Interest...

Today we're pleased to introduce TeleYapper 4.0, an updated, Asterisk® 1.4-compatible version of our telephone broadcasting service (aka phone blasting software). For those with text-to-speech capabilities on your PBX in the form of either Flite or Cepstral, today's addition adds support for individualized, text-based messages to everyone in a group distribution list. And, for those with multiple outbound trunks, TeleYapper 4.0 supports simultaneous calls using multiple trunks. Version 4 works with PBX in a Flash, of course. And it should work well with trixbox 2.x and later versions of Asterisk@Home. If you're using an earlier version of Asterisk@Home, see our previous versions and tutorial.

For those that have never used TeleYapper, let us give you a quick summary of the product. It's an automated message broadcasting service commonly known as a call blasting or phone blasting system. In addition to loads of creepy uses, phone blasting has a legitimate purpose. TeleYapper is licensed for the following uses: to send prerecorded phone messages for neighborhood association announcements, school closings, tornado alerts, little league practices, fund raisers, municipal government reminders, and for just about any other non-commercial purpose. We'll have more to say about the licensing restrictions on this product in a minute.

Everything you'll need to get TeleYapper 4.0 dialing away is in this article. And functionally, TeleYapper still works identically to prior versions with a few embellishments. For those new to TeleYapper, here's how. 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 PBX in a Flash and some other Asterisk distributions. Once your distribution list is set up, 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 message recipients. 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) PBX in a Flash system. Look at the top of this page (just below the Nerd Vittles header) for links to Windows, Mac, and Linux versions of PBX in a Flash that are perfectly suited for use with TeleYapper. Today we'll actually get TeleYapper making calls and emailing you the results of those calls. Don't be intimidated by this technology. You can complete this project in under 5 minutes. If you're using one of our PBX in a Flash systems, then installation of TeleYapper 4.0 is a one-minute install. Either way we've done most of the hard work for you. All you'll need to do is create your call distribution groups.

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. But we try pretty hard to write reliable code. 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 our previous article concerning Do Not Call statutes in your jurisdiction. 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. TeleYapper 4.0 also provides a good framework for anyone wanting to write Asterisk AGI scripts using PHP. The code is well-documented to demonstrate how to pass variables to an AGI script from your dialplan and how to retrieve variables from an Asterisk AGI script into your dialplan. We needed this for TeleYapper because we're using a phone call to an Interactive Voice Response (IVR) session embedded in the dialplan to begin the calling process. We use the IVR session not only to determine which group of callees to call but also to give the caller the option of placing a call to everyone in the group or just those to whom the initial call was unsuccessful. After the caller hangs up, the results are passed to the teleyapper.php application to do the heavy lifting. The PHP program takes advantage of an AGI script's ability to actually set dialplan code in motion once a call is answered. In order to log calls and track which ones are successful, we have to pass variables into that dialplan code and then execute another PHP script when the call is completed. Stated another way, every call requires two round-trips from the Asterisk dialplan to PHP/AGI scripts. So, if you can't figure out how to pass variables back and forth using this application, you probably should consider another line of work. For those that just want to use the TeleYapper application and not learn much of anything about programming, you're welcome to do that subject to the license agreement which follows. We hope you'll put it to good use for the betterment of a school, an intramural sports program, or a neighborhood or community in which you happen to 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 and purchase 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 M-S-G (extension 674) from a phone connected to your PBX, TeleYapper 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 and you populate your new database below, or you'll get smoke. When 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, canceling the transaction, or just redialing the numbers of the calls that failed to this group on the previous pass through the database.

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:

• Caller with TeleYapper password places call to M-S-G (extension 674) to activate a TeleYapper session.
• Asterisk answers the call, provides IVR menu choices: playback a message, record a new message, or place a call.
• If caller chooses to place a call, IVR prompts for Group number to call (0-9).
• Asterisk passes the Group number to MySQL (checkgroup.php) to look up the number of callees in the chosen Group.
• Group count is passed back to Asterisk which uses Allison to tell the caller how many callees are in the chosen Group.
• Caller has option of placing the call, hanging up, or choosing to redial previously unsuccessful calls in the chosen Group again.
• If caller chooses to place a new call, Asterisk thanks the caller, hangs up, and then passes control to teleyapper.php to handle placing the calls.
• TeleYapper time stamps dialing scripts two minutes apart for each call beginning two minutes after the initiating request. Scripts are placed in the Asterisk outgoing calls queue.
• TeleYapper initializes the date/time and status fields for each record in the Group to be called. These are only filled in when a call is then answered.
• If you've enabled logging in teleyapper.php, then the log is generated after all of the call setups have been completed.
• If you've enabled emailing of the teleyapper.php log, then the log is emailed to your email address at the same time.
• Asterisk checks its call queue each minute and places each call at the appointed time. Then it waits for the callee to answer.
• If no one answers the call, nothing is posted to the MySQL database regarding call completion. That's how we identify unsuccessful calls.
• If the call is answered, the callee is advised to hold for an important message. If the msg field for this callee is blank, then the prerecorded message is played to the caller.
• If the msg field has a message in it, then either Flite or Cepstral is used to read the custom message to the callee.
• Callee is then prompted to press 1 to acknowledge the call and hang up, press 2 to replay the message, or press 3 to remove the callee from the database.
• If callee presses 1, Allison says goodbye and Asterisk hangs up the call. MySQL database will show date/time of call with status of OK.
• If callee presses 2, your message is replayed, and then the call is disconnected. MySQL database will show date/time of call with ReplayedMsg as status.
• If callee presses 3, log will reflect that caller requested blacklisting. MySQL will actually DELETE this person from your database. It's the LAW!
• If callee makes no choice, Asterisk will replay your message, then hang up, and record the date/time of call with status of AnsMachine.
• If you've enabled logging in teleyapper2.php, then the individual call log is generated and appended to the main log file after each call has been placed.
• If you've enabled emailing in teleyapper2.php, then the call log is emailed to your email address after EACH call has been placed.

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

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

Installing TeleYapper 4.0 The real beauty of PBX in a Flash as an Asterisk platform is demonstrated by the ease with which you can install new applications such as this one. The drill is very simple. You download an install script, make it executable, and run it. Less than a minute later, the TeleYapper install is done. For those that want to take advantage of the new text-to-speech option in TeleYapper to deliver customized messages to callees, we've included an option in the installer that preconfigures TeleYapper for either Flite or Cepstral so you don't have to touch your dialplan. This can be changed later by replacing Flite with Swift or vice versa in the [broadcast] and [broadcast2] contexts in your extensions_custom.conf dialplan code. Here are the commands to execute to install TeleYapper after logging into your PBX in a Flash system as root:

cd /root
wget http://bestof.nerdvittles.com/applications/teleyapper4/teleyapper.pbx
chmod +x teleyapper.pbx
./teleyapper.pbx


Adding Entries to the TeleYapper Database. We use the 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.

The install script created the MySQL database to support TeleYapper. The easiest way to work with MySQL databases is to use the phpMyAdmin which is accessible through the Tools tab in FreePBX on PBX in a Flash systems. You'll need to login as maint with your maint password to access phpMyAdmin. After phpMyAdmin loads, click on the teleyapper database in the left column. Then click the teleyapper.callees table entry in the left column to open the file. Now 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. Only fill in the msg field if you want to deliver a customized message (rather than your prerecorded message) to this callee. And, remember, this functionality only works if you have Flite or Cepstral installed and working on your system. Flite works by default on all PBX in a Flash systems. Cepstral you have to pay for. See our Cepstral article if you'd prefer to use Cepstral with Allison's voice for this and other Nerd Vittles text-to-speech applications.

Where were we? You can add up to two MySQL records at a time with phpMyAdmin 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 recreate the database table again.

Answering the Incoming Call. A simple addition to your dialplan is used to force Asterisk to answer calls to M-S-G (extension 674) and pass them to the TeleYapper contexts for processing. The following code has been inserted into the [from-internal-custom] context near the top of 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)


Once you change the password, save your changes and reload the Asterisk dialplan.

If you're using FreePBX, we recommend you also make the following addition to your FreePBX configuration. Log into FreePBX with a web browser. Then choose Setup, Misc Destination. Add a new entry for TeleYapper with 674 as the Dial entry. Save your change and reload the dialplan when prompted to do so.

Configuring checkgroup.php AGI Script. The checkgroup.php script was installed in your /var/lib/asterisk/agi-bin directory as part of the installation. 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 tutorial 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" ;


Configuring teleyapper.php AGI Script. The teleyapper.php script has a number of configuration options including a debug log. Edit the file carefully while positioned in the /var/lib/asterisk/agi-bin 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.

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

The first line lets you set the number of simultaneous calls which can be placed. Be sure you have sufficient outbound trunks to support the number you insert and be sure to use the "local" setting for $trunk unless you know what you're doing. The callspread variable determines the spacing of calls (or groups of calls if you have multiple outbound trunks) to your various callees. The default has been changed from one minute to two minutes based upon extensive testing with large numbers of calls. This means the call to the second callee (or group of callees if you have specified $maxlines > 1) begins two minutes after the first call starts. Because a broadcast message is usually more than about 20 seconds long, we have found the 2 minute setting to be better since it allows sufficient time to complete the first call before the next one begins. Otherwise, calls will start failing if you only have a single outbound trunk. If you're going to be placing hundreds of calls, be sure to read our previous article which covers a real-world example using a 700-call database.

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 in your /etc/asterisk/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 (some don't!). 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. Do NOT use hyphens or other punctuation in the phone number entries!

Configuring teleyapper2.php AGI Script. 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 each individual 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.

Changing the Initial Greeting. When TeleYapper places calls, it initially announces the call before playing your prerecorded message or customized text-to-speech messages. The default greeting is "Hi. Please hold a moment for an important message." This may not be appropriate for what you plan to do so we've added several more from which you can choose. The greetings all are stored in /var/lib/asterisk/sounds/custom. The one that actually plays is nv-yapintro.wav. So just choose the one you like and copy it over as nv-yapintro.wav. The choices include the following:

• nv-yapintro-reminder.wav - Please hold a moment for an important reminder.
• nv-yapintro-pubsvcmessage.wav - Please hold a moment for an important public service message.
• nv-yapintro-safety.wav - Please hold a moment for an important safety alert.
• nv-yapintro-school.wav - Please hold a moment for an important message from your school.
• nv-yapintro-team.wav - Please hold a moment for an important message from your team.
• nv-yapintro-message.wav - Please hold a moment for an important message.

Taking TeleYapper for a Spin. Once you restart Asterisk (amportal restart), you should have a TeleYapper System that works. First, start up the Asterisk Command Line Interface (CLI) by typing asterisk -rvvvvv from the command prompt on your system after you've logged in as root. 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 about two minutes.

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

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-commercial (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 the automated phone call from TeleYapper at the neighborhood headquarters. But, who cares, right? It's only your house. Class dismissed.

64-bit PBX in a Flash IS Ready for Testing. For those of you with 64-bit systems, you really need to try our new 64-bit version of PBX in a Flash. Some are reporting more than a 200% performance improvement over the 32-bit version. If you'd like to try out the 64-bit release, contact Joe Roper through the PBX in a Flash Web Site for a link to the download. The following processors reportedly support 64-bit code:

Intel NetBurst
Intel Xeon (some models since "Nocona")
Intel Celeron D (some models since "Prescott")
Intel Pentium 4 (some models since "Prescott")
Intel Pentium D
Intel Pentium Extreme Edition
Intel Core microarchitecture
Intel Xeon (all models since "Woodcrest")
Intel Core 2 (Including Mobile processors since "Merom")
Intel Pentium Dual Core (E2140, E2160, E2180, T2310, T2330 and T2370)
Intel Celeron (Celeron 4x0; Celeron M 5xx)
AMD Athlon 64
AMD Athlon 64 X2
AMD Athlon 64 FX
AMD Opteron
AMD Turion 64
AMD Turion 64 X2
AMD Sempron ("Palermo" E6 stepping and all "Manila" models)
AMD Phenom


Coming Soon for Bleeding Edgers. If you really like living on the edge, there will be an Asterisk 1.6 version of PBX in a Flash shortly for experimentation purposes only. I spoke with Tom King by phone using a functioning 1.6 build today, and everything worked swimmingly including most of the FreePBX 2.4 functionality. The design is the same as the current PBX in a Flash system with the latest Asterisk 1.6 beta code, of course, and all the goodies needed to support it in the familiar LAMP environment consisting of Linux, Apache, MySQL, and PHP. Stay close to the PBX in a Flash Forum for the 1.6 ISO announcement!

Do You Get It Yet? With the roll-out of these new ISOs, even the slow-learners should be starting to see why a carefully designed, source-based LAMP install of Asterisk is so compelling. Until now, not a single PBX in a Flash user ever has had to reinstall PBX in a Flash from scratch. A few button clicks is all it takes to transform the original PBX in a Flash ISO into a current, virtually bug-free system with the latest and greatest versions of Asterisk, FreePBX, and CentOS. And issues raised on our forums are addressed in minutes, not weeks or months. Pretty neat if we do say so. Give PBX in a Flash a try. You'll be glad you switched. 40,000+ downloads in four months and four days kinda says it all.

Munin Comes to PBX in a Flash. With special thanks to Andrew Gillis for his pioneering work in porting munin to the Asterisk LAMP environment, we are pleased to announce that a one-minute install of munin is now available for PBX in a Flash. For those unfamiliar with munin, it is a fantasic, web-based server monitoring and management tool that now has customized add-ons to support Asterisk.everything. You can read up on munin and download the installation script from the PBX in a Flash Forum.

Aastra 2.2 Firmware Update. For those heeding our advice and using the World's Best Asterisk Phone, the Aastra 57i, there's a terrific firmware update that's 100% compatible with the existing Nerd Vittles Aastra phone design. This update adds dozens of new features and fixes the one concern of losing the transfer and forward buttons when a second incoming call arrives. The new features include:

• Group Paging via RTP Multicast
• Call Forward and DND for each account
• One-touch Call Transfer to BLF Extensions and SpeedDials
• Intercom and AutoAnswer Enhancements
• and many, many more...

Just download the update from here, copy the unzipped 57i.st file into /tftpboot on your PBX in a Flash server, and restart your phones. It's as simple as that.

Conversational Linux for Windows Users. Last, but not least, Joe Roper, one of the key players on the PBX in a Flash Development Team, has a great Linux for Newbies tutorial that should be available in the next couple weeks. If you're a Windows user and want to learn all of the Linux basics in a simple, Plain-English tutorial, this is the document for you. The document will be made available on pbxinaflash.com and pbxinaflash.net at no cost although Joe does accept consultancy work when you have a project that demands a bit more expertise. A portion of that income is generously plowed back into the PBX in a Flash development project. Stay tuned!

Special Thanks to Our Generous Sponsors

FULL DISCLOSURE: ClearlyIP, Skyetel, Vitelity, DigitalOcean, Vultr, VoIP.ms, 3CX, Sangoma, TelecomsXchange and VitalPBX have provided financial support to Nerd Vittles and our open source projects through advertising, referral revenue, and/or merchandise. As an Amazon Associate and Best Buy Affiliate, we also earn from qualifying purchases. We’ve chosen these providers not the other way around. Our decisions are based upon their corporate reputation and the quality of their offerings and pricing. Our recommendations regarding technology are reached without regard to financial compensation except in situations in which comparable products at comparable pricing are available from multiple sources. In this limited case, we support our sponsors because our sponsors support us.

BOGO Bonaza: Enjoy state-of-the-art VoIP service with a $10 credit and half-price SIP service on up to $500 of Skyetel trunking with free number porting when you fund your Skyetel account. No limits on number of simultaneous calls. Quadruple data center redundancy. $25 monthly minimum spend required. Tutorial and sign up details are here.

The lynchpin of Incredible PBX 2020 and beyond is ClearlyIP components which bring management of FreePBX modules and SIP phone integration to a level never before available with any other Asterisk distribution. And now you can configure and reconfigure your new Incredible PBX phones from the convenience of the Incredible PBX GUI.

VitalPBX is perhaps the fastest-growing PBX offering based upon Asterisk with an installed presence in more than 100 countries worldwide. VitalPBX has generously provided a customized White Label version of Incredible PBX tailored for use with all Incredible PBX and VitalPBX custom applications. Follow this link for a free test drive!
 

Special Thanks to Vitelity. Vitelity is now Voyant Communications and has halted new registrations for the time being. Our special thanks to Vitelity for their unwavering financial support over many years and to the many Nerd Vittles readers who continue to enjoy the benefits of their service offerings. We will keep everyone posted on further developments.
 

Some Recent Nerd Vittles Articles of Interest...

AsteriDex Security Alert. Because of a security vulnerability in our AsteriDex robodialer, you should download and install the following patch to protect your system if AsteriDex is accessible from the public Internet or if your private network is used by individuals other than your immediate (trustworthy) family. Log into your Asterisk® server as root and issue the following commands. We also recommend you change the name of the asteridex folder to something that only you know. For further security precautions, read the Hardening Your System section of the Best of Nerd Vittles article.

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


NOTE: This version of TeleYapper works with Asterisk 1.2 only. For Asterisk 1.4, read our new article on TeleYapper 4.0 or visit our Best of Nerd Vittles site.

WARNING: New federal regulations regarding robodialers go into effect on September 1, 2009. Before you use this software, make absolutely certain that you are in compliance with the new regulations regarding calls that deliver a prerecorded message! You can download the regulations here.

To start July off with a bang, we're back today with TeleYapper 3.0, an updated version of our Asterisk-based telephone broadcasting service. For those with multiple outbound trunks, TeleYapper 3.0 now supports simultaneous calls using multiple trunks. Special thanks to Matt Frederickson for the code. Version 3 works with all flavors of Asterisk@Home 2.x as well as most versions of TrixBox. We haven't tested it with Asterisk 1.4, but tips from others suggest that it'll work just fine with the DigitTimeout and ResponseTimeout tweaks that already are incorporated into TeleYapper 3.0. If you're running an earlier version of Asterisk@Home, use our version 1 code and tutorial. And, just like the original and version 2.5, TeleYapper 3.0 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 3.0 dialing away is in this article. And functionally, TeleYapper still works identically to prior versions. 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 TrixBox and 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) TrixBox PBX. Look at the top of this page (just below the Nerd Vittles header) for links to Windows, Mac, and Linux versions of TrixBox that are perfectly suited for use with TeleYapper. 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. If you're using one of our TrixBox builds which we just described, then this is less than a 5-minute upgrade. In either case, we've done all the hard work for you.

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 TeleYapper update provides a good framework for anyone wanting to write Asterisk AGI scripts using PHP. The code is well-documented to demonstrate how to pass variables to an AGI script from your dialplan and how to retrieve variables from an Asterisk AGI script into your dialplan. We needed this for TeleYapper because we're using a phone call to an Interactive Voice Response (IVR) session embedded in the dialplan to begin the calling process. We use the IVR session not only to determine which group of callees to call but also to give the caller the option of placing a call to everyone in the group or just those to whom the initial call was unsuccessful. After the caller hangs up, the results are passed to the teleyapper.php application to do the heavy lifting. The PHP program takes advantage of an AGI script's ability to actually set dialplan code in motion once a call is answered. In order to log calls and track which ones are successful, we have to pass variables into that dialplan code and then execute another PHP script when the call is completed. Stated another way, every call requires two round-trips from the Asterisk dialplan to PHP/AGI scripts. So, if you can't figure out how to pass variables back and forth using this application, you probably should consider another line of work. For those that just want to use the TeleYapper application and not learn much of anything about programming, you're welcome to do that subject to the license agreement which follows. We hope you'll put it to good use for the betterment of a school, an intramural sports program, or a neighborhood in which you happen to 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. 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 and TrixBox 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 our previous TeleYapper 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:

Upgrading from TeleYapper 2.5. If you're using one of our preconfigured TrixBox 1.2.3 systems from the links at the top of this page or if you have an existing TeleYapper 2.5 system which is working, then the upgrade to TeleYapper 3.0 is a piece of cake. You only need to download and replace the teleyapper.php AGI script located in /var/lib/asterisk/agi-bin on your TrixBox system. Just log into your Asterisk server as root and execute the commands below to install the new code. Then adjust the default settings as described below to meet your needs. That's it. You're done!

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


Creating the TeleYapper Database. We use the 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 phpMyAdmin. On Asterisk@Home systems, use a web browser pointed to your Asterisk server and choose: AMP->Maintenance->phpMyAdmin. On TrixBox systems, choose System Administration and then phpMyAdmin from the maintenancemenu. 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. A simple addition to your dialplan is used to force Asterisk to answer calls to M-S-G (extension 674) and pass them to the TeleYapper contexts for processing. Log into your Asterisk system as root and move to the /etc/asterisk directory. 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. For TrixBox users, cut-and-paste the following code into the [from-internal-trixbox] context near the top of extensions_trixbox.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. 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 or extensions_trixbox.conf if you're using TrixBox:

[yapper]
exten => s,1,Set(TIMEOUT(digit)=7)
exten => s,2,Set(TIMEOUT(response)=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 or extensions_trixbox.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,Set(TIMEOUT(digit)=4)
exten => s,3,Set(TIMEOUT(response)=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 or extensions_trixbox.conf, save your changes to disk. There's no need to reload Asterisk just yet. We've still got our AGI scripts to install.

If you're using freePBX, then make the following addition to your freePBX configuration. Log into your TrixBox server with a web browser. Choose freePBX and then choose Setup, Misc Destination. Add a new entry for TeleYapper with 674 as the Dial entry. Save your change and click the Red Bar to update the freePBX configuration.

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 although we haven't tried it with Asterisk 1.4. 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 usually will get recorded. Just be aware that there may be further adjustments down the road. In the meantime, you can check back and read the latest comments to this blog entry.

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" ;


NOTE: If you're using TeleYapper with Asterisk 1.4.x, comment out lines 168-172 in checkgroup.php to get the script to function properly. Special thanks to Lee Azzarello for the tip.

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/trixbox123/teleyapper30.zip
mv teleyapper.php teleyapper25.php
unzip teleyapper30.zip
rm teleyapper30.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.

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

The first line lets you set the number of simultaneous calls which can be placed. Be sure you have sufficient outbound trunks to support the number you insert and be sure to use the "local" setting for $trunk. The callspread variable determines the spacing of calls (or groups of calls if you have multiple outbound trunks) to your various callees. The default has been changed from one minute to minutes based upon extensive testing with large numbers of calls. This means the call to the second callee (or group of callees if you have specified $maxlines > 1) begins two minutes after the first call starts. Because a broadcast message is usually more than about 20 seconds long, we have found the 2 minute setting to be better since it allows sufficient time to complete the first call before the next one begins. Otherwise, calls will start failing if you only have a single outbound trunk. If you're going to be placing hundreds of calls, be sure to read our previous article which covers a real-world example using a 700-call database.

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 -rvvvvv from the command prompt on your system after you've logged in as root. 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.

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.

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 the automated phone call from TeleYapper at the neighborhood headquarters. But, who cares, right? It's only your house. Class dismissed.

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® to version 3. The original system let you schedule reminders for future events and, when the appointed date and time arrived, Asterisk swung into action and placed a call to the number you designated to deliver your customized reminder message. Today we add the bells and whistles that just about everyone using the original application requested. Now you can set up recurring reminders that call daily or on weekdays as well as weekly, monthly, and annually. This means it can be used to wake you up in the morning, or to remind Granny to take her medicine every day, or to remind your Little League team of practice times and locations, or to remind you and your customers of scheduled and recurring events.

The smarts for the original system already have been incorporated into our 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 phone reminder 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 messages 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, in our next article, we'll show you how to use a single entry from the new Asterisk Telephone Reminder System to contact a small or large group of people on a recurring basis.

Prerequisites. We've tested version 3 of our appointment reminder system with ISO-installed versions of Asterisk@Home 2.5 and TrixBox 1.2.3 in addition to the Nerd Vittles VMware builds of TrixBox 1.2.3. If you wish to use it with later versions of TrixBox or with a "pure Asterisk" system (not 1.4!), then you shouldn't have any problems. It won't work with version 1.x of Asterisk@Home or 1.4 releases of Asterisk. Post a comment if you have problems. You also will need a system which includes PHP to run this application. We've tested it with PHP 4.3.9, but PHP 5 systems probably will function without many changes in the underlying code. You should be able to install this project and get everything working in under 30 minutes. For those using our VMware TrixBox builds or our Linux PBX-in-a-Flash script for TrixBox 1.2.3 which can be downloaded at the top of this page, we'll walk you through the 5-minute upgrade drill so that you can take advantage of the new Version 3 recurring reminders feature set. If you're installing Telephone Reminders for the first time, complete installation instructions are available on our Best of Nerd Vittles site.

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. Finally, you're prompted whether to schedule a single reminder or recurring reminders (weekdays, daily, weekly, monthly, or annually). 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, end of the month recurring reminders pose a special problem. Why? Because not all months end on the same numbered day. January has 31, February has 28, April has 30. You get the idea. So the default behavior is as follows, If you schedule monthly reminders on the last day of any month, then we assume you want the reminders delivered on the last day of every month. You can alter this behavior by setting a flag in the reminder.php script if you want monthly reminders to always be delivered on the 28th day of the month, for example.

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, non-recurring reminders will be deleted from the system. But the reminder message is preserved as well as the recurring reminder for the next date on which to place the call. 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 for a specific date while logged in as root on your Asterisk system with a command like this:

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

Be sure you don't delete today's reminder messages or messages with a future date, or your entire reminder system will be toast!

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.

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. In today's article, we're going to walk you through upgrading a system on which you already have installed an earlier version of our Telephone Reminders system. As mentioned, if you're installing the software for the first time, stop here and use our Best of Nerd Vittles tutorial. To get the Reminder System upgraded, we're first going to move all of the code into the proper places. This includes the modifications to the dialplan contexts, installation of a new Allison voice prompts, and installation of the upgraded 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 replace some code that's already in your dialplan. The original contexts in extensions_custom.conf looked like this. Find ALL of this code (toward the bottom of the extensions_custom.conf file or, for TrixBox systems, extensions_trixbox.conf in the /etc/asterisk directory on your system) and delete it. The contexts to delete are the following: reminder, reminder2, reminder3, reminder4, reminder5, reminder6, reminder7, reminder8, reminder9, remindem, and remindem2. Replace the deleted contexts with this version 3.0 code.

For Step #2, make sure the following code snippet is still located in the top section of extensions_custom.conf in the [from-internal-custom] context or, for TrixBox systems, extensions_trixbox.conf in the [from-internal-trixbox] 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 your new config file and reload Asterisk.

Installing Reminder Voice Prompts. These voice prompts are free for the taking subject to the terms of the license agreement, and they're all the same as version 2.5 except there is a new reminder6.gsm. Just log into your Asterisk server as root and enter the following command to install the new voice prompt:

cd /var/lib/asterisk/sounds/custom
wget http://nerdvittles.com/aah2/reminder6.gsm
chmod 664 reminder*.gsm
chown asterisk:asterisk reminder*.gsm


If you need all of the voice prompts, then use these commands instead:

cd /var/lib/asterisk/sounds/custom
wget http://nerdvittles.com/aah2/nv-reminder3_voice.zip
unzip nv-reminder3_voice.zip (be sure to overwrite existing files!)
chmod 664 reminder*.gsm
chown asterisk:asterisk reminder*.gsm
rm -f nv-reminder3_voice.zip


Installing the Reminder PHP/AGI Scripts. Now we're getting to the new code for version 3. 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
mv reminder.php reminder25.php
mv run_reminders run_reminders.25
mv checkdate.php checkdate25.php
mv checktime.php checktime25.php
wget http://nerdvittles.com/aah2/nv-reminder3.zip
unzip nv-reminder3.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
chmod 777 run_recurring
chown asterisk:asterisk run_recurring


Creating Reminders Directories. While you're still logged in as root, create the following directories to store your reminders until the day arrives to execute them. Just issue the following commands. You should already have the reminders directory, but it won't hurt execute the command again just to be sure.

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


Setting Up the Crontab Entries. Now we need to set up the cron jobs to actually move reminders and recurring reminders into the Asterisk call processing directory on the day they are scheduled to run. Be very careful here. If you already have a working Telephone Reminders system, then there will already be an entry for run_reminders. For the new system to work, you MUST adjust the time that the run_reminders script executes so that it occurs AFTER the run_recurring script each day. 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 insert the following commands at the bottom of the crontab file and delete the existing run_reminders entry if you have one. Each command below should go on its own line.

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

Once you've added the two news lines and deleted the existing run_reminders 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:

$endofmonthflag=1 ;
$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, 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 or TrixBox systems 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. Beginning in version 2.5, 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.

Entering Recurring Reminders. Beginning with version 3, you now will be prompted whether to schedule (1) a single reminder, (2) a recurring reminder every weekday (M-F), (3),a recurring reminder every day, (4) a recurring reminder every week, (5) a recurring reminder every month, or (6) a recurring reminder every year. Once you make a selection, your reminder will be scheduled. If you choose an option other than 1 through 6, a single reminder will be scheduled.

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. For recurring reminders, duplicates of the .call script and the .gsm message are stored in /var/spool/asterisk/recurring with the date of the next recurring reminder. At midnight on the next scheduled date, the two files are copied to the /var/spool/asterisk/reminders and /var/lib/asterisk/sounds/custom folders respectively. Then the next scheduled reminder date is set in the two filenames. For single reminders, prior to the delivery date of the reminder message, the .call file is stored in /var/spool/asterisk/reminders. Then, at 12:03 am 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 recorded 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. To delete a recurring reminder, delete both the .call and .gsm files from /var/spool/asterisk/recurring. Note that the .call file will have an additional extension which tells the recurring type, e.g. .daily, .weekly, etc.

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 -rvvvvv. 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. By default, there's also a reminder log file produced for the last reminder call placed. You can display this file with the following command: cat /var/log/asterisk/reminder.txt.

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,"-"));


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. Recurring reminders are NOT yet included excepted those scheduled for delivery today. You can access the web page 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!

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.

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.

Email Delivery of Reminders. Assuming you have email messaging working on your Asterisk system, Telephone Reminders 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.

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.

MIME-Construct: Wherefore Art Thou? A Linux utility, MIME-Construct, made it easy to convert images (like faxes) to PDF documents and also facilitated the emailing of just about any other document including reminder messages. Unfortunately, it came up missing in TrixBox, and it's difficult to install because of all the Linux dependencies. So here's a simple solution that restores the original functionality of MIME-construct thanks to the programming genius of Rob Thomas. Since Rob's fax-process.pl code (included in freePBX) mimics the old MIME-construct application, the simple solution was just to tweak it a bit for Nerd Vittles and TrixBox compatibility and then copy a renamed version into the PATH (remember the DOS PATH!) on your Linux box. Log in as root and issue these commands, and you'll be back in the mime-construct business with TrixBox:

cd /usr/local/bin
wget http://nerdvittles.com/trixbox123/mime-construct
chmod +x mime-construct


Nerd Vittles Demo Hot Line (courtesy of les.net). You now can take a number of Nerd Vittles projects for a test drive... by phone! The current demos include (1) MailCall for Asterisk with password 1111 (retrieve your email by phone), (2) NewsClips for Asterisk (latest news headlines in dozens of categories), (3) Weather Forecasts by U.S. Airport Code, and (4) Weather Forecasts by U.S. ZIP Code. You're not prompted for #4 yet, but it does work! Just call our number (shown in the left margin) and take any or all of them for a spin. The sound quality may not be perfect due to performance limitations of our ancient Intel 386 demo machine. But the price is right.

Nerd Vittles Fan Club Map. Thanks for visiting! We hope you'll take a second and add yourself to our Frappr World Map compliments of Google. In making your entry, you can choose an icon: guy, gal, nerd, or geek. For those that don't know the difference in the last two, here's the best definition we've found: "a nerd is very similar to a geek, but with more RAM and a faster modem." We're always looking for the best BBQ joints on the planet. So, if you know of one, add it to the map while you're visiting as well.

Some Recent Nerd Vittles Articles of Interest...