Introducing TeleYapper: Free Asterisk Message Broadcasting System, Part II

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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


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

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

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

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


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

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

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


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

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

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

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

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

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


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

For Asterisk@Home 1.5 users:


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


For Asterisk@Home 2.2 users:


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


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

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

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

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

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

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

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

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

For Asterisk@Home 1.5 users:


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


For Asterisk@Home 2.2 users:


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


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

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

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

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

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

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

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

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

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

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