Elastix Unified Communications Server Cookbook

Asterisk Gateway Interface is an implementation that allows any external program to control and interact with Asterisk's Dialplan using STDIN (standard input), STDOUT (standard output), and STDERR (standard error) data streams.

We consider as STDIN all the information sent from Asterisk to the program, and as STDOUT all the data sent back to Asterisk. In other words, AGI lets us add more functionality with Asterisk using any program from bash, Perl, PHP, Visual Basic, and so on. We can even write programs that allow us to communicate with databases, open files, and so on.

The way an AGI program is invoked from Dialplan is as follows:

[context]
exten => 8888,1,Answer
exten => 8888,n,AGI(script.agi, arg1, arg2, …)
exten => 8888,n,Hangup()

All the AGI scripts or program are stored in the /var/lib/asterisk/agi-bin folder.

The most common AGI frameworks are:

Asterisk PERL Library: http://asterisk.gnuinter.net/
PHPAGI: http://sourceforge.net/projects/phpagi/
py-Asterisk: http://py-asterisk.berlios.de/py-asterisk.php
C libagiNow: http://www.open-tk.de/libagiNow/
.NET MONO-TONE: http://gundy.org/asterisk

The information passed between Asterisk and any AGI is given in the following table:

AGI Variable	Description
`agi_request`	Name of the AGI script
`agi_channel`	Channel of the call used to invoke the AGI script
`agi_language`	Language code of the call
`agi_type`	The type of channel used by the call (SIP,ZAP,DAHDI,IAX, and so on)
`agi_uniqueid`	A unique identifier for this call
`agi_callerid`	Caller ID number
`agi_calleridname`	Caller ID name
`agi_callingpres`	PRI Call ID presentation
`agi_callingani2`	Caller ANI2 (used on PRI channels)
`agi_callington`	Caller type of number (PRI channels)
`agi_callingtns`	Transit Network Selector (used on PRI channels)
`agi_dnid`	Dialed number ID
`agi_rdnis`	Referring Dial Number ID Service (RDNIS)
`agi_context`	The context in which the AGI script was executed
`agi_extension`	Extension that was called
`agi_priority`	The priority in the dialplan from which the AGI was invoked
`agi_accountcode`	Account code for the originating channel

The list of commands executed from the AGI is given as follows:

Command	Description
`answer`	Answer channel
`asyncagi break`	Interrupts Async AGI
`channel status`	Returns status of the connected channel
`database del`	Removes database key/value
`database deltree`	Removes database keytree/value
`database get`	Gets database value
`database put`	Adds/updates database value
`exec`	Executes a given application
`get data`	Prompts for DTMF on a channel
`get full variable`	Evaluates a channel expression
`get option`	Stream file, prompt for DTMF with timeout
`get variable`	Gets a channel variable
`hangup`	Hangs up a channel
`noop`	Does nothing
`receive char`	Receives one character from channels supporting it
`receive text`	Receives text from channels supporting it
`record file`	Records to a given file
`say alpha`	Says a given character string
`say digits`	Says a given digit string
`say number`	Says a given number
`say phonetic`	Says a given character string with phonetics
`say date`	Says a given date
`say time`	Says a given time
`say datetime`	Says a given time as specified by the format given
`send image`	Sends images to channels supporting it
`send text`	Sends text to channels supporting it
`set autohangup`	Auto-hangup channel in some time
`set callerid`	Sets caller ID for the current channel
`set context`	Sets channel context
`set extension`	Changes channel extension
`set music`	Enables/disables music on hold generator
`set priority`	Sets channel dialplan priority
`set variable`	Sets a channel variable
`stream file`	Sends audio file on channel
`control stream file`	Sends audio file on channel and allows the listener to control the stream
`tdd mode`	Toggles TDD mode (for the deaf)
`verbose`	Logs a message to the asterisk verbose log
`wait for digit`	Waits for a digit to be pressed
`speech create`	Creates a speech object
`speech set`	Sets a speech engine setting
`speech destroy`	Destroys a speech object
`speech load grammar`	Loads grammar
`speech unload grammar`	Unloads grammar
`speech activate grammar`	Activates grammar
`speech deactivate grammar`	Deactivates grammar
`speech recognize`	Recognizes speech
`gosub`	Causes the channel to execute the specified dialplan subroutine

Tip

To learn more about Asterisk's Gateway Interface, visit http://www.voip-info.org/wiki/view/Asterisk+AGI.

Elastix Unified Communications Server Cookbook

Elastix Unified Communications Server Cookbook

Overview of this book

Related Content you might be interested in

Current Title:

Elastix Unified Communications Server Cookbook

Appendix D. Asterisk Gateway Interface Programming

Tip