login | register
Wed 20 of Aug, 2008 [11:13 UTC]

voip-info.org

Discuss [3] History

Asterisk AGI

Created by: oej,Last modification on Mon 11 of Aug, 2008 [18:02 UTC] by admin

Asterisk Gateway Interface (AGI)

The Asterisk Gateway Interface is an interface for adding functionality to Asterisk with many different programming languages. Perl, PHP, C, Pascal, Bourne Shell - it's your choice, really.

  • AGI may control the dial plan, called in extensions.conf.
  • EAGI gives the application the possibility to access and control the sound channel in addition to interaction with the dial plan.
  • FastAGI can be used to do the processing on a remote machine via a network connection.
  • DeadAGI gives access to a dead channel, after hangup.

New in Asterisk v1.2.11: GET VARIABLE can now retrieve global variables (see bug 7609)
New in Asterisk v1.2: CallerID is reported with agi_callerid and agi_calleridname instead of a single parameter holding both. The agi_callerid previously held the value "Name"<Number> and the agi_calleridname was not present. In v1.2, agi_callerid has Number and the agi_calleridname has Name.

For debugging purposes you can type "agi debug" on the CLI.

Applications

  • AGI, DeadAGI, and EAGI: Applications to use in extensions.conf
  • FastAGI: Allows running of AGI applications on a remote machine (improves performance for Asterisk)

Dialing out

If the AGI application dials outward by executing Dial, control over the call returns to the dialplan and the script loses contact with the Asterisk server. The script continues to run in the background by itself and is free to clean up and do post-dial processing.

If you want your application to initiate a call out without being started through the dialplan:

AGI Execution Environment


You can pass arguments to an AGI script, like so:
 AGI(script.agi|arg1|arg2|...)

The AGI script can send Asterisk special AGI commands on standard output and read the result on standard input. The result takes this form:

  200 result=X

where X is generally 1 for success and 0 for failure. Some commands return additional name=value pairs. Some return a string value in parentheses.

To list the special commands, type "agi show" in the Asterisk command line interface.

When Asterisk starts an AGI script, it feeds the channel variables to the script on standard input. The variable names are prefixed with "agi_" and are separated from their values by a colon and a space. Though the actual channel variables may be in the upper case, the names passed to an AGI script are all lower case. Also, some channel variable names as passed to AGI script differ from the current variable names used in the dial plan.

Here are some of the variables passed to AGI scripts:

  • agi_channel — calling channel
  • agi_callerid — CALLERID(num)
  • agi_calleridname — CALLERID(name)
  • agi_context — dialplan context from which script was called
  • agi_extension — dialplan extension from which script was called
  • agi_priority — dialplan priority from which script was called
  • agi_language — CHANNEL(language)

Global variables are not passed to the AGI script in this manner. You must get them using the "get variable" AGI command.

An AGI script is also passed a number of environment variables which point to file-system directories which contain Asterisk files. These are:
  • AST_CONFIG_DIR
  • AST_CONFIG_FILE
  • AST_MODULE_DIR
  • AST_SPOOL_DIR
  • AST_MONITOR_DIR
  • AST_VAR_DIR
  • AST_DATA_DIR
  • AST_LOG_DIR
  • AST_AGI_DIR
  • AST_KEY_DIR
  • AST_RUN_DIR

Return value

AGI script returns the following status in variable "AGISTATUS":
  • SUCCESS
  • FAILURE
  • HANGUP

AGI commands




Libraries and Frameworks


ActiveX

  • AstOCX: An activex control for running AGI, FastAGI and DeadAGI on Windows platform.

Java


Pascal/ObjectPascal

  • TPasAGI is compatible with FreePascal/Lazarus as well as CodeGear/Borland Delphi. Use with Delphi supports only FastAGI from Windows computers while both AGI and FastAGI are supported for Lazarus/Freepascal on linux platforms. Released under LGPL License.

Perl


PHP

  • Asterisk AGI php: Advice on how to setup PHP scripts for AGI.
  • phpAGI: PHP classes for AGI and the Asterisk Manager Interface.
  • AgiPhp5
  • PHP ASTLIB: A PHP 5 class for AGI. Built for easy extendability for handing FastAGI.
  • Asterisk PHP (scripting within the dialplan - better than using AGI): http://eder.us/projects/asterisk_php/ Please note that while this is a good idea in concept, per the webpage is not suitable for production use as the implementation has serious threading bugs.)

Python


Ruby


C

  • CAGI: A C API for AGI. Based on PHPAGI.
  • Quivr: A C API for AGI. ANSI C AGI Library.
  • libagiNow: A C library for the development of AGI-programs.
  • AGIAddOns: Asterisk module to add additional AGI commands, such as PUT SOUNDFILE and GET SOUNDFILE, amongst others.
  • AGI Audio File Transfer Addons: Based on AGIAddOns: adds the same AGI commands (although slightly modified), and updated to be compatible with newer versions of Asterisk

.NET


Haskell



Example AGI Applications

Perl

PHP

Python

Bash and Ash

  • Bash AGI: A Bash script that sets the callerID name from NANPA data for the NPA-NXX.
  • MacinTalk AGI: A Bash script that does text to voice with MacinTalk.
  • The distribution package of the LCDial.sh AGI script contains a sh-agi.inc file providing primitives, such as sh_agi_cmd, sh_agi_getvariable and sh_agi_log, to simplify the coding of AGI scripts for the bash and ash shell interpreters.

Haskell


Notes

Fork and continue dialplan

If you don't want Asterisk to wait until the script finishes you can fork the script off to return to dialplan excution: Here's how to accomplish this in Perl:
 open STDOUT, '>/dev/null';
 fork and exit; 

CLI output

>>For some reason, my AGI perl scripts cannot write to the CLI console using
>>standard error. I ran the agi-test.agi test script that came with asterisk
>>and verified that the problem was not with the code. Asterisk is always
>>started with 4 or more v's, yet this the CLI output does not show up. Have
>>there been any major changes to AGI in the cvs-head? I am using Asterisk
>>CVS-D2005.08.05.
>
>This is a known problem. Asterisk will only send STDERR from AGI
>scripts to the actual console Asterisk is running on. You have to
>switch to the actual console Asterisk is running on (tty9 I think) or
>start asterisk in the foreground with "asterisk -cvvv".
>
>It's a minor issue for most people.

We start asterisk under a detached screen with GNU screen. We use the
'L' flag to log to a text file if we want. Then we can "screen -r" to
the actual asterisk CLI any time we want.

 /usr/bin/screen -L -d -m -S asterisk /usr/sbin/asterisk -vvvvvvvvvvvvvvvvvvvvvgc

See http://www.gnu.org/software/screen/

Miscellaneous

  • Using the verbose comand in an AGI you can feed information back to the console (the CLI ) in the same way that applications do. So by specifying different information to be returned at various verbosity levels the AGI will produce results similar to those of Asterisk applications. Make sure you read the return of the VERBOSE command (just like with any other AGI command) before issuing another AGI command. Be aware that VERBOSE will give trouble with quoted strings as e.g. in CALLERID (verbose will cut the string after the first space character).
  • The EAGI extension will let you receive sound from the channel into your application. It will not let you send sound. EAGI is intended to allow you to write a script that passes sound to an external application - such as the Sphinx speech-to-text/speech recognition application (as the example script included with asterisk does). Your EAGI application must also listen for a text response. In the case of Sphinx this would be a string representing the captured speech.
  • Always use AGI unless you specifically need EAGI functionality - unpredictable results may otherwise be obtained.
  • Commands such as "send text" may cause your script to fail if accessed from a phone that has no capability for the requested media type.
  • GET VARIABLE: Does not work with global variables. Does not work with some variables that are generated by modules.

Tutorials

I wrote up a paper on the basics of AGI programming that can be found here (PDF - 76kb). It goes over the basics and includes a sample program. Feedback is welcome!

AGI enhancements



asterisk-agi-audiotx

This is an extension module for the Asterisk Gateway Interface (AGI) that adds commands to allow the transfer of audio files to and from Asterisk via the AGI session. This is useful when using FastAGI from a remote host; sounds recorded by Asterisk may be retrieved by remote FastAGI-providing service, for example, or sound files required by the remote service may be dynamically added to the Asterisk server.
This module adds the following AGI commands:
  • PUT SOUNDFILE <soundfile> <size>
  • GET SOUNDFILE <soundfile>
  • ISEXISTING SOUNDFILE <soundfile>

See also




Comments

Comments Filter
222

333Passing value from Asterisk to Perl Script

by padmaja3, Thursday 27 of September, 2007 [11:08:34 UTC]
Hi all,
I have accepted "intime" as "Read(intime||4)" in extensions.conf.
After that, i'm passing as an argument to perl script.

in extensions.conf

exten => 444,18,AGI(insert_db.pl|${intime})­

in insert_db.pl

  1. !/usr/bin/perl -Tw

use DBI;
use File::Copy;

$table_name = "schedule";

  1. the name of the box the MySQL database is running on
$hostname = "192.168.1.99";
  1. the name of the database our tables are kept
$database = "asterisk";
  1. username to connect to the database
$username = "root";
  1. password to connect to the database
$password = "aDfasoAd12";
  1. print "Connecting to database\n";
$dbh= DBI->connect("dbi:mysql:dbname=­ $database;host=$hostname", "$username", "$password");

$statement = "INSERT into $table_name values(.........)";
  1. i got stuck in above statement as i dont know how to insert values in that table by accepting from Asterisk. "schedule" table has intime,outtime,telephonenumber as fields.#

$result = $dbh->prepare($statement);
$result->execute();

exit 0;

As the scope of "intime" is in Asterisk only, not in database, I'm stuck with how to pass that in "INSERT into schedule values(....)".

Pls suggest me how to proceed here.

Thanks in advance,
Padmaja T N.
222

333more info

by , Sunday 17 of October, 2004 [04:44:45 UTC]
anyone have more detailed info on how to get the card working with mysql?

222

333Database setup?

by , Sunday 16 of May, 2004 [16:38:23 UTC]
how about a mysqldump of a database that'll work with the agi-ccard.agi app?