Asterisk: The Future of Telephony, 2nd Edition

Writing AGI Scripts in Perl

Asterisk comes with a sample AGI script called agi-test.agi. Let’s step through the file while we cover the core concepts of AGI programming. While this particular script is written in Perl, please remember that your own AGI programs may be written in almost any programming language. Just to prove it, we’re going to cover AGI programming in a couple of other languages later in the chapter.

Let’s get started! We’ll look at each section of the code in turn, and describe what it does:

#!/usr/bin/perl

This line tells the system that this particular script is written in Perl, so it should use the Perl interpreter to execute the script. If you’ve done much Linux or Unix scripting, this line should be familiar to you. This line assumes, of course, that your Perl binary is located in the /usr/bin/ directory. Change this to match the location of your Perl interpreter.

use strict;

use strict tells Perl to act, well, strict about possible programming errors, such as undeclared variables. While not absolutely necessary, enabling this will help you avoid common programming pitfalls.

$|=1;

This line tells Perl not to buffer its output—in other words, that it should write any data immediately, instead of waiting for a block of data before outputting it. You’ll see this as a recurring theme throughout the chapter.

# Set up some variables
my %AGI; my $tests = 0; my $fail = 0; my $pass = 0;

Warning

You should always use unbuffered output when writing AGI scripts. Otherwise, your AGI may not work as expected, because Asterisk may be waiting for the output of your program, while your program thinks it has sent the output to Asterisk and is waiting for a response.

Here, we set up four variables. The first is a hash called AGI, which is used to store the variables that Asterisk passes to our script at the beginning of the AGI session. The next three are scalar values, used to count the total number of tests, the number of failed tests, and the number of passed tests, respectively.

while(<STDIN>) {
        chomp;
        last unless length($_);
        if (/^agi_(\w+)\:\s+(.*)$/) {
                $AGI{$1} = $2;
        }
}

As we explained earlier, Asterisk sends a group of variables to the AGI program at startup. This loop simply takes all of these variables and stores them in the hash named AGI. They can be used later in the program or simply ignored, but they should always be read from STDIN before continuing on with the logic of the program.

print STDERR "AGI Environment Dump:\n";
foreach my $i (sort keys %AGI) {
        print STDERR " -- $i = $AGI{$i}\n";
}

This loop simply writes each of the values that we stored in the AGI hash to STDERR. This is useful for debugging the AGI script, as STDERR is printed to the Asterisk console.^[120]

sub checkresult {
        my ($res) = @_;
        my $retval;
        $tests++;
        chomp $res;
        if ($res =~ /^200/) {
                $res =~ /result=(-?\d+)/;
                if (!length($1)) {
                        print STDERR "FAIL ($res)\n";
                        $fail++;
                } else {
                        print STDERR "PASS ($1)\n";
                        $pass++;
                }
        } else {
                print STDERR "FAIL (unexpected result '$res')\n";
                $fail++;
        }

This subroutine reads in the result of an AGI command from Asterisk and decodes the result to determine whether the command passes or fails.

Now that the preliminaries are out of the way, we can get to the core logic of the AGI script:

print STDERR "1.  Testing 'sendfile'...";
print "STREAM FILE beep \"\"\n";
my $result = <STDIN>;
&checkresult($result);

This first test shows how to use the STREAM FILE command. The STREAM FILE command tells Asterisk to play a sound file to the caller, just as the Background() application does. In this case, we’re telling Asterisk to play a file called beep.gsm.^[121]

You will notice that the second argument is passed by putting in a set of double quotes, escaped by backslashes. Without the double quotes to indicate the second argument, this command does not work correctly.

Warning

You must pass all required arguments to the AGI commands. If you want to skip a required argument, you must send empty quotes (properly escaped in your particular programming language), as shown above. If you don’t pass the required number of arguments, your AGI script will not work.

You should also make sure you pass a line feed (the \n on the end of the print statement) at the end of the command.

After sending the STREAM FILE command, this test reads the result from STDIN and calls the checkresult subroutine to determine if Asterisk was able to play the file. The STREAM FILE command takes three arguments, two of which are required:

• The name of the sound file to play back

• The digits that may interrupt the playback

• The position at which to start playing the sound, specified in number of samples (optional)

In short, this test told Asterisk to play back the file named beep.gsm, and then it checked the result to make sure the command was successfully executed by Asterisk.

print STDERR "2.  Testing 'sendtext'...";
print "SEND TEXT \"hello world\"\n";
my $result = <STDIN>;
&checkresult($result);

This test shows us how to call the SEND TEXT command, which is similar to the SendText() application. This command will send the specified text to the caller, if the caller’s channel type supports the sending of text.

The SEND TEXT command takes one argument: the text to send to the channel. If the text contains spaces (as in the previous code block), the argument should be encapsulated with quotes, so that Asterisk will know that the entire text string is a single argument to the command. Again, notice that the quotation marks are escaped, as they must be sent to Asterisk, not used to terminate the string in Perl.

print STDERR "3.  Testing 'sendimage'...";
print "SEND IMAGE asterisk-image\n";
my $result = <STDIN>;
&checkresult($result);

This test calls the SEND IMAGE command, which is similar to the SendImage() application. Its single argument is the name of an image file to send to the caller. As with the SEND TEXT command, this command works only if the calling channel supports the receiving images.

print STDERR "4.  Testing 'saynumber'...";
print "SAY NUMBER 192837465 \"\"\n";
my $result = <STDIN>;
&checkresult($result);

This test sends Asterisk the SAY NUMBER command. This command behaves identically to the SayNumber() dialplan application. It takes two arguments:

• The number to say

• The digits that may interrupt the command

Again, since we’re not passing in any digits as the second argument, we need to pass in an empty set of quotes.

print STDERR "5.  Testing 'waitdtmf'...";
print "WAIT FOR DIGIT 1000\n";
my $result = <STDIN>;
&checkresult($result);

This test shows the WAIT FOR DIGIT command. This command waits the specified number of milliseconds for the caller to enter a DTMF digit. If you want the command to wait indefinitely for a digit, use -1 as the timeout. This application returns the decimal ASCII value of the digit that was pressed.

print STDERR "6.  Testing 'record'...";
print "RECORD FILE testagi gsm 1234 3000\n";
my $result = <STDIN>;
&checkresult($result);

This section of code shows us the RECORD FILE command. This command is used to record the call audio, similar to the Record() dialplan application. RECORD FILE takes seven arguments, the last three of which are optional:

• The filename of the recorded file.

• The format in which to record the audio.

• The digits that may interrupt the recording.

• The timeout (maximum recording time) in milliseconds, or -1 for no timeout.

• The number of samples to skip before starting the recording (optional).

• The word BEEP, if you’d like Asterisk to beep before the recording starts (optional).

• The number of seconds before Asterisk decides that the user is done with the recording and returns, even though the timeout hasn’t been reached and no DTMF digits have been entered (optional). This argument must be preceded by s=.

In this particular case, we’re recording a file called testagi (in the GSM format), with any of the DTMF digits 1 through 4 terminating the recording, and a maximum recording time of 3,000 milliseconds.

print STDERR "6a.  Testing 'record' playback...";
print "STREAM FILE testagi \"\"\n";
my $result = <STDIN>;
&checkresult($result);

The second part of this test plays back the audio that was recorded earlier, using the STREAM FILE command. We’ve already covered STREAM FILE, so this section of code needs no further explanation.

print STDERR "================== Complete ======================\n";
print STDERR "$tests tests completed, $pass passed, $fail failed\n";
print STDERR "==================================================\n";

At the end of the AGI script, a summary of the tests is printed to STDERR, which should end up on the Asterisk console.

In summary, you should remember the following when writing AGI programs in Perl:

• Turn on strict language checking with the use strict command.^[122]

• Turn off output buffering by setting $|=1.

• Data from Asterisk is received using a while(<STDIN>) loop.

• Write values with the print command.

• Use the print STDERR command to write debug information to the Asterisk console.

The Perl AGI Library

If you are interested in building your own AGI scripts in Perl, you may want to check out the Asterisk::AGI Perl module written by James Golovich, which is located at http://asterisk.gnuinter.net. The Asterisk::AGI module makes it even easier to write AGI scripts in Perl.

---

^[120] Actually, to the first spawned Asterisk console (i.e., the first instance of Asterisk called with the -c option). If safe_asterisk was used to start Asterisk, the first Asterisk console will be on TTY9, which means that you will not be able to view AGI errors remotely.

^[121] Asterisk automatically selects the best format, based on translation cost and availability, so the file extension is never used in the function.

^[122] This advice probably applies to any Perl program you might write, especially if you’re new to Perl.