Asterisk Gateway Interface (AGI)
Release 1.05 - 21 Nov 2002 

Note
This document was prepared by Cam Farnell. The content of this document is based on the documentation in the source code, inspection of the source code and experimenting with Asterisk to see what happens. I have attempted to be clear, accurate and complete but I make no guarantees: I am not an Asterisk expert; use at your own risk. I would appreciate having errors, omissions or constructive suggestions drawn to my attention. 

Note 2
This documentation is out of date an will become more so as time goes on. Although at first I tried keeping up with Asterisk development eventually I got tired of my Asterisk system (which is used for a real phone system) breaking and of patches not working any more. Now I just use the system that I put together in late 2002. To the best of my knowledge this document is correct for the version of Asterisk available as of late 2002. 
Introduction
The AGI facility allows you to launch scripts, written in just about any language, from an Asterisk dial plan. Communication between your script and Asterisk is via standard input and standard output. 
Starting your script
Each item in an extension is of the form: 
    exten => extension-number,priority,application,arguments
To launch an AGI script the application is 'agi' and the argument is the filename of your script. The script: 
•	must be executable 
•	must be located in /var/lib/asterisk/agi-bin 
•	must be specified complete with an extension 
For example to run a Python script named 'test.py' then a suitable extension item would be: 
    exten => 1,2,agi,test.py
When your script runs, you get a message saying so on the asterisk console provided you have your 'verbosity' level set to 3 or higher. If your script isn't found (you mis-typed the name) you will get a message saying failed to execute ... no such file or directory. If your script isn't executable (you forgot to give it execute permission) you will get a message saying failed to execute ... permission denied. 

In any case, don't pay too much attention to the console message saying agi script test.py completed returning 0. This simply indicated that executing (or attempting to execute) the script is done; it does NOT imply that the script executed successfully. 

Your script can issue messages to the Asterisk console by sending them to standard error. At least in the initial stages of developing an agi script it isn't a Bad Idea to have the script issue messages along the line of Hi, I'm starting now and Terminating normally just so you know your script ran and completed successfully. 

You can also use the agi VERBOSE command (documented below) to send messages to the console with the added advantage that you can suppress or enable such messages depending on the verbosity setting. 
Passing arguments to your AGI script
Yes Virginia you can pass arguments to your AGI script. You do so by following the name of your script with a vertical bar then the text you want to pass in. Extending the above example, to pass in "yada" as an argument we get: 
    exten => 1,2,agi,test.py|yada
AGI scripts *always* receive two arguments. The first argument is the full path to the script itself. The second argument is the stuff passed in from the "exten" line. It's that second argument we are concerned with here. A few things to note about the second argument: 
•	If no argument is given on the "exten" line or if the argument given is empty, then the argument received is an empty string. 
•	The argument received consists of everything on the line following the vertical bar up until a vertical bar, a semi-colon or a comma. That means the argument may contain spaces. 
•	Quotes, single or double, are simply taken as part of the argument; they have no special effect. 
•	By the time you get the argument any trailing spaces have been deleted but leading spaces are not deleted. 

Communicating with Asterisk
In theory communicating with Asterisk is wonderfully simple: 
•	You write to standard output to send a command to Asterisk. 
•	You read from standard input to get the reply from Asterisk. 
A few things to note: 
•	At script startup time Asterisk sends various pieces of information to your script and you should read these items, via standard input, before doing much else. Each item is sent on a line terminated with a newline and the end of the list is indicated by an empty line. The list of items received will look something like this: 
•	
   agi_request: test.py
•	
   agi_channel: Zap/1-1
•	
   agi_language: en
•	
   agi_type: Zap
•	
   agi_callerid:
•	
   agi_dnid:
•	
   agi_context: default
•	
   agi_extension: 3
•	
   agi_priority: 1
If you need the information provided then save it; otherwise feel free to throw it away. 
•	Commands sent to Asterisk must be terminated with a newline character. 
•	The result returned by AGI commands is a text string, generally of the form: 
200 Result=<number>
although some commands return additional information after the number. If you send Asterisk an invalid command your result will be 
510 Invalid or unknown command
All commands return a result. Commands which don't really need to return a result return 0 as the number. Commands which do need to return a result return various values, as described under the heading 'Returns' below. 

Language specific issues
Although communicating with Asterisk via standard input and output is perfectly simple in theory, there are some practical considerations you need to be aware of and these vary depending on the language used. 
Perl
No known issues using Perl with AGI. 

James Golovich has a number of Perl related AGI modules at http://asterisk.gnuinter.net 

My knowledge of Perl is zero. If some Perl-head would care to send me a version of the 'minimal AGI script' (per the examples below for Pascal, Python and C) I will include it here. 
Free Pascal
Free Pascal works fine with AGI without any special action. The only issue to note is that Pascal has no built-in way to send output to standard error. To send messages to the Asterisk console via standard error you need to use the 'Sysutils' unit and then invoke the FileWrite command to send text to file handle 2, which is standard error. A minimal AGI script in Free Pascal looks like this: 

   Program AgiProto;

   Uses

       Sysutils;

   Var

       Line                : String;

   Begin

       {Read and ignore AGI environment (read till blank line)}

       Repeat;

           Readln(Line);

       Until Line = '';

       {Send Asterisk a command}

       Writeln('SAY NUMBER 123 "*#"');

       {Read response from Asterisk}

       Readln(Line);

       {Show response received on the Asterisk console}

       {glue on CRLF}

       Line := Line + #13#10;

       FileWrite(2,Line[1],Length(Line));

   End.
A Free Pascal unit with routines which ease the task of writing AGI scripts in Pascal is located here and our minimal script, rewritten to use the unit, is located here. 
Python
Python works fine with AGI; the only proviso is that after writing a message to Asterisk (via stdout) or to the Asterisk console (via stderr) you have to flush the corresponding file. Failing to flush stdout will cause the script to come to a grinding halt while Python waits for the buffer to fill and Asterisk waits for a command. A minimal AGI script in Python looks like this: 

   #!/usr/bin/python

   # Import module required.

   import sys

   # Read and ignore AGI environment (read until blank line)

   env = ""

   while(env != "\n"):

   	env = sys.stdin.readline()

   # Send Asterisk a command

   sys.stdout.write('SAY NUMBER 123 "*#"\n')

   # *must* flush the data or Asterisk won't get it

   sys.stdout.flush()

   # Read response from Asterisk

   res = sys.stdin.readline()

   # Show the response received on the Asterisk console

   sys.stderr.write("Received %s\n"%res)

   # And the obligatory flush

   sys.stderr.flush()
A Python module with facilities which ease the task of writing AGI scripts in python is located here and our minimal Python script, rewritten to use the module, is located here. 
C
C works just fine with Asterisk but you should use 'setlinebuf' on stdout and stderr. This causes buffering one line at a time (rather than using a larger buffer). If you *don't* do this on stdout then your script will hang up while Asterisk waits for a command but the (long) buffer isn't full yet. A minimal AGI script in C looks like this: 

   #include <stdio.h>

   main() {

       char        line[80];

       /* use line buffering */

       setlinebuf(stdout);

       setlinebuf(stderr);

       /* read and ignore AGI environment */

       while (1) {

           fgets(line,80,stdin);

           if (strlen(line) <= 1) break;

       }

       /* Send asterisk a command */

       printf("SAY NUMBER 123 \"\"\n");

       /* Read response from Asterisk and show on console */

       fgets(line,80,stdin);

       fputs(line,stderr);

   }

Java
The following example of the minimal agi script written in java appears here thanks to a kind contribution from Carlos Pineda. 

   file: test-java.agi

   --------------------------

   #!/bin/bash

   #some examples to set the class path

   AGI_DIR=/var/lib/asterisk/agi-bin

   JAVA_SCRIPTS=/usr/lib/asterisk/java/test.jar #add any jar that you need

   #exec the Java VM

   $JAVA_HOME/bin/java -cp $AGI_DIR:$JAVA_SCRIPTS TestAGI

   file: TestAGI

   ----------------------------------

   import java.io.*;

   public class TestAGI {

       public static void main( String[] args ) {

           try {

               String linea;

               LineNumberReader in =  new LineNumberReader( new InputStreamReader( System.in ) );

               do { //read AGI environmet

                   linea = in.readLine();

               } while ( linea.length() > 0 );

               System.out.println( "SAY NUMBER 123 \"*#\"" );

               linea = in.readLine();

               System.err.println("Received "+linea);

               System.exit( 0 );

           } catch( Exception ex ) {

               System.err.println("Error: "+ex.getMessage());

           }

       }

   }

AGI commands
If your script does some simple operation and then terminates, great, that's the easy case. There are often times, however, when your script wants to have Asterisk do something or supply some information and that's where commands to Asterisk come in handy. 

The commands available are documented below. Most of the commands will work with all clients, but some commands, as marked in the 'notes' section, require a special client (such as GnoPhone ). Remember that each command documented below must be followed by a newline character (\n) when it is sent to Asterisk via standard output. Note also that the command names are case insensitive. Although they are shown below in ALL UPPER CASE they be used in any mixture of upper and lower case. 

ANSWER 
AUTOHANGUP <time> 
CHANNEL STATUS [<channelname>] 
EXEC <application> <options> 
GET DATA <filename> [<timeout>] [<max digits>] 
GET VARIABLE <variablename> 
HANGUP [<channelname>] 
RECEIVE CHAR <timeout> 
RECORD FILE <filename> <format> <escape digits> <timeout> [BEEP] 
SAY DIGITS <digit string> <escape digits> 
SAY NUMBER <number> <escape digits> 
SEND IMAGE <image> 
SEND TEXT "<text to send>" 
SET CALLERID <number> 
SET CONTEXT <desired context> 
SET EXTENSION <new extension> 
SET PRIORITY <new priority number> 
SET VARIABLE <variablename> <value> 
STREAM FILE <filename> <escape digits> 
TDD MODE <on|off> 
VERBOSE <level> 
WAIT FOR DIGIT <timeout> 

ANSWER

Purpose
Answer channel if not already in answer state. 
Returns
-1 on channel failure, or 0 if successful. 

AUTOHANGUP <time>

Purpose
Cause the channel to automatically hangup at <time> seconds in the future. If <time> is 0 then the autohangup feature is disabled on this channel. 
Returns
0 
Note
If the channel is hungup prior to <time> seconds, this setting has no effect. 

CHANNEL STATUS [<channelname>]

Purpose
Return the status of the specified channel. If no channel name is specified, return the status of the current channel. 
Returns
-1 There is no channel that matches the given <channelname> 
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 
Examples
CHANNEL STATUS
Return the status of the current channel. 
CHANNEL STATUS Zap/9-1
Return the status of channel Zap/9-1 
Note
The <channelname> to use is the same as the channel names reported by the Asterisk console 'show channels' command. 

EXEC <application> <options>

Purpose
Executes the specified Asterisk <application> with given <options>. 
Returns
Whatever the application returns, or -2 on failure to find the application. 

GET DATA <filename> [<timeout> [<max digits>]]

Purpose
Plays the given file and receives DTMF data. This is similar to STREAM FILE, but this command can accept and return many DTMF digits, while STREAM FILE returns immediately after the first DTMF digit is detected. 
Returns
•	If the command ended due to timeout then the result is of the form 
    200 Result=<digits> (timeout)
where <digits> will be zero or more ASCII characters depending on what the user pressed. 
•	If the command ended because the maximum number of digits were entered then the result is of the form 
    200 Result=<digits>
and the number of digits returned will be equal to <max digits>. 
•	In either case what you get are actual ASCII characters. For example if the user pressed the one key, the three key and then the star key, the result would be 
    200 Result=13* (timeout)
This differs from other commands with return DTMF as numbers representing ASCII characters. 

Notes
•	Don't give an extension with the filename. 
•	Asterisk looks for the file to play in /var/lib/asterisk/sounds 
•	If the user doesn't press any keys then the message plays, there is <timeout> milliseconds of silence then the command ends. 
•	The user has the opportunity to press a key at any time during the message or the post-message silence. If the user presses a key while the message is playing, the message stops playing. When the first key is pressed a timer starts counting for <timeout> milliseconds. Every time the user presses another key the timer is restarted. The command ends when the counter goes to zero or the maximum number of digits is entered, whichever happens first. 
•	If you don't specify a time out then a default timeout of 2000 is used following a pressed digit. If no digits are pressed then 6 seconds of silence follow the message. 
•	If you want to specify <max digits> then you *must* specify a <timeout> as well. 
•	If you don't specify <max digits> then the user can enter as many digits as they want. 
•	Pressing the # key has the same effect as the timer running out: the command ends and any previously keyed digits are returned. A side effect of this is that there is no way to read a # key using this command. 

GET VARIABLE <variablename>

Purpose
Fetch the value of a variable. 
Returns
Returns 0 if the variable hasn't been set. Returns 1 followed by the value of the variable in parenthesis if it has been set. 
Example
SET VARIABLE Baffy "This is a test"
200 result=1
GET VARIABLE Baffy
200 result=1 (This is a test)

HANGUP [<channelname>]

Purpose
Hangup the specified channel. If no channel name is given, hang up the current channel. 
Returns
If the hangup was successful then the result is 200 result=1 

If no channel matches the <channelname> you specified then the result is 200 result=-1 
Examples
HANGUP
Hangup the current channel. 
HANGUP Zap/9-1
Hangup channel Zap/9-1 
Notes
The <channelname> to use is the same as the channel names reported by the Asterisk console 'show channels' command. 

With power comes responsibility. Hanging up channels other than your own isn't something that is done routinely. If you are not sure why you are doing so, then don't. 

RECEIVE CHAR <timeout>

Purpose
Receive a character of text from a connected channel. Waits up to <timeout> milliseconds for a character to arrive, or infinitely if <timeout> is zero. 
Returns
•	If a character is received, returns the ASCII value of the character as a decimal number. For example if the character 'A' is received the result would be 
    result=65
•	If the channel does not support text reception or if the no character arrives in <timeout> milliseconds then the result is 
    result=0 (timeout)
•	On error or failure the result is 
    result=-1

Note
Most channels do not support the reception of text. 

RECORD FILE <filename> <format> <escape digits> <timeout> [BEEP]

Purpose
Record sound to a file until an acceptable DTMF digit is received or a specified amount of time has passed. Optionally the file BEEP is played before recording begins. 
Returns
•	The documentation in the code says on hangup the result is -1, however when I tried it the hangup result was 
    result=0 (hangup)
•	If an error occurs then the result is -1. This can happen, for example, if you ask for a non-existent format. 
•	If the user presses an acceptable escape digit then the result is a number representing the ASCII digit pressed. For example if recording terminated because the user pressed the '2' key the result is 
    result=50 (dtmf)

Example
RECORD FILE baffy gsm 123 5000 beep
Record sound in gsm format to file 'baffy.gsm'. Play a beep before starting to record. Stop recording if user presses '1', '2' or '3', after five seconds of recording, or if the user hangs up. 
Notes
•	Don't put an extension on the filename; the filename extension will be created based on the <format> specified. 
•	The file will be created in 
/var/lib/asterisk/sounds

•	<format> specifies what kind of file will be recorded. GSM is a commonly used format. To find out what other formats are supported start Asterisk with at a verbosity level of at least 2 (-vvc) and look for the messages that appear saying "== Registered file format <whatever>'. Most but not all registered formats can be used, for example, Asterisk can read but not write files in 'mp3' format. 
•	If you don't want ANY digits to terminate recording then specify "" instead of a digit string. To change the above example so no digits terminate recording use RECORD FILE baffy gsm "" 5000 beep 
•	<timeout> is the maximum record time in milliseconds, or -1 for no timeout. When this document was written [Nov 2002] I was unable to get <timeout> to work; this command always kept recording until I pressed an escape digit or hung up, as if -1 had been specified for timeout. A patch to correct this has been submitted but has not yet shown up in the CVS tree. 

SAY DIGITS <digit string> <escape digits>

Purpose
Say the given digit string, returning early if any of the given DTMF escape digits are received on the channel. If no DTMF digits are to be received specify "" for <escape digits>. 
Returns
Zero if playback completes without a digit being received, or the ASCII numerical representation of the digit pressed, or -1 on error or hangup. 
Example
SAY DIGITS 123 78# 

The digits 'one', 'two', 'three' are spoken. If the user presses the '7', '8' or '#' key the speaking stops and the command ends. If the user pressed no keys the result would be 200 result=0. If the user pressed the '#' key then the result would be 200 result=35. 

SAY NUMBER <number> <escape digits>

Purpose
Say the given number, returning early if any of the given DTMF escape digits are received on the channel. If no DTMF digits are to be accepted specify "" for <escape digits>. 
Returns
Zero if playback completes without a digit being received, or the ASCII numerical representation of the digit pressed, or -1 on error or hangup. 
Example
SAY NUMBER 123 789 

The phrase 'one hundred twenty three' is spoken. If the user presses the '7', '8' or '9' key the speaking stops and the command ends. If the user pressed no keys the result would be 200 result=0. If the user pressed the '#' key then the result would be 200 result=35. 

SEND IMAGE <image>

Purpose
Send the specified image on a channel. The image name should not should not include the extension. 
Returns
Zero if the image is sent or if the channel does not support image transmission. Returns -1 only on error or hangup. 
Notes
•	Asterisk looks for the image in /var/lib/asterisk/images 
•	Most channels do not support the transmission of images. 

SEND TEXT "<text to send>"

Purpose
Send the given text to the connected channel. 
Returns
0 if text is sent or if the channel does not support text transmission. Returns -1 only on error or hangup. 
Example
SEND TEXT "Hello world" 
Note
Most channels do not support transmission of text. 

SET CALLERID <caller ID specification>

Purpose
Changes the caller ID of the current channel 
Returns
Always returns 200 result=1 
Example
SET CALLERID "John Smith"<1234567> 
Notes
This command will let you take liberties with the <caller ID specification> but the format shown in the example above works well: the name enclosed in double quotes followed immediately by the number inside angle brackets. 
•	If there is no name then you can omit it. 
•	If the name contains no spaces you can omit the double quotes around it. 
•	The number must follow the name immediately; don't put a space between them. 
•	The angle brackets around the number are necessary; if you omit them the number will be considered to be part of the name. 

SET CONTEXT <new context>

Purpose
Sets the context for continuation upon exiting the application. 
Returns
Always returns 200 result=0. 
Example
SET CONTEXT demo 
Notes
•	Setting the context does NOT automatically reset the extension and the priority; if you want to start at the top of the new context you should set extension and priority yourself. 
•	If you specify a non-existent context you receive no error indication (the result returned is still 'result=0') but you do get a warning message on the Asterisk console. 

SET EXTENSION <new extension>

Purpose
Set the extension to be used for continuation upon exiting the application. 
Returns
Always returns 200 result=0. 
Example
SET EXTENSION 23 
Note
•	Setting the extension does NOT automatically reset the priority. If you want to start with the first priority of the extension you should set the priority yourself. 
•	If you specify a non-existent extension you receive no error indication (the result returned is still 'result=0') but you do get a warning message on the Asterisk console. 

SET PRIORITY <new priority number>

Purpose
Set the priority to be used for continuation upon exiting the application. 
Returns
Always returns 200 result=0. 
Example
SET PRIORITY 5 
Note
If you specify a non-existent priority you receive no error indication of any sort: the result returned is still 'result=0' and no warning is issued on the Asterisk console. 

SET VARIABLE <variablename> <value>

Purpose
Sets a variable to the specified value. The variables so created can later be used by later using ${<variablename>} 
in the dialplan. 
Returns
Always returns 200 result=1. 
Example
SET VARIABLE station zap/3 

Creates a variable named 'station' with the value 'zap/3'. 
Notes
•	Unlike most of Asterisk, variable names are case sensitive. The names 'Baffy' and 'baffy' refer to two separate and distinct variables. 
•	If the value being assigned contains spaces then put it inside double quotes. 
•	If you want double quotes inside the value then you have to escape them. For example to create a variable CID whose value is "John Doe"<555-1212> you could use: 
SET VARIABLE CID "\"John Doe \"<555-1212> 

Be aware that the language you are using may eat the backslash before it gets passed to Asterisk; you may have to use two backslashes or otherwise tell the language that, yes, you really do want a backslash in the string you are sending. 
•	These variables live in the channel Asterisk creates when you pickup a phone and as such they are both local and temporary. Variables created in one channel can not be accessed by another channel. When you hang up the phone, the channel is deleted and any variables in that channel are deleted as well. 

STREAM FILE <filename> <escape digits>

Purpose
Play the given audio file, allowing playback to be interrupted by a DTMF digit. This command is similar to the GET DATA command but this command returns after the first DTMF digit has been pressed while GET DATA can accumulated any number of digits before returning. 
Returns
If playback finished with no acceptable digit being pressed the result is zero. If an acceptable digit was pressed the result is the decimal representation of the pressed digit. If the channel was disconnected or an error occurred the result is -1. 
Example
STREAM FILE welcome # 

Plays the file 'welcome'. If the user presses the '#' key the playing stops and the command returns 200 result=35 
Note
•	Don't give an extension with the filename. 
•	Asterisk looks for the file to play in /var/lib/asterisk/sounds 
•	Use double quotes if the message should play completely. For example to play audio file 'welcome' without allowing interruption by digits use: STREAM FILE welcome "" 

TDD MODE <setting>

Purpose
Enable or disable TDD transmission/reception on the current channel. 
Returns
1 if successful or 0 if the channel is not TDD capable. 
Example
TDD MODE on 
Note
The argument <setting> can be 'on' or 'tdd' to enable tdd mode. It can also be 'mate' which apparently sets some unspecified tdd mode. If it is anything else ('off' for example) then tdd mode is disabled. 

VERBOSE <message> [<level>]

Purpose
Sends <message> to the Asterisk console via the 'verbose' message system. 
Returns
Always returns 1 
Example
VERBOSE Hello 3 

Sends the message "Hello" to the console if the current Asterisk verbosity level is set to 3 or greater. 
Notes
•	<level> is the verbosity level in the range 1 through 4. 
•	If your message contains spaces, then enclose it in double quotes. 
•	The Asterisk verbosity system works as follows. The Asterisk user gets to set the desired verbosity at startup time or later using the console 'set verbose' command. Messages are displayed on the console if their verbose level is less than or equal to desired verbosity set by the user. More important messages should have a low verbose level; less important messages should have a high verbose level. 

WAIT FOR DIGIT <timeout>

Purpose
Waits up to 'timeout' milliseconds for channel to receive a DTMF digit 
Returns
-1 on channel failure, 0 if no digit is received in timeout or the numerical value of the ascii of the digit received. 
Note
Use -1 for the timeout value if you want the call to wait indefinitely. 
Example
WAIT FOR DIGIT 3000 

If the user didn't press a digit within three seconds then the response is 200 result=0. If the user pressed the 9 digit the response is 200 result=57.