Asterisk Gateway Interface - Perl

Asterisk Gateway Interface

1. What is Asterisk Gateway Interface? 

In simple word AGI is Language Independent API to programmers to control the call flow on their Asterisk PBXs.

Asterisk provides more than its own dial-plan, to control to the call flow or lets say call logics. So which means you may use either one of

1. Dialplan
2. Asterisk Manager Interface (AMI)
3. Asterisk Gateway Interface (AGI)

to manipulate your call logics.

Before we move on to AGI lets briefly discuss about each one of above,

Dialplan

Dial plan is Asterisk native call logics performer, it's fast, easy to learn and efficient. But this configuration script is more closer to assembly program (If you have any previous experience on assembly), the main drawback of the Asterisk Dialplan in it's lack of support on standard procedural  language as an example when you want create a loop. 

Any way in the following tutorials we will only discuss about the AGI, But we can't avoid the fact that we need Dialplan to call out AGI script.

Asterisk Manager Interface (AMI)

What if you have a remote controller to your Asterisk PBX, it is AMI. It is more sophisticate with regards to Dialplan. So in essence you can control your PBX by using TCP socket. 

You can use a remote control tool to control your PBX but beware there are more security concerns would be followed up with this.

Asterisk Gateway Interface (AGI)

If you consider AMI and Dialplan regards to AGI, AGI should lay between them. AGI can't be completely independent, we have to get the support of the Dialplan, also you may use your desired language on AGI script. 

In this tutorial I'll use Perl on our AGI script...

But please note that if your PBX system is pure outbound AGI is not for you, AGI is only for inbound call  handling.

There are four type of AGI's you can find,

• Standard AGI

It is the Simplest of all, and use standard inputs(STDIN) and outputs(STDOUT) to communicate with the PBX. In this tutorial are about to use this one. 

• Dead AGI

Dead AGI is to handle the call logics after call hangup. Some AGI commands will not be able to use under this. 

• Fast AGI

Using Fast AGI you can transfer your AGI processing burden to another server. You may use TCP sockets for the communications. It's Provide all the features in Standard AGI. 

• EAGI

If Developers need to access/communicate beyond the STDIN and STDOUT which if they need to access the media channel, they may use EAGI.

2. Okay Now it's time to discuss our scenario,

I have two SIP peers call, peter and bob. We need them to able call with each other, and if one of them is not available, calling party should be able to drop a voice mail.

Later the other party may listen to that voice mail by accessing their voice mail.

By Dialing an extension with '*' (eg: *101) can listen their Voice Mail Boxes 

Create two sip peers for bob and peter

• sip.conf

          [peter]             ;Peer name
          type=friend         ;Allow both incoming and outgoing 
          secret=123          ;Password for SIP peer
          host=dynamic        ;IP address of the SIP peer 
          allow=alaw,ulaw     ;Allowed coddecs
          context=users       ;Dialplan context for the SIP peer

          [bob]
          type=friend
          secret=123
          host=dynamic
          allow=alaw,ulaw
          context=users

         
Configure Dialplan to use our AGI script 

• extensions.conf

   [users]
          exten => _[*0-9]X.,1,NoOp("Dialiing AGI") ; This will accept dial pattern which are starting from * or from a number
          same => n,AGI(dialplan.pl,${EXTEN})            ; run Our AGI script which resides in agi-bin, and also we are providing the dialled extension number as a command line input. 

Configure voice mail boxes

• voicemail.conf

          [sales]                                       ;VM Context
          101 => 123,Bob's Mailbox,bob@example.com ;vmbox => [password],[Description], [Mail address to use]
          102 => 321,Peter's Mailbox,peter@example.com

         

Now please reload your configuration through asterisk CLI and Verify them

                   #rasterisk
                     > sip reload
                     > sip show peers
                     > dialplan reload
                     > voicemail reload
                     > voicemail show users

              

Now lets look at our Perl script

#!/usr/bin/perl
use warnings;
use strict;

#apt-get install build-essential

use Asterisk::AGI;

Asterisk::AGI for perl : 

First you may install cpan which is use to manage perl module by using 

#apt-get install build-essential

Then install Asterisk:AGI module using cpan

#cpan

>install Asterisk::AGI

Now in here I've define a global variable and assign the extension number which has passed as a command line argument from the Dialplan.

our $DPLAN_EXTEN=$ARGV[0];

Now depends on the number that dialed, if number start with '*' it should dialed to relevant voice mail box or else if it's a number it should directly dial the relevant sip peer.

if ($DPLAN_EXTEN =~ m/^\*/){
       vm_box();
} else {
       main();
}

####Call Routes between two peers, Bob and Peter 
sub main{

#-->In here I have created a hash(a nested hash) to store relevant information to use
 my %EXTEN_CONF = (
                '101' => {
                        'CHAN'          =>'SIP',
                        'PEER'          =>'bob',
                        'MAXWAIT'       =>5,
                        'VM_CONTEXT'    =>'sales',
                },
                '102' => {
                        'CHAN'          =>'SIP',
                        'PEER'          =>'peter',
                        'MAXWAIT'       =>5,
                        'VM_CONTEXT'    =>'sales',
                },
 );

#-->Now here we create our AGI object
my $AGI = new Asterisk::AGI;


#-->Use exec to use any Dialplan Application in your AGI script. Using exec you can execute the relevant application and pass the argument to the relevant application.
#-->$AGI->exec($app, $options)
#--> As per the following example, execute dial function and pass relevant Chanel , Peer and wait time. If you execute the following on the Dialplan it would be "exten => 101,1,Dial(SIP/bob,5)"
$AGI->exec('Dial',"$EXTEN_CONF{$DPLAN_EXTEN}{'CHAN'}/$EXTEN_CONF{$DPLAN_EXTEN}{'PEER'},$EXTEN_CONF{$DPLAN_EXTEN}{'MAXWAIT'}");

#-->Now in order to put a voice mail use voice mail function
$AGI->exec('VoiceMail',"$DPLAN_EXTEN\@$EXTEN_CONF{$DPLAN_EXTEN}{'VM_CONTEXT'}");


#-->To Hangup
$AGI->hangup();
}

####Listen to the Voice Mails
sub vm_box{
#-->In order to store the informations regarding to the voice mail boxes here I've use a hash again
my %VM_CONF = (
                '*101' => {
                        'VM_BOX'        =>'101',
                        'VM_CONTEXT'    =>'sales',
                },
                '*102' => {
                        'VM_BOX'        =>'102',
                        'VM_CONTEXT'    =>'sales',
                },
);
my $AGI = new Asterisk::AGI;
$AGI->exec('VoiceMailMain',"$VM_CONF{$DPLAN_EXTEN}{VM_BOX}\@$VM_CONF{$DPLAN_EXTEN}{VM_CONTEXT}");
$AGI->hangup();

You can put your AGI file in asterisk agi-bin. in my Debian system its on 

#cd /var/lib/asterisk/agi-bin

In order to properly run the script change the ownership to your Asterisk user and grant the execute permission.

#chown asterisk:asterisk dialplan.pl
#chmod u+x dialplan.pl

Click here to download configuration file.

To get the asterisk Dialplan application information and how to use them you may refer asterisk CLI or you can search them on https://www.voip-info.org.

Installing Perl modules,

Thats it.... Enjoy....