Introducing TeleYapper 3.0: The Free Asterisk Message Broadcasting System

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.

Creative Commons LicenseLicensing. 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:

  • 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 advanced options (which redials previously unsuccessful calls in 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 and then your prerecorded message plays.
  • Callee is then prompted to press 1 to replay the message, press 2 to blacklist the last caller (you!), or press 3 to hang up.
  • If callee presses 1, 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 2, log will reflect that caller requested blacklisting. MySQL will actually DELETE this person from your database. It's the LAW!
  • If callee presses 3, Allison says goodbye and Asterisk hangs up the call. MySQL database will show date/time of call with status of OK.
  • 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 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:

  • TeleYapper MySQL database
  • Code Snippet to Answer M-S-G Calls
  • AutoAttendant Contexts
  • checkgroup.php AGI script
  • Call Processing Contexts
  • teleyapper.php AGI script
  • teleyapper2.php AGI script
  • 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

    [yapper2]
    exten => s,1,Playback(after-the-tone)
    exten => s,2,Playback(say-temp-msg-prs-pound)
    exten => s,3,Wait(2)
    exten => s,4,Record(custom/broadcast:gsm)
    exten => s,5,Wait(2)
    exten => s,6,Playback(custom/broadcast)
    exten => s,7,Wait(2)
    exten => s,8,Playback(your-msg-has-been-saved)
    exten => s,9,Wait(2)
    exten => s,10,Goto(yapper,s,1)

    [yapper3]
    exten => s,1,AGI(checkgroup.php|${GROUP})
    exten => s,2,NoOp(tmp variable: ${tmp})
    exten => s,3,GotoIf($[${tmp} = 0]?9,1)
    exten => s,4,Set(COUNTER=${tmp}|g)
    exten => s,5,Playback(the-num-i-have-is)
    exten => s,6,SayNumber(${COUNTER})
    exten => s,7,Playback(vm-messages)
    exten => s,8,Wait(1)
    exten => s,9,Set(TIMEOUT(digit)=7)
    exten => s,10,Set(TIMEOUT(response)=10)
    exten => s,11,Background(to-call-this-number)
    exten => s,12,Background(press-1)
    exten => s,13,Background(to-hang-up)
    exten => s,14,Background(press-2)
    exten => s,15,Background(vm-advopts)
    exten => 1,1,Goto(yapper-gen,s,1)
    exten => 2,1,Playback(goodbye)
    exten => 2,2,Hangup
    exten => 3,1,Goto(yapper-redial,s,1)
    exten => 9,1,Playback(dir-nomatch)
    exten => 9,2,Wait(1)
    exten => 9,3,Goto(yapper,s,1)
    exten => t,1,Playback(goodbye)
    exten => t,2,Hangup
    exten => i,1,Playback(goodbye)
    exten => i,2,Hangup
    exten => h,1,Hangup

    [yapper-options]
    exten => s,1,Wait(1)
    exten => s,2,Playback(you-have-these-options)
    exten => s,3,Playback(digits/0)
    exten => s,4,Playback(through)
    exten => s,5,Playback(digits/9)
    exten => s,6,Playback(press-star-cancel)
    exten => s,7,Read(tmp,vm-enter-num-to-call,1)
    exten => s,8,Set(GROUP=${tmp}|g)
    exten => s,9,NoOp(${GROUP})
    exten => s,10,GotoIf($["foo${GROUP}" = "foo"]?s,78)
    exten => s,11,GotoIf($["foo${GROUP}" = "foo*"]?s,88)
    exten => s,12,GotoIf($["foo${GROUP}" = "foo#"]?s,98)
    exten => s,13,Goto(yapper3,s,1)
    exten => s,78,Playback(connection-timed-out)
    exten => s,79,Wait(1)
    exten => s,80,Goto(yapper,s,1)
    exten => s,88,Playback(cancelled)
    exten => s,89,Wait(1)
    exten => s,90,Goto(yapper,s,1)
    exten => s,98,Playback(option-not-implemented)
    exten => s,99,Goto(yapper,s,1)

    [yapper-gen]
    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}|1)
    exten => h,2,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...

    Be Sociable, Share!

    14 Responses to “Introducing TeleYapper 3.0: The Free Asterisk Message Broadcasting System”

    1. JP says:

      Thanks for this Ward, will prove veeeeeeery handy with our local hockey association!

    2. ppuskari says:

      I can’t believe I finally get the chance to contribute!!!!! Please change this one line of code in teleyapper.php in order to get multiple lines to work correctly. Without it, you’ll autostrip your duplicates, and it will also make it impossible to test multilines with the same destination number.

      $thisfile = $calltime . “.yap.” . $phonenum . “.call” ;

      to

      $thisfile = $calltime . $loopcounter . “.yap.” . $phonenum . “.call” ;

      If your outbound call list has no duplicates then the original will work fine. But I was trying to call my voicemail to prove all 32 IAX2 channels fired with 35 callees and got only 2 call files. Since the phone number is the differentiation with time, that just overwrote the call files… This fixes that and all is happy.

      This is great stuff!

      [WM: Thanks for finding it. We didn’t have multiple lines to try. The zip file has been updated. I assume you didn’t need a period after the $calltime since the other code just looks for the first four characters for a time match. Just download the new file and try it for me if you would. If the missing period causes a problem, let me know. Thanks again.]

    3. Rob says:

      Ward
      THANK YOU!!! you are save our Pack more than $200 a year with this!
      I did want to know if there was away to customize the voice prompts?

    4. mak says:

      Do you know if this supports any TTS engine?

      [WM: Not yet, but good idea. We’ll look into adding support for Flite down the road.]

    5. termy says:

      Is it possible to make a call, make a pause, and then leave the message?
      Like to leave a message directly on the cell phone?

    6. Rob says:

      Ok, this is cool. Took me about 15 minutes and I was bugging the heck out of my family with the silly calls I kept making.
      Now, as I ponder the uses for my business…
      I’m very new with AGI and PHP. Is there some one who can point me to some tutorials as I would like to create a GUI interface for this. Great work.

    7. Rey says:

      The teleyapper is great, now is there a way to schedule or stop outgoing messages? lets say at 3:00pm on Monday when I’m at work with my buddies. or stop at 3:30 even if the list of friends was not called completely. Great work guys .

    8. termy says:

      I’ve been working on this for 3 weeks. I dont know why, teleyapper dont respect the time. I put 1 Line. call spead =3. And its still makes all the calls at one time. It doesnt wait for the 3 minutes. Even do, teleyapper.txt write the time delay, it shoots all the calls at onces!! Anyone had that kind of problem? I’ve been trying v.30 v.25 still the same thing.

      [WM: Be sure there’s not a typo in the variable name, e.g. call spead =3]

    9. james says:

      I was just installing this for about the fourth time on my trixbox I keep erasing and reinstalling everything. When I try to copy/paste the download/unzip/rm lines, I get the prompt to rm. Would it be easier for everyone, especially the newbies to use:
      rm -f teleyapper2.zip
      instead of
      rm teleyapper2.zip
      ??
      Thanks for a great app.

      [WM: Using -f is great if you never make typos. When you do use it, you don’t get a second chance!]

    10. David says:

      I got Teleyapper 3.0 running on an Asterisk 1.4 on Ubuntu Server. It’s very nice.

      You note that on Asterisk 1.4 one should comment out lines 167-172. I did this and the checkgroup.php didn’t return the correct number of phone numbers in the group. I uncommented line 167 and then it returned the correct number of phone numbers in the group.

      Thanks!

    11. Octothorpe says:

      One thing that I would like to add to the wishlist is a way to simply call all or part of a group. For Example: I have groups 1-9 set to call different parts of the group and would like to be able use group 0 to call everyone in the entire database, or all groups. That way I can just call group or call everyone depending one what I need to send.

    12. Scott says:

      I have been able to write a html front end for the teleyapper program and it seems to work pretty nice. I have added a “groups” database to the system and have it joined to the “callees” database. You can add, edit and view both groups and users through the web interface. Please let me know if you would like the code. I am not a pure programmer so it is not as nice as as some but it gets the job done. It works with Asterisk 1.4.15, mysql 5.0.22 and php.

      [WM: We’d love to have a look. Thanks, Scott!]

    13. Paulo says:

      Hi Ward, is there a teleyapper version for PIAF?

      [WM: Coming very, very soon.]

    14. Bob Pierce says:

      Hey Ward – Has this script been tested with Trixbox 2.4.2 yet? I can authenticate but when it jumps to the yapper routine it dosen’t prompt it just hangs up.

      — Executing [674@from-internal:1] Answer(“SIP/205-09febc88″, “”) in new stack
      — Executing [674@from-internal:2] Wait(“SIP/205-09febc88″, “1”) in new stack
      — Executing [674@from-internal:3] Authenticate(“SIP/205-09febc88″, “1234”) in new stack
      — Playing ‘agent-pass’ (language ‘en’)
      — Playing ‘auth-thankyou’ (language ‘en’)
      — Executing [674@from-internal:4] Goto(“SIP/205-09febc88″, “yapper|s|1″) in new stack
      — Goto (yapper,s,1)
      == Spawn extension (yapper, s, 1) exited non-zero on ‘SIP/205-09febc88′
      — Executing [h@yapper:1] Hangup(“SIP/205-09febc88″, “”) in new stack
      == Spawn extension (yapper, h, 1) exited non-zero on ‘SIP/205-09febc88′
      — Saved useragent “Linksys/SPA3102-5.1.7(GW)” for peer 205

      [WM: Doesn’t work with any system running Asterisk 1.4 yet, but we’re working on it.]

    Ringbinder theme by Themocracy