B.26. DeadAGI()

Runs an AGI compliant program on an inactive channel.
DeadAGI(program,arguments)
Runs an AGI compliant program on an inactive (on hook) channel. With AGI (Asterisk Gateway Interface), you can manipulate channels with programs written in practically any conceivable language. AGI programs can control a channel, play audio, interpret and store DTMF tones; AGI programs exchange data with Asterisk on STDIN und STDOUT. The specified arguments are passed unadulterated to the AGI program.
This application was developed for use on inactive (on hook) channels, because the standard AGI interface will not work on a channel after it is hung up. It is not necessary for the channel to be "dead" at the time of execution, however!
The command show agi, entered on the CLI, will give a list of the available AGI commands.
Returns -1 if the application causes a hang-up, or returns 0 on exit without hang-up.
; run AGI on a hung-up channel:
exten => h,1,DeadAGI(agi-test)

Important

The channel will be treated as active as long as the AGI program is running. This can have implications for CDRs.
Note also that DeadAGI applications receive a SIGHUP signal when the channel is hung up, and it may need to be explicitly ignored in your AGI program:
Perl
$SIG{HUP} = "IGNORE";
PHP
pcntl_signal(SIGHUP, SIG_IGN);
(PHP must be compiled with --enable-pcntl; it is not by default!)
Ruby
trap('SIGHUP','IGNORE')
It is also important for the AGI program to stop communicating after the hang-up, or it will receive a SIGPIPE signal and end (unless the signal is explicitly ignored as in the example above).

Note

Internal help for this application in Asterisk 1.4:
  -= Info about application 'DeadAGI' =- 

[Synopsis]
Executes AGI on a hungup channel

[Description]
  [E|Dead]AGI(command|args): Executes an Asterisk Gateway Interface compliant
program on a channel. AGI allows Asterisk to launch external programs
written in any language to control a telephony channel, play audio,
read DTMF digits, etc. by communicating with the AGI protocol on stdin
and stdout.
  This channel will stop dialplan execution on hangup inside of this
application, except when using DeadAGI.  Otherwise, dialplan execution
will continue normally.
  A locally executed AGI script will receive SIGHUP on hangup from the channel
except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel
variable to "no" before executing the AGI application.
  Using 'EAGI' provides enhanced AGI, with incoming audio available out of band
on file descriptor 3

  Use the CLI command 'agi show' to list available agi commands
  This application sets the following channel variable upon completion:
     AGISTATUS      The status of the attempt to the run the AGI script
                    text string, one of SUCCESS | FAILED | HANGUP
diff output to internal help in Asterisk 1.2:
13,19c13,15
<   This channel will stop dialplan execution on hangup inside of this
< application, except when using DeadAGI.  Otherwise, dialplan execution
< will continue normally.
<   A locally executed AGI script will receive SIGHUP on hangup from the channel
< except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel
< variable to "no" before executing the AGI application.
<   Using 'EAGI' provides enhanced AGI, with incoming audio available out of band
---
> Returns -1 on hangup (except for DeadAGI) or if application requested
>  hangup, or 0 on non-hangup exit. 
> Using 'EAGI' provides enhanced AGI, with incoming audio available out of band
22,25c18
<   Use the CLI command 'agi show' to list available agi commands
<   This application sets the following channel variable upon completion:
<      AGISTATUS      The status of the attempt to the run the AGI script
<                     text string, one of SUCCESS | FAILED | HANGUP
---
> Use the CLI command 'show agi' to list available agi commands