dijexi.com

The (AGI) Asterisk Gateway Interface is an interface for adding functionality to Asterisk with many different programming languages. Perl, PHP, C, Pascal, Bourne Shell, or any other programming language that you like.

To use AGI, create an extension on extension.conf, with this format (example extension number 5151):

exten => 5151,1,AGI(test.php)

Then place the script (for example in PHP, test.php) on the specified AGI folder in asterisk.conf, for example in /var/lib/asterisk/agi-bin.

The script should be executable, so you must first chmod +x to the script.

As an example, let create simple AGI application that fetch the web for a currency data and speak it to the caller. To simplify our self, we are going to use PHP and PHPAGI library.

The web service URL that we are going to fetch is located at http://www.webservicex.com/CurrencyConvertor.asmx/ConversionRate?FromCurrency=USD&ToCurrency=IDR

This will return the conversion rate in XML format of the FromCurrency to the ToCurrency. For simplicity we make it hard coded now. You can change the values for the both parameters.

Before we begin, first download latest version of PHP AGI library from http://sourceforge.net/projects/phpagi/, extract, and put phpagi.php, phpagi-asmanager.php, and phpagi-fastagi.php files on /var/lib/asterisk/agi-bin.

Also, you need to install Fextival text to speech so that Asterisk can answer the caller using the text that we supply.

Let’s create a new PHP script and save it on /var/lib/asterisk/agi-bin as curr.php. Here is the source code:

#!/usr/bin/php -q
<?

set_time_limit(30);
//load PHP AGI
require(‘phpagi.php’);
$agi = new AGI();

//answer the call
$agi->answer();

//fetch the web service and store the result into $curr
$fromCurrency="USD";
$toCurrency="IDR";
$res=file_get_contents("http://www.webservicex.com/CurrencyConvertor.asmx/ConversionRate?FromCurrency=$fromCurrency&ToCurrency=$toCurrency");
$xml = new SimpleXMLElement($res);
$curr=$xml[0];

$agi->text2wav("Currency rate from $fromCurrency to $toCurrency is");
$agi->say_number($curr);
$agi->text2wav("Thank you");
$agi->hangup();

?>

A few thing to consider on the above code:

First we set the allowable processing time limit to 30 seconds, and load the PHP AGI library, then we instantiate the $agi variable. Then we answer the call using $agi->answer().

Then we fetch the currency data from the web service URL, and store the data into $res variable which is an XML string. We convert it into XML object by using SimpleXMLElement, and get the conversion value which is stored on $xml[0] and store it into $curr variable. You may inspect the XML structure by calling print_r($xml).

Next we call $agi->text2wav() that will say anything supplied into it’s parameter. And we call $agi->say_number($curr). At the end, we say thank you and hang up the phone by $agi->hangup().

Now edit /etc/asterisk/extension.conf and add the following lines under the context that your phone can access, for example Internal context.

[Internal]
exten => 5151,1,AGI(curr.php)

Call the extension number 5151 from your phone, and you will get replied by the system telling you the currency rate between USD and IDR.. But don’t get surprised with the big value, this is Indonesia :(

Further PHP AGI functions that might interest you are:

1. get_data to get DTMF data for you application to process, like the IVR menu
2. parse_callerid to parse and get the caller ID information 
3. record_file to record caller’s voice

For further information and consultation, you may contact me directly:

Akhmad Daniel Sembiring
akhmad.daniel[at]gmail.com
vitraining.com – CEO

Further reading:

1. http://www.voip-info.org/wiki/view/Asterisk+AGI
2. http://sourceforge.net/projects/phpagi/
3. http://www.asterisk.org