Skip to content

AGI()

Synopsis

Executes an AGI compliant application.

Description

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.

The following variants of AGI exist, and are chosen based on the value passed to command:

  • AGI - The classic variant of AGI, this will launch the script specified by command as a new process. Communication with the script occurs on 'stdin' and 'stdout'. If the full path to the script is not provided, the astagidir specified in asterisk.conf will be used.

  • FastAGI - Connect Asterisk to a FastAGI server using a TCP connection. The URI to the FastAGI server should be given in the form '[scheme]://host.domain[:port][/script/name]', where scheme is either 'agi' or 'hagi'.
    In the case of 'hagi', an SRV lookup will be performed to try to connect to a list of FastAGI servers. The hostname in the URI must be prefixed with '_agi._tcp'. prior to the DNS resolution. For example, if you specify the URI 'hagi://agi.example.com/foo.agi' the DNS query would be for '_agi._tcp.agi.example.com'. You will need to make sure this resolves correctly.

  • AsyncAGI - Use AMI to control the channel in AGI. AGI commands can be invoked using the 'AMI' action, with a variety of AGI specific events passed back over the AMI connection. AsyncAGI should be invoked by passing 'agi:async' to the command parameter.

Note

As of '1.6.0', this channel will not stop dialplan execution on hangup inside of this application. Dialplan execution will continue normally, even upon hangup until the AGI application signals a desire to stop (either by exiting or, in the case of a net script, by closing the connection). A locally executed AGI script will receive 'SIGHUP' on hangup from the channel except when using 'DeadAGI' (or when the channel is already hungup). A fast AGI server will correspondingly receive a 'HANGUP' inline with the command dialog. Both of these signals may be disabled by setting the AGISIGHUP channel variable to 'no' before executing the AGI application. Alternatively, if you would like the AGI application to exit immediately after a channel hangup is detected, set the AGIEXITONHANGUP variable to 'yes'.

Example: Start the AGI script /tmp/my-cool-script.sh, passing it the contents of the channel variable FOO
same => n,AGI(/tmp/my-cool-script.sh,${FOO})
Example: Start the AGI script my-cool-script.sh located in the astagidir directory, specified in asterisk.conf
same => n,AGI(my-cool-script.sh)
Example: Connect to the FastAGI server located at 127.0.0.1 and start the script awesome-script
same => n,AGI(agi://127.0.0.1/awesome-script)
Example: Start AsyncAGI
same => n,AGI(agi:async)
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

    • FAILURE

    • NOTFOUND

    • HANGUP

Syntax

AGI(command,arg1,[arg2[,...]])
Arguments

  • command - How AGI should be invoked on the channel.

  • args - Arguments to pass to the AGI script or server.

    • arg1 required

    • arg2[,arg2...]

See Also

Generated Version

This documentation was generated from Asterisk branch 21 using version GIT