• Options
• Home
• Applications
• Scripts
• Tutorials
• Providers
• About

Nerd Vittles' Telephone Reminder System lets you schedule reminders for future events by telephone. When the appointed date and time arrives, Asterisk swings into action and places a call to the number you designate to deliver a customized reminder message. Version 3 adds support for recurring reminders. So you can set up reminders that place calls daily or on weekdays as well as weekly, monthly, and annually. This means it can be used to wake you up in the morning, or to remind Granny to take her medicine every day, or to remind your Little League team of practice times and locations, or to remind you and your customers of scheduled and recurring events. If you're using Asterisk 1.4, we'd recommend Telephone Reminders 4.0 which also includes a web scheduling module.

Prerequisites

To get Telephone Reminders 3.0 for Asterisk working, we recommend either a TrixBox system or a version 2 Asterisk@Home system. Any other Asterisk 1.2.x system (not 1.4!) with a web server, PHP 4, and Perl on the same box should also work. Instead of a dedicated Asterisk server, you also can use our VMware version of TrixBox if you just want to experiment a bit. It runs in a window on your Windows Vista/XP/2000 desktop. There's also a version for Intel Macs.

How It Works

The Telephone Reminder System is simple to use. Dial extension 1-2-3 on your Asterisk system and enter your password. You'll be prompted to record a reminder message. Next you enter the phone number, date, and time for delivery of the reminder message. Finally, you're prompted whether to schedule a single reminder or recurring reminders (weekdays, daily, weekly, monthly, or annually). When the appointed date and time arrives, Asterisk will place the call to the number you specified using your default dialing rules and will play the customized reminder when the call is answered. If the call is not answered, the call will be repeated the number of times you specify with a user-adjustable delay between calls. You'll get an email with the call reminder setup if desired.

Asterisk Server Download

Telephone Reminders 3.0 for Asterisk (10KB)
Telephone Reminders 3.0 GSM Voice Prompts (67KB)

Dialplan Setup

Most of the heavy-lifting for the Telephone Reminder System is handled by scripts in the Asterisk dialplan. With Asterisk@Home systems, these additions are made to the extensions_custom.conf file. With TrixBox systems, the additions are made to the extensions_trixbox.conf file. These files are located in the /etc/asterisk directory. To begin, add the following code to the [from-internal-custom] context on Asterisk@Home systems or the [from-internal-trixbox] context on TrixBox systems. Replace the password 12345678 in line 3 with something that is secure.

exten => 123,1,Answer
exten => 123,2,Wait(1)
exten => 123,3,Authenticate(12345678)
exten => 123,4,Goto(reminder,s,1)

Now move to the bottom of the configuration file and cut-and-paste the following block of code into the config file. If you have used a previous version of our Telephone Reminder System, be sure to delete the existing code first. Save your changes.

freePBX Setup

While still connected to your TrixBox server with your browser, choose freePBX and then choose Setup, Misc Destination. Add a new entry for Telephone Reminders with 123 as the Dial entry.

Save your entry and then click the Red Bar to reload your Asterisk dialplan settings.

Crontab Setup

The Telephone Reminders System uses cron jobs to actually move reminders and recurring reminders into the Asterisk call processing directory on the day they are scheduled to run. Be very careful here. If you already have a working Telephone Reminders System, then there will already be an entry for run_reminders in the crontab file. For the version 3 system to work, you MUST adjust the time that the run_reminders script executes so that it occurs AFTER the run_recurring script each day. While logged in as root, edit the crontab file: nano -w /etc/crontab. Insert the following commands at the bottom of the crontab file and delete the existing run_reminders entry if you have one. Each command below should go on its own line.

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

Once you've added the two new lines and deleted the existing run_reminders line, save your changes: Ctrl-X, Y, then press Enter.

Voice Prompts Setup

Log into your Asterisk server as root and enter the following commands to install the Telephone Reminders 3.0 voice prompts:

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

PHP and Perl Scripts Setup

Log into your Asterisk system as root. Copy and set up the Telephone Reminders 3.0 scripts in the agi-bin directory on your TrixBox or Asterisk@Home system:

cd /var/lib/asterisk/agi-bin
mv reminder.php reminder25.php
mv run_reminders run_reminders.25
mv checkdate.php checkdate25.php
mv checktime.php checktime25.php
wget http://nerdvittles.com/aah2/nv-reminder3.zip
unzip nv-reminder3.zip
chmod 775 reminder.php
chown asterisk:asterisk reminder.php
chmod 775 check*.php
chown asterisk:asterisk check*.php
chmod 777 run_reminders
chown asterisk:asterisk run_reminders
chmod 777 run_recurring
chown asterisk:asterisk run_recurring
su asterisk
mkdir /var/spool/asterisk/reminders
mkdir /var/spool/asterisk/recurring
exit
amportal restart

To configure the reminder system, you'll need to edit the reminder.php script while logged in as root: nano -w /var/lib/asterisk/agi-bin/reminder.php. You'll notice a section of variables at the top of the file that looks like this:

 $endofmonthflag=1 ;
 $extensionmaxdigits=4 ;
 $debug = 1;
 $newlogeachdebug = 1;
 $emaildebuglog = 0;
 $email = "yourname@yourdomain" ;
 $trunk = "local" ;
 $callerid = "6781234567" ;
 $numcallattempts=6 ;
 $calldelaybetweenruns=300 ;
 $timetoring=40 ;
 $acctcode= "Reminder" ;

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

• $endofmonthflag=1 ... Forces monthly recurring reminders scheduled on the last day of a month to the last day of every succeeding month
• $extensionmaxdigits=4 ... Sets the maximum number of digits for treating outbound calls as calls to local extensions.
• $debug = 1 ... If set to 1, then a debug log is created in /var/log/asterisk/reminder.txt. Instructions for deleting reminders are in the log.
• $newlogeachdebug = 1 ... If set to 1, then a new debug log is created each time a reminder is scheduled. Otherwise, file grows and grows.
• $emaildebuglog = 0 ... If set to 1, the debug log is emailed to the email address set below when each reminder 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 = "6781234567" ... Specify your caller ID number. Only used if $trunk is not set to "local" above.
• $numcallattempts=6 ... If there is no answer on the Reminder call, how many times should Asterisk attempt to deliver the reminder?
• $calldelaybetweenruns=300 ... How many seconds delay should there be between failed call attempts to deliver a reminder?
• $timetoring=40 ... How many seconds should the call ring when attempting to deliver a reminder?
• $acctcode= "Reminder" ... What accouting code should be used for reminder calls?

Scheduling a Reminder

We are ready to take the Reminder System for a trial run. Make sure you have reloaded your Asterisk system (amportal restart), and then dial 123 from an extension on your system. Enter the password you set up for your reminder system and then press the pound key.

Entering a Reminder Message. You'll first be prompted to record a reminder message. This is the message that will be played when someone answers the reminder call. If you're not scheduling this reminder for yourself, then the message ought to explain who's calling and what the purpose of the call is. Once you've recorded your message, press the pound key to end the recording. You can replay or rerecord the reminder if desired while you're in this step of the reminder creation process.

Entering the Callback Number. When prompted for the reminder callback number, there are a couple of things to keep in mind. First, if you've specified "local" as the trunk to use for reminders in the reminder.php script, then the phone numbers can be entered in any format supported by your dialplan. Press the pound key after entering the appropriate number. The calls will be placed using the trunks specified in your dialplan rules. The one exception is extensions on your local Asterisk system since these can't be routed by Asterisk@Home or TrixBox systems using your outbound calls dialplan rules. The way we handle extensions is by examining the length of the phone number. At the top of reminder.php, you can specify the maximum number of digits for local extensions by setting $extensionmaxdigits. So long as the callback number is less than or equal to this number of digits, the system has the smarts to correctly route the call to a local extension.

If you have designated a particular trunk for placement of reminder calls, then you'll need to make certain that the format of the phone numbers entered for reminders on your system matches a dial string supported for this outbound trunk in your dialplan. For example, if this trunk requires that calls be entered with a 1 and then an area code and 7-digit number, then that is the only format that should be used for entering callback numbers in your reminder system. Again, the one exception is calls to local extensions. So long as the number of a local extension is entered with less than or equal the number of digits set for the $extensionmaxdigits variable in reminder.php, the call will be routed properly to the local extension regardless of the trunk setting.

Finally, here's a shortcut that can be used if the phone you're using to schedule the reminder is the same one on which you want to get the reminder callback. In this case, just press the pound key when prompted for the number to which to deliver the reminder message. This will set the callback number as the caller ID of the phone you used to schedule the call. If it's a local extension, then the caller ID will be set to the local extension number of the phone from which you placed the reminder scheduling call. Just be sure your $extensionmaxdigits is set correctly or calls to local extensions will fail.

Entering the Date of the Reminder. Once you accept the reminder message, you'll be prompted to enter the date on which this reminder will be delivered. Dates are entered using a four-digit year, then a two-digit month, and then a two-digit day using the time zone of the Asterisk system running the Telephone Reminders System. There is some error correction but not much. You obviously can't schedule reminders in the past! And you don't need to press the pound key after entering the eight digits. Beginning in version 2.5, you now can press the pound key (#) instead of entering an 8-digit date, and the system will set the reminder date to today. Once you've entered a date, the system will tell you what date you entered including the day of the week. If the entry is correct, just press 1 to move on.

Entering the Time of the Reminder. Now you'll be prompted to enter the delivery time for your reminder. Times are entered as a two-digit hour and two-digit minute using the time zone of the Asterisk system running the Telephone Reminders System. For times less than 1200, you will be prompted whether you meant AM or PM. For those that understand military time, you can avoid this step by entering times using the format: 1345 which means 1:45 p.m. You don't need to press the pound key after entering the four-digit time for delivery of your reminder. Keep in mind that you cannot schedule a reminder for delivery in the first five minutes after midnight. Other times "in the midnight hour" should be entered in the format: 0045 which means 12:45 a.m. Keep in mind that reminder times always must be at least 5 minutes in the future. Finally, you cannot schedule two reminders for the exact same date and time for delivery to the same phone number. Once you enter a delivery time, the system will play back both the date and time for the reminder as a precaution. Press 1 to accept your entries.

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

Telephone Reminders 101

There are actually two files that make up each reminder: the .call file which places the actual call and the .gsm file which is the reminder message itself. The file naming convention is HourMinute.Date.PhoneNumber with either a .call or .gsm extension. The sound files are all stored in /var/lib/asterisk/sounds/custom. For recurring reminders, duplicates of the .call script and the .gsm message are stored in /var/spool/asterisk/recurring with the date of the next recurring reminder. At midnight on the next scheduled date, the two files are copied to the /var/spool/asterisk/reminders and /var/lib/asterisk/sounds/custom folders respectively. Then the next scheduled reminder date is set in the two filenames. For single reminders, prior to the delivery date of the reminder message, the .call file is stored in /var/spool/asterisk/reminders. Then, at 12:03 am on the date the reminder is scheduled for delivery, the run_reminders script in /var/lib/asterisk/agi-bin moves the affected .call files to /var/spool/asterisk/outgoing. The .call files in the outgoing directory are reviewed every minute of the day by Asterisk. By examining the time stamp of the file, Asterisk looks for a match with the current hour and minute of the day. Once the time for the call arrives, Asterisk processes the .call script and places the call. All dialing retries are handled internally by Asterisk with no user or program control so it's important to set your default values correctly in the reminder.php script as explained above. Once the .call file is processed, Asterisk discards the file whether the call was successful or not. As noted above, the reminder message file is only discarded if the call is completed successfully. So, from time to time, you do need to review the contents of /var/lib/asterisk/sounds/custom and discard reminder messages, if any, with dates in the past. Note also that, if you begin scheduling a reminder and change your mind and hang up after recording a reminder message, that recorded message will still exist in /var/lib/asterisk/sounds/custom.

Finally, a word of caution about the reminder message files: be very careful in deleting these files. The message files and .call files are linked by filename only, and there is no error detection or correction if the message file gets discarded before the time for the reminder call arrives. What would happen in such a situation is the call would be placed, someone would answer, Allison would say "please hold for an important reminder," and then there would be a brief silence followed by Allison saying "to repeat this reminder, press 1; otherwise, press 2" which is not entirely helpful. To delete a recurring reminder, delete both the .call and .gsm files from /var/spool/asterisk/recurring. Note that the .call file will have an additional extension which tells the recurring type, e.g. .daily, .weekly, etc.

Web Interface to Telephone Reminders

We've built a very simple web page that will let you review which reminders are pending on your system. Recurring reminders are NOT yet included excepted those scheduled for delivery today. You can access the web page directly at http://192.168.0.111/reminders/ using the IP address of your Asterisk system. To install the Telephone Reminders web interface, log into your Asterisk system as root and then issue the following commands:

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

E-Mail Delivery of Telephone Reminders

Assuming you have email messaging working on your Asterisk system, Telephone Reminders has the ability to deliver an email copy of reminders to the recipient in addition to a phone call. Be advised that, if the phone call is never completed, the email copy of the reminder will not be delivered. The reason for this is because Asterisk never passes the call to the context which handles delivery of the email message until the call is connected. So ... no connection, no email. However, if the recipient has an answering machine or voice mail, that would trigger delivery of the email message.

Once you've installed the new contexts to support email messaging, step two is registering email addresses for extensions and phone numbers to which you want email reminders delivered. Log in to your Asterisk server as root, and start up the Command Line Interface (CLI): asterisk -r. For each extension and phone number for which you want to activate email reminders, enter a command at the CLI prompt that looks like this:

database put EMAIL 6781234567 joe@schmo.com

6781234567 is the phone number of the reminder recipient and joe@schmo.com is the recipient's email address. You can display all existing EMAIL addresses that have been entered into your Asterisk database with this command: database show EMAIL. If you need to modify an existing entry, simply delete it and reenter it. To delete an existing entry, use the following syntax:

database del EMAIL 6781234567

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

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

Programmer's Corner

If you're just getting into PHP and AGI programming with Asterisk, then take a careful look at reminder.php. In particular, take a look at the section of code that begins with parse agi headers into array. As best we can tell, our initial tutorial on Telephone Reminders was the first version of this subroutine written in PHP that actually worked. If you review the log file (/var/log/asterisk/reminder.txt), you will see a listing of all the AGI headers which are passed by Asterisk to PHP. But this is the first code we've seen that correctly reads the headers into variables where you can actually retrieve the content. We call it a feature. For example, the commented out line ($tmp = $agi['dnid']) shows the syntax to retrieve the DNID value from Asterisk. Just make a mental note that the parse AGI headers code in reminder.php actually works. Here's the complete list of AGI headers that can be saved to variables in your PHP code should the need ever arise:

read: agi_request: reminder.php
read: agi_channel: SIP/204-6a1a
read: agi_language: en
read: agi_type: SIP
read: agi_uniqueid: 1138010325.1367
read: agi_callerid: "Line2" <204>
read: agi_dnid: 123
read: agi_rdnis: unknown
read: agi_context: reminder9
read: agi_extension: h
read: agi_priority: 2
read: agi_enhanced: 0.0
read: agi_accountcode: 

You'll also want to take note of a little quirk in Asterisk (compared to some PBXs). To decipher the extension which actually placed a call, you must parse the agi_channel variable for the data between the slash and hyphen characters since the DNID (dialed number identifier) returns the extension being called (as opposed to the originating extension) when an internal call is placed. Here's one PHP approach to get the answer which in this case happens to be extension 204. Regex wizards could probably save a line of code, but who cares.

$CallingID = substr(stristr($agi['channel'],"/"),1);
$CallingID = substr($CallingID,0,strrpos($CallingID,"-"));