Asterisk Gateway Interface (AGI)

Release 1.05 - 21 Nov 2002



Note

This document was prepared by Cam Farnell (hsa01 .a.t. bitflipper .d.o.t. ca - NOTE: put "to-cam" somewhere in the subject line else your email will get silently trashed by my spam filters) 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: 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:

Communicating with Asterisk

In theory communicating with Asterisk is wonderfully simple: A few things to note:

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



Notes




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



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



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




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




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.



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




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




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




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




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




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.