TeleYapper 4.0 for Asterisk 1.4

Message Broadcasting System aka Phone Blasting Software

Nerd Vittles' TeleYapper is an automated message broadcasting service commonly known as a call blasting or phone blasting system. This version of TeleYapper is licensed for non-commercial use including the following: 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. Using phpMyAdmin and MySQL, a simple database of numbers to call is created. Callees can be separated into groups. Using a phone on your PBX in a Flash system, a TeleYapper session is initiated by dialing M-S-G (674). A personalized message can be recorded for delivery to each recipient or customized text-to-speech messages can be delivered using Flite or Cepstral. A delivery group is selected, and the automated calls are generated. Installation is a one-minute operation using a Nerd Vittles script which is downloaded onto your PBX in a Flash system.

Prerequisites

TeleYapper 4.0 for Asterisk 1.4 needs a LAMP-based platform (Linux, Apache, MySQL, and PHP) to work. We recommend PBX in a Flash, but other systems such as trixbox 2.x should suffice as well. To use the text-to-speech capabilities in version 4, you also will need a functioning text-to-speech engine. Both Flite and Cepstral are supported. Instead of a dedicated Asterisk server, you also can use the VMware version of PBX in a Flash if you just want to experiment a bit. It runs in a window on your Windows Vista/XP/2000 or Mac desktop.

How It Works

TeleYapper is simple to use. Dial extension M-S-G (674) on your Asterisk system and enter your password. You'll be prompted to record a message. Next you enter the group number for delivery of your TeleYapper message. The system will tell you how many recipients are in the group you have chosen. You then can begin the phone blasting session, or you can choose to resend messages to failed calls on a previous try to the same group. TeleYapper keeps track of which calls were successfully delivered and which were not so that follow-up calls can be placed.

Version 4 adds support for simultaneous outbound calls through a simple configuration setting. And customized text-to-speech messages can be stored with the phone number for each call recipient. In this case, the customized text-to-speech message is delivered instead of the recorded message. If you also have installed Telephone Reminders for Asterisk 1.4, there's also a convenient web page that lets you review previously scheduled TeleYapper calls on your system.

Installing TeleYapper 4.0 for Asterisk 1.4

[zip] TeleYapper 4.0 for Asterisk 1.4 Install Script (1KB)

Installation takes about 15 seconds. Log into your PBX in a Flash server as root and execute the following commands:

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

Assuming you have Cepstral functioning on a trixbox ce system, the install script should work reliably although we have not tested it. If you're not using PBX in a Flash or trixbox, review the TeleYapper 3.0 tutorial for more installation specifics.

Dialplan Setup

Most of the heavy-lifting for the TeleYapper system is handled by scripts in the Asterisk dialplan. With PBX in a Flash systems, these additions are made to the extensions_custom.conf file in /etc/asterisk. The only modification of the installed code that we recommend is changing the password for the telephony interface. Using nano, edit /etc/asterisk/extensions_custom.conf and search for 674. Or, from within FreePBX, click on the Tools tab, click Config Edit, and then click extensions_custom.conf. Replace the password 1234 in line 4 of the 674 dialplan code with numbers that are known only by you and those you trust and save your changes.

exten => 674,1,Answer
exten => 674,2,Wait(1)
exten => 674,3,Playback(custom/nv-yapwelcome)
exten => 674,4,Authenticate(1234)
exten => 674,5,Goto(yapper,s,1)

Missing Directory Setup

On some other distributions (not PBX in a Flash), the sounds directory in which the weather reports are stored has disappeared. The symptom for this would be a weather report that introduces the report but never plays it. Here's how to recreate the directory:

cd /var/lib/asterisk/sounds
mkdir tts
chmod 775 tts
chown asterisk:asterisk tts

FreePBX Setup

While still connected to your PBX in a Flash server with FreePBX in your browser, click on the Setup tab and then Misc Destinations. Add a new entry for TeleYapper with 674 as the Dial entry.

 Add Misc Destination
description:
dial:   

Save your entry and reload your Asterisk dialplan when prompted to do so. We recommend that you also install the Telephone Reminders for Asterisk 1.4 application so that you can monitor calls that have been scheduled.

Configuring the Telephony Interface

The telephony AGI interface to TeleYapper can be customized to meet your specific needs. Unless you plan to dial multiple calls simultaneously, the only setup required is to insert your correct CallerID information. To configure the telephony interface, edit the teleyapper.php script while logged in as root:

nano -w /var/lib/asterisk/agi-bin/teleyapper.php

You'll notice a section of variables at the top of the file that looks like this:

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

This is the only section of code you ought to change. 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:

  • $maxlines=1 ... Specifies the number of outbound trunks available on your system for simultaneous oubound calls.
  • $maxretries=1 ... Sets the number of times TeleYapper will attempt to place a failed call.
  • $retrytime=60 ... How many seconds delay should there be between failed call attempts to deliver a message?
  • $waittime=60 ... How many seconds delay should there be between failed call attempts to deliver a message?
  • $callspread=2 ... How many minutes delay should there be between calls in the calling list?
  • $debug = 1 ... If set to 1, then a debug log is created in /var/log/asterisk/teleyapper.txt.
  • $newlogeachdebug = 1 ... If set to 1, then a new debug log is created each time a TeleYapper session is initiated. Otherwise, file grows and grows.
  • $emaildebuglog = 0 ... If set to 1, the debug log is emailed to the email address set below when each TeleYapper session is scheduled.
  • $email = "yourname@yourdomain" ... Enter your actual email address between the quotation marks. Only works if line above is set to 1.
  • $trunk = "local" ... If set to "local", calls are routed using your default dialplan rules. Otherwise, specify a trunk to use, e.g. "sip/telasip-gw".
  • $callerid = chr(34) . "TeleYapper" . chr(34) . " <6781234567>" ... Specify your caller ID name and number. Name is NOT delivered by most Baby Bells and cellphone companies.

Adding Entries to the TeleYapper Database

TeleYapper uses 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. This customized message 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 this Cepstral article if you'd prefer to use Cepstral with Allison's voice for this and other Nerd Vittles text-to-speech applications.

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 lets you subdivided your recipients into 10 categories. 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.

Scheduling a TeleYapper Session By Phone

We are ready to take TeleYapper for a trial run. Make sure you have reloaded your Asterisk system (amportal restart), and then dial M-S-G (674) from an extension on your system. Enter the password you set up for TeleYapper and then press the pound key.

Recording a TeleYapper Message. You'll first be prompted to record a TeleYapper message. This is the message that will be played when someone answers the TeleYapper call. Press 2 to begin your recording and # to end it. Press 1 to play it back. Then press 3 to initiate a TeleYapper dialing spree.

Choosing a Delivery Group. TeleYapper supports 10 delivery groups: 0 through 9. Choose one of the delivery groups, and TeleYapper will tell you how many qualifying recipients exist in your database for this group.

Choosing a TeleYapper Delivery Option. Once you know how many calls will be placed, you can initiate a calling session by pressing 1. You can redial failed calls to this group from a previous calling session by pressing 2. Or you can cancel the TeleYapper session by pressing 3. If you press 1 or 2, the calls begin shortly after you hang up.

TeleYapper License

This version of TeleYapper is licensed for non-commercial use only 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!

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 at this link.

Additional Terms of Use

You are not buying this software. It's FREE! Don't assume today's version is error-free. It's probably not. But we try pretty hard to write reliable code. 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 warnings 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 our software.

Nerd Vittles Original Article (3/18/2008): Introducing Teleyapper 4.0 for Asterisk 1.4

Nerd Vittles Latest Update (10/10/10): Introducing Teleyapper 5.0 for Asterisk 1.4 and 1.6.2