Integrating Asterisk with External Systems

Introduction

In this tip, we will create a simple Java application that gets today’s day from the system date and read back to the caller like “Today is Monday”. And we will discuss the power of Fast AGI to integrate Java application with Asterisk system.

Background

Asterisk is a Private Branch eXchange (PBX) system in Software or simply a communication platform. You can use Asterisk to develop any telephony system; yes I mean any from simple home PBX to complex Voice over IP (VOIP) systems. Its power comes in its ability to integrate with various database systems and could get integrated with any other external systems. Learn more from the official Asterisk website.

Using AGI

Asterisk has two features to integrate with external systems. These are: Asterisk Management Interface (AMI) and Asterisk Gateway Interface (AGI). AMI is mostly used to control and manage the asterisk system from external system. While AGI is a gateway to external systems, you can imagine AGI as an API to Asterisk.

An AGI communicates with the dial plan through STDIN (Standard Input) and STDOUT (Standard Output). In order to make our code visible to Asterisk, we have to put our AGI script under the directory /var/lib/asterisk/agi-bin/. Let’s say we have an application that returns today’s day and name it day.agi. <o:p>

We will call the AGI script though:<o:p>

exten => 123,1,Agi(day.agi) 

This is simple but will be clumsy for calls with a magnitude of hundreds or thousands at a time. For that reason, we will use a Fast AGI, an advanced AGI. Fast AGI is a TCP/IP based AGI which enables you to have a dedicated remote server serving the application. Separating the application server from the communication server is also a big plus for the performance of our system and can handle several calls simultaneously. <o:p>

The format to invoke Fast-AGI is:<o:p>

exten => 123,1,Agi(http://ipaddress:port/script-name.agi) 

You can write an AGI Script in PHP, RUBY, Java, C, .NET, Java, PERL, Python, etc.

Asterisk-Java

Asterisk-Java is an open source programming library that mediates the Java and asterisk interaction. You can download stable Asterisk-Java from asterisk-java.org and put it in the same with your Java class.

Now create the Java application as follows and save it Day.java.

import org.asteriskjava.fastagi.*;
import java.util.Calendar;

public class Day extends BaseAgiScript{
   
private static int counter = 0;
   
public void service(AgiRequest request, AgiChannel channel)                 
throws AgiException {
       
try {
       
Calendar cal = Calendar.getInstance();  //Initiates today’s date   
    
String day = "Sunday";     
int dayNumber = cal.get(Calendar.DAY_OF_WEEK);
    
switch (dayNumber) {
            case 1:
                day  = "Sunday";
                break;
            case 2:
                day  = "Monday";
                break;         

          case 3:
                day  = "Tuesday";
                break;
            case 4:
                day  = "Wednesday";
                break;
            case 5:
                day  = "Thursday";
                break;
            case 6:
               day = "Friday";
                break;
            case 7:
                day = "Saturday";
                break;
       
} 
       setVariable("todaysDay",day);    
} 
catch (org.asteriskjava.fastagi.AgiHangupException e) {
            System.out.println("the user hanged up!!");        
}    
   
counter++;  

}  
}

Next, compile the Day.java as follows:

#java -cp asterisk-java.jar:. org.asteriskjava.fastagi.DefaultAgiServer  

After that, create a fastagi-mapping.properties file. And put the mapping between the Day class and day.agi like this:<o:p>

day.agi = Day

From the same directory, run the Java asterisk.<o:p>

# java -cp asterisk-java-0.3.1.jar:. org.asteriskjava.fastagi.DefaultAgiServer  

Then the system should be on listening mode as follows:<o:p>

INFO: Thread pool started.
Apr 17, 2014 3:30:07 PM org.asteriskjava.fastagi.DefaultAgiServer 
startupINFO: Listening on *:4573.  

Last but not least, your dial plan should look like:

[day]
exten => 1234,1,Answer()
                same => n,Agi(agi://localhost/day.agi) 
            ;the localhost should be replaced by the address to the script
                same => n,Playback(today&${todaysDay}) ;Playing back today's day
                same => n,Hangup()  

Assumptions

• You have installed Java on your AGI server.
• You have the days of the week sound files.

That is it; I have tried to put together how to use Java with Asterisk in a simple way. If you have any comments or suggestions, don’t hesitate to comment or contact me.

Thank you!