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:

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

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.

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.