Asterisk::AGI(3pm)

📦

version 1.08 · 4 versions

1.08 · debian bookworm, ubuntu jammy (latest)
1.08 · ubuntu noble
1.08 · ubuntu resolute, ubuntu stonking
1.08 · debian trixie, ubuntu questing

, in debian bookworm, ubuntu jammy

Asterisk::AGI — User Contributed Perl Documentation — the 3pm manual page, bestie edition 💅

✨ NAME ✨

Asterisk::AGI — Simple Asterisk Gateway Interface Class 🦋

✨ SYNOPSIS ✨

okay so here's the whole vibe in one glance, no cap:

use Asterisk::AGI;

$AGI = new Asterisk::AGI;

# pull AGI variables into %input

        %input = $AGI->ReadParse();

# say the number 1984

        $AGI->say_number(1984);

like. that's it. that's the whole entry point. iconic. 🎀

✨ DESCRIPTION ✨

This module should make it easier to write scripts that interact with the asterisk open source pbx via AGI (asterisk gateway interface) 💖

translation bestie: Perl script → talks to Asterisk → Asterisk does phone stuff. the module is literally just here to make your life easier. periodt.

✨ MODULE COMMANDS ✨

$AGI->setcallback($funcref)

Set function to execute when call is hungup or function returns error. 🫶

lowkey important — this is your little safety net for when the call dies or something goes sideways.

Example: $AGI->setcallback(\&examplecallback);

✨ AGI COMMANDS ✨

this is the main character section. every one of these bad boys maps to a real AGI command. let's go 🏃‍♀️💨

$AGI->answer()

Executes AGI Command ANSWER

Answers channel if not already in answer state 🔥

Example: $AGI->answer();

Returns: -1 on channel failure, or 0 if successful

$AGI->channel_status([$channel])

Executes AGI Command CHANNEL STATUS $channel

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

a whole mood board of channel feelings fr fr 💀

$AGI->control_stream_file($filename, $digits [, $skipms [, $ffchar [, $rewchar [, $pausechar]]]])

Executes AGI Command CONTROL STREAM FILE $filename $digits [$skipms [$ffchar [$rewchar [$pausechar]]]]

Send the given file, allowing playback to be controlled 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 ASCII numerical value of the digit of one was pressed.

$AGI->database_del($family, $key)

Executes AGI Command DATABASE DEL $family $key

Removes database entry <family>/<key> 🗑️

Example: $AGI->database_del('test', 'status');

Returns: 1 on success, 0 otherwise

$AGI->database_deltree($family, $key)

Executes AGI Command DATABASE DELTREE $family $key

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

$AGI->database_get($family, $key)

Executes AGI Command DATABASE GET $family $key

Example: $var = $AGI->database_get('test', 'status');

Returns: The value of the variable, or undef if variable does not exist 😭

$AGI->database_put($family, $key, $value)

Executes AGI Command DATABASE PUT $family $key $value

Set/modifes database entry <family>/<key> to <value> ✍️

Example: $AGI->database_put('test', 'status', 'authorized');

Returns: 1 on success, 0 otherwise

$AGI->exec($app, $options)

Executes AGI Command EXEC $app "$options"

The most powerful AGI command. Executes the given application passing the given options. 👑

this is the big one bestie. it's giving "I can run literally any Asterisk application from here" energy.

Example: $AGI->exec('Dial', 'Zap/g2/8005551212');

Returns: -2 on failure to find application, or whatever the given application returns

$AGI->get_data($filename, $timeout, $maxdigits)

Executes AGI Command GET DATA $filename $timeout $maxdigits

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);

$AGI->get_full_variable($variable [, $channel])

Executes AGI Command GET FULL VARIABLE $variablename $channel

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', 'SIP/4382');

Returns: The value of the variable, or undef if variable does not exist

$AGI->get_option($filename, $digits [, $timeout])

Executes AGI Command GET OPTION $filename $digits $timeout

Behaves similar to STREAM FILE 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);

$AGI->get_variable($variable)

Executes AGI Command GET VARIABLE $variablename

Gets the channel variable <variablename> 🔍

Example: $AGI->get_variable('status');

Returns: The value of the variable, or undef if variable does not exist

$AGI->hangup($channel)

Executes AGI Command HANGUP $channel

Hangs up the passed $channel, or the current channel if $channel is not passed. It is left to the AGI script to exit properly, otherwise you could end up with zombies. 🧟🧟🧟

no cap, the zombie warning is real. your script still has to exit on its own. don't be the reason for wandering undead processes bestie 😭

Example: $AGI->hangup();

Returns: Always returns 1

$AGI->noop()

Executes AGI Command NOOP

Does absolutely nothing except pop up a log message. Useful for outputting debugging information to the Asterisk console. 💬

Example: $AGI->noop("Test Message");

Returns: -1 on hangup or error, 0 otherwise

not me using this for absolutely every debug print 💅 it's literally a vibes-only command and I'm obsessed.

$AGI->receive_char($timeout)

Executes AGI Command RECEIVE CHAR $timeout

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.

$AGI->receive_text($timeout)

Executes AGI Command RECEIVE TEXT $timeout

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.

$AGI->record_file($filename, $format, $digits, $timeout, $beep, $offset, $beep, $silence)

Executes AGI Command RECORD FILE $filename $format $digits $timeout [$offset [$beep [s=$silence]]]

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.

$AGI->say_alpha($string, $digits)

Executes AGI Command SAY ALPHA "$string" $digits

Say a given character string, returning early if any of the given DTMF $digits are received on the channel. 🔤

Returns Example: $AGI->say_alpha('Joe Smith', '#');

Returns:

0 if playback completes without a digit being pressed;
the ASCII numerical value of the digit if one was pressed;
-1 on error/hangup.

$AGI->say_date($time [, $digits])

$AGI->say_time($time [, $digits])

$AGI->say_datetime($time [, $digits [, $format [, $timezone]]])

Executes AGI Command SAY DATE $number $digits Executes AGI Command SAY TIME $number $digits Executes AGI Command SAY DATETIME $number $digits $format $timezone

Say a given date or time, returning early if any of the optional DTMF $digits are received on the channel. $time is number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC), commonly known as "unixtime." ⏰

For say_datetime, $format is the format the time should be said in; see voicemail.conf (defaults to "ABdY 'digits/at' IMp"). 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', 'EDT');

Returns:

-1 on error or hangup;
0 if playback completes without a digit being pressed;
the ASCII numerical value of the digit of one was pressed.

$AGI->say_digits($number, $digits)

Executes AGI Command SAY DIGITS $number $digits

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 ASCII numerical value of the digit of one was pressed.

$AGI->say_number($number, $digits, $gender)

Executes AGI Command SAY NUMBER $number $digits [$gender]

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 ASCII numerical value of the digit of one was pressed.

$AGI->say_phonetic($string, $digits)

Executes AGI Command SAY PHONETIC "$string" $digits

Say a given character string with phonetics, returning early if any of the given DTMF digits are received on the channel. 🗣️

Example: $AGI->say_phonetic('Joe Smith', '#');

Returns:

0 if playback completes without a digit being pressed;
the ASCII numerical value of the digit if one was pressed;
-1 on error/hangup.

$AGI->send_image($image)

Executes AGI Command SEND IMAGE $image

Sends the given image on a channel. Most channels do not support the transmission of images. 🖼️🚫

Example: $AGI->send_image('image.png');

💖 okay so we're picking up right where we left off — here's the tail end of the one before this, bestie, her Returns line was: -1 on error or hangup, 0 if the image was sent or if the channel does not support image transmission.

`$AGI->send_text($text)`

Runs the AGI command SEND TEXT "$text" ✨

Drops your $text onto the channel. Real talk though — most channels do NOT support sending text at all, so don't be shocked if nothing happens 🙈

Example:

$AGI->send_text('You've got mail!');

Returns: -1 on error or hangup, 0 if the text actually got sent or if the channel just doesn't do text transmission. Either way, no drama 💅

`$AGI->set_autohangup($time)`

Runs the AGI command SET AUTOHANGUP $time ⏰

Makes the channel auto-hangup <time> seconds into the future. And yes bestie, it can absolutely get hung up before then too — that's not a bug, that's just how it works. Set it to 0 and the autohangup feature goes fully off on this channel. Bye 👋

Example:

$AGI->set_autohangup(60);

Returns: always 1. She's consistent, we love that 🎀

`$AGI->set_callerid($number)`

Runs the AGI command SET CALLERID $number 📞

Swaps the callerid of the current channel over to <number>. Glow-up for your caller ID, honestly.

Example:

$AGI->set_callerid('9995551212');

Returns: always 1 🔥

`$AGI->set_context($context)`

Runs the AGI command SET CONTEXT $context 🌀

Changes the context that gets used for continuation once you exit the agi application. Like, where the call goes next after you're done.

Example:

$AGI->set_context('dialout');

Returns: always 0 ✨

`$AGI->set_extension($extension)`

Runs the AGI command SET EXTENSION $extension 🌸

Changes the extension for continuation once you exit the agi application — the sibling of the one above, same energy, different field.

Example:

$AGI->set_extension('7');

Returns: always 0 💜

`$AGI->set_music($mode [, $class])`

Runs the AGI command SET MUSIC $mode $class 🎶

Turns the music on hold generator on or off. If you don't pass $class, it just uses the default music on hold class — no biggie. And $mode must be "on" or "off", like there's no third option bestie, pick a lane 🫶

Example:

$AGI->set_music("on", "happy");
$AGI->set_music("off");

Returns: -1 on hangup or error, 0 otherwise 😌

`$AGI->set_priority($priority)`

Runs the AGI command SET PRIORITY $priority ⭐

Changes the priority used for continuation after you exit the agi application.

Example:

$AGI->set_priority(1);

Returns: always 0 🦋

`$AGI->set_variable($variable, $value)`

Runs the AGI command SET VARIABLE $variable $value 💫

Sets the channel variable <variablename> to <value>. Classic.

Example:

$AGI->set_variable('status', 'authorized');

Returns: always 1 👑

`$AGI->stream_file($filename, $digits, $offset)`

Runs the AGI command STREAM FILE $filename $digits [$offset] 🔊

This one tells Asterisk to play the sound file and listen out for the DTMF digits you specified. Heads up though — do NOT put the file extension in the filename, because Asterisk will go find the most appropriate file type all on her own, she's got this 💅

Also $filename can be an array of files or just one single filename. Flexible queen.

Example:

$AGI->stream_file('demo-echotest', '0123');
$AGI->stream_file(['demo-echotest', 'demo-welcome'], '0123');

Returns: -1 on error or hangup, 0 if playback finishes without any digit being pressed, or the ASCII numerical value of the digit if a digit was pressed 🎯

`$AGI->tdd_mode($mode)`

Runs the AGI command TDD MODE <on|off> 📠

Enables or disables TDD transmission/reception on a channel.

Example:

$AGI->tdd_mode('on');

Returns: 1 if it worked, or 0 if the channel just isn't TDD-capable. Not every channel has that range, and that's okay 💀

`$AGI->verbose($message, $level)`

Runs the AGI command VERBOSE $message $level 🗣️

Logs $message at verboselevel $level. For when you need the logs to know.

Example:

$AGI->verbose("System Crashed", 1);

Returns: always 1 😭

`$AGI->wait_for_digit($timeout)`

Runs the AGI command WAIT FOR DIGIT $timeout ⏳

Hangs out for up to $timeout milliseconds waiting for the channel to receive a DTMF digit.

Wanna block forever? Use -1 as the timeout value and just vibe indefinitely, bestie 🧚

Example:

$AGI->wait_for_digit($timeout);

Returns: -1 on channel failure, 0 if no digit showed up within the timeout, or the numerical value of the ascii of the digit if one did arrive 🌈

and that's the whole page, periodt 🎀 This one's from perl v5.24.1, dated 2016-12-22, and it's the Asterisk::AGI(3pm) manpage — thanks for reading all the way to the end bestie, you ate 💖✨

📦 where this page comes from

debian bookworm: libasterisk-agi-perl 1.08-1 · Artistic-1.0-Perl
ubuntu jammy: libasterisk-agi-perl 1.08-1 · Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms