Simple asterisk gateway interface class
use Asterisk::AGI;
$AGI = new Asterisk::AGI;
# pull \s-1AGI\s0 variables into %input
%input = $AGI->ReadParse();
# say the number 1984
$AGI->say_number(1984);
This module should make it easier to write scripts that interact with the asterisk open source pbx via \s-1AGI\s0 (asterisk gateway interface)
Set function to execute when call is hungup or function returns error. Example: $AGI->setcallback(\&examplecallback);
Executes \s-1AGI\s0 Command \*(L"\s-1ANSWER\s0\*(R" Answers channel if not already in answer state Example: $AGI->answer(); Returns: -1 on channel failure, or 0 if successful Executes \s-1AGI\s0 Command \*(L"\s-1CHANNEL\s0 \s-1STATUS\s0 $channel\*(R" Returns the status of the specified channel. If no channel name is given the returns the status of the current channel. Example: $AGI->channel_status(); Returns: -1 Channel hungup or error
0 Channel is down and available
1 Channel is down, but reserved
2 Channel is off hook
3 Digits (or equivalent) have been dialed
4 Line is ringing
5 Remote end is ringing
6 Line is up
7 Line is busy
Executes \s-1AGI\s0 Command \*(L"\s-1CONTROL\s0 \s-1STREAM\s0 \s-1FILE\s0 $filename $digits [$skipms [$ffchar [$rewchar [$pausechar]]]]\*(R" Send the given file, allowing playback to be controled by the given digits, if any. Use double quotes for the digits if you wish none to be permitted. Remember, the file extension must not be included in the filename. Note: ffchar and rewchar default to * and # respectively. Example: $AGI->control_stream_file('status', 'authorized'); Returns: -1 on error or hangup;
0 if playback completes without a digit being pressed;
the \s-1ASCII\s0 numerical value of the digit of one was pressed.
Executes \s-1AGI\s0 Command \*(L"\s-1DATABASE\s0 \s-1DEL\s0 $family $key\*(R" Removes database entry <family>/<key> Example: $AGI->database_del('test', 'status'); Returns: 1 on success, 0 otherwise Executes \s-1AGI\s0 Command \*(L"\s-1DATABASE\s0 \s-1DELTREE\s0 $family $key\*(R" Deletes a family or specific keytree within a family in the Asterisk database Example: $AGI->database_deltree('test', 'status'); Example: $AGI->database_deltree('test'); Returns: 1 on success, 0 otherwise Executes \s-1AGI\s0 Command \*(L"\s-1DATABASE\s0 \s-1GET\s0 $family $key\*(R" Example: $var = $AGI->database_get('test', 'status'); Returns: The value of the variable, or undef if variable does not exist Executes \s-1AGI\s0 Command \*(L"\s-1DATABASE\s0 \s-1PUT\s0 $family $key $value\*(R" Set/modifes database entry <family>/<key> to <value> Example: $AGI->database_put('test', 'status', 'authorized'); Returns: 1 on success, 0 otherwise Executes \s-1AGI\s0 Command \*(L"\s-1EXEC\s0 $app \*(R"$options"" The most powerful \s-1AGI\s0 command. Executes the given application passing the given options. Example: $AGI->exec('Dial', 'Zap/g2/8005551212'); Returns: -2 on failure to find application, or whatever the given application returns Executes \s-1AGI\s0 Command \*(L"\s-1GET\s0 \s-1DATA\s0 $filename $timeout $maxdigits\*(R" Streams $filename and returns when $maxdigits have been received or when $timeout has been reached. Timeout is specified in ms Example: $AGI->get_data('demo-welcome', 15000, 5); Executes \s-1AGI\s0 Command \*(L"\s-1GET\s0 \s-1FULL\s0 \s-1VARIABLE\s0 $variablename $channel\*(R" Similar to get_variable, but additionally understands complex variable names and builtin variables. If $channel is not set, uses the current channel. Example: $AGI->get_full_variable('status', '\s-1SIP/4382\s0'); Returns: The value of the variable, or undef if variable does not exist Executes \s-1AGI\s0 Command \*(L"\s-1GET\s0 \s-1OPTION\s0 $filename $digits $timeout\*(R" Behaves similar to \s-1STREAM\s0 \s-1FILE\s0 but used with a timeout option. Streams $filename and returns when $digits is pressed or when $timeout has been reached. Timeout is specified in ms. If $timeout is not specified, the command will only terminate on the $digits set. $filename can be an array of files or a single filename. Example: $AGI->get_option('demo-welcome', '#', 15000); $AGI->get_option(['demo-welcome', 'demo-echotest'], '#', 15000); Executes \s-1AGI\s0 Command \*(L"\s-1GET\s0 \s-1VARIABLE\s0 $variablename\*(R" Gets the channel variable <variablename> Example: $AGI->get_variable('status'); Returns: The value of the variable, or undef if variable does not exist Executes \s-1AGI\s0 Command \*(L"\s-1HANGUP\s0 $channel\*(R" Hangs up the passed $channel, or the current channel if $channel is not passed. It is left to the \s-1AGI\s0 script to exit properly, otherwise you could end up with zombies. Example: $AGI->hangup(); Returns: Always returns 1 Executes \s-1AGI\s0 Command \*(L"\s-1NOOP\s0\*(R" Does absolutely nothing except pop up a log message. Useful for outputting debugging information to the Asterisk console. Example: $AGI->noop(\*(L"Test Message\*(R"); Returns: -1 on hangup or error, 0 otherwise Executes \s-1AGI\s0 Command \*(L"\s-1RECEIVE\s0 \s-1CHAR\s0 $timeout\*(R" Receives a character of text on a channel. Specify timeout to be the maximum time to wait for input in milliseconds, or 0 for infinite. Most channels do not support the reception of text. Example: $AGI->receive_char(3000); Returns: Returns the decimal value of the character if one is received, or 0 if the channel does not support text reception. Returns -1 only on error/hangup. Executes \s-1AGI\s0 Command \*(L"\s-1RECEIVE\s0 \s-1TEXT\s0 $timeout\*(R" Receives a string of text on a channel. Specify timeout to be the maximum time to wait for input in milliseconds, or 0 for infinite. Most channels do not support the reception of text. Example: $AGI->receive_text(3000); Returns: Returns the string of text if received, or -1 for failure, error or hangup. Executes \s-1AGI\s0 Command \*(L"\s-1RECORD\s0 \s-1FILE\s0 $filename $format $digits $timeout [$offset [$beep [s=$silence]]]\*(R" Record to a file until $digits are received as dtmf. The $format will specify what kind of file will be recorded. The $timeout is the maximum record time in milliseconds, or -1 for no timeout. $offset samples is optional, and if provided will seek to the offset without exceeding the end of the file. $silence is the number of seconds of silence allowed before the function returns despite the lack of dtmf digits or reaching timeout. Example: $AGI->record_file('foo', 'wav', '#', '5000', '0', 1, '2'); Returns: 1 on success, -1 on hangup or error. Executes \s-1AGI\s0 Command \*(L"\s-1SAY\s0 \s-1ALPHA\s0 $string $digits\*(R" Say a given character string, returning early if any of the given \s-1DTMF\s0 $digits are received on the channel. Returns Example: $AGI->say_alpha('Joe Smith', '#'); Returns: 0 if playback completes without a digit being pressed;
the \s-1ASCII\s0 numerical value of the digit if one was pressed;
-1 on error/hangup.
Executes \s-1AGI\s0 Command \*(L"\s-1SAY\s0 \s-1DATE\s0 $number $digits\*(R" Executes \s-1AGI\s0 Command \*(L"\s-1SAY\s0 \s-1TIME\s0 $number $digits\*(R" Executes \s-1AGI\s0 Command \*(L"\s-1SAY\s0 \s-1DATETIME\s0 $number $digits $format $timezone\*(R" Say a given date or time, returning early if any of the optional \s-1DTMF\s0 $digits are received on the channel. $time is number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time (\s-1UTC\s0), commonly known as \*(L"unixtime.\*(R" For say_datetime, $format is the format the time should be said in; see voicemail.conf (defaults to \*(L"ABdY 'digits/at' IMp\*(R"). Acceptable values for $timezone can be found in /usr/share/zoneinfo. Defaults to machine default. Example: $AGI->say_date('100000000');
$AGI->say_time('100000000', '#');
$AGI->say_datetime('100000000', '#', 'ABdY IMp', '\s-1EDT\s0');
Returns: -1 on error or hangup;
0 if playback completes without a digit being pressed;
the \s-1ASCII\s0 numerical value of the digit of one was pressed.
Executes \s-1AGI\s0 Command \*(L"\s-1SAY\s0 \s-1DIGITS\s0 $number $digits\*(R" Says the given digit string $number, returning early if any of the $digits are received. Example: $AGI->say_digits('8675309'); Returns: -1 on error or hangup, 0 if playback completes without a digit being pressed, or the \s-1ASCII\s0 numerical value of the digit of one was pressed. Executes \s-1AGI\s0 Command \*(L"\s-1SAY\s0 \s-1NUMBER\s0 $number $digits [$gender]\*(R" Says the given $number, returning early if any of the $digits are received. Example: $AGI->say_number('98765'); Returns: -1 on error or hangup, 0 if playback completes without a digit being pressed, or the \s-1ASCII\s0 numerical value of the digit of one was pressed. Executes \s-1AGI\s0 Command \*(L"\s-1SAY\s0 \s-1PHONETIC\s0 $string $digits\*(R" Say a given character string with phonetics, returning early if any of the given \s-1DTMF\s0 digits are received on the channel. Example: $AGI->say_phonetic('Joe Smith', '#'); Returns: 0 if playback completes without a digit being pressed;
the \s-1ASCII\s0 numerical value of the digit if one was pressed;
-1 on error/hangup.
Executes \s-1AGI\s0 Command "\s-1SEND\s0 \s-1IMAGE\s0 $image Sends the given image on a channel. Most channels do not support the transmission of images. Example: $AGI->send_image('image.png'); Returns: -1 on error or hangup, 0 if the image was sent or if the channel does not support image transmission. Executes \s-1AGI\s0 Command \*(L"\s-1SEND\s0 \s-1TEXT\s0 \*(R"$text" Sends the given text on a channel. Most channels do not support the transmission of text. Example: $AGI->send_text('You've got mail!'); Returns: -1 on error or hangup, 0 if the text was sent or if the channel does not support text transmission. Executes \s-1AGI\s0 Command \*(L"\s-1SET\s0 \s-1AUTOHANGUP\s0 $time\*(R" Cause the channel to automatically hangup at <time> seconds in the future. Of course it can be hungup before then as well. Setting to 0 will cause the autohangup feature to be disabled on this channel. Example: $AGI->set_autohangup(60); Returns: Always returns 1 Executes \s-1AGI\s0 Command \*(L"\s-1SET\s0 \s-1CALLERID\s0 $number\*(R" Changes the callerid of the current channel to <number> Example: $AGI->set_callerid('9995551212'); Returns: Always returns 1 Executes \s-1AGI\s0 Command \*(L"\s-1SET\s0 \s-1CONTEXT\s0 $context\*(R" Changes the context for continuation upon exiting the agi application Example: $AGI->set_context('dialout'); Returns: Always returns 0 Executes \s-1AGI\s0 Command \*(L"\s-1SET\s0 \s-1EXTENSION\s0 $extension\*(R" Changes the extension for continuation upon exiting the agi application Example: $AGI->set_extension('7'); Returns: Always returns 0 Executes \s-1AGI\s0 Command \*(L"\s-1SET\s0 \s-1MUSIC\s0 $mode $class\*(R" Enables/Disables the music on hold generator. If $class is not specified, then the default music on hold class will be used. $mode must be \*(L"on\*(R" or \*(L"off\*(R". Example: $AGI->set_music(\*(L"on\*(R", \*(L"happy\*(R");
$AGI->set_music(\*(L"off\*(R");
Returns: -1 on hangup or error, 0 otherwise. Executes \s-1AGI\s0 Command \*(L"\s-1SET\s0 \s-1PRIORITY\s0 $priority\*(R" Changes the priority for continuation upon exiting the agi application Example: $AGI->set_priority\|(1); Returns: Always returns 0 Executes \s-1AGI\s0 Command \*(L"\s-1SET\s0 \s-1VARIABLE\s0 $variable $value\*(R" Sets the channel variable <variablename> to <value> Example: $AGI->set_variable('status', 'authorized'); Returns: Always returns 1 Executes \s-1AGI\s0 Command \*(L"\s-1STREAM\s0 \s-1FILE\s0 $filename $digits [$offset]\*(R" This command instructs Asterisk to play the given sound file and listen for the given dtmf digits. The fileextension must not be used in the filename because Asterisk will find the most appropriate file type. $filename can be an array of files or a single filename. Example: $AGI->stream_file('demo-echotest', '0123'); $AGI->stream_file(['demo-echotest', 'demo-welcome'], '0123'); Returns: -1 on error or hangup, 0 if playback completes without a digit being pressed, or the \s-1ASCII\s0 numerical value of the digit if a digit was pressed Executes \s-1AGI\s0 Command \*(L"\s-1TDD\s0 \s-1MODE\s0 <on|off>\*(R" Enable/Disable \s-1TDD\s0 transmission/reception on a channel. Example: $AGI->tdd_mode('on'); Returns: Returns 1 if successful, or 0 if channel is not TDD-capable. Executes \s-1AGI\s0 Command \*(L"\s-1VERBOSE\s0 $message $level\*(R" Logs $message with verboselevel $level Example: $AGI->verbose(\*(L"System Crashed\n\*(R", 1); Returns: Always returns 1 Executes \s-1AGI\s0 Command \*(L"\s-1WAIT\s0 \s-1FOR\s0 \s-1DIGIT\s0 $timeout\*(R" Waits up to 'timeout' milliseconds for channel to receive a \s-1DTMF\s0 digit. Use -1 for the timeout value if you desire the call to block indefinitely. Example: $AGI->wait_for_digit($timeout); Returns: Returns -1 on channel failure, 0 if no digit is received in the timeout, or the numerical value of the ascii of the digit if one is received.