AGI Gosub Command Support in Asterisk-Java

Today, I had my first experience of contributing to an open-source project. The story is that a few weeks ago when I needed to execute an AGI Gosub command, I found out this command is not implemented in Asterisk-Java yet. Thus I decided to do some coding myself. I sent the result to the project’s JIRA by opening a new feature issue. Kindly, Stefan Reuter (funder of Asterisk-Java) appreciated the work and helped me to improve it. Finally, the new Gosub command added to the SVN and will be available in the 1.0.0 release.

The Gosub Command

This command has been added to Asterisk since 1.6 version. It lets you to call a subroutine in your dialplan from AGI script. You can also pass some optional arguments to the subroutine. Although an AGI developer may find this feature useful in several situations, personally I most benefit from gosub command in indirectly calling applications for whom no dedicated AGI command is available. An example is doing a “Queue” application as exec(“Queue”, …) may not give you all the expected behavior.

As an example of using this command, consider that you have this simple subroutine in your dialplan:

[inside]
exten => 190,1,AGI(agi://localhost/gosub.agi)

[sub-hello]
exten => s,1,NoOp(arg1: ${ARG1})
exten => s,n,NoOp(arg2: ${ARG2})
exten => s,n,Playback(hello-world)
exten => s,n,Return()

Then you can call this subroutine like this:

public class TestGosub extends BaseAgiScript
{
        public void service(AgiRequest request, AgiChannel channel) throws AgiException
        {
                answer();
                streamFile("silence/1");
                gosub("sub-hello", "s", "1", "a", "b");
                hangup();
        }
}

As it can be seen in the code, the first three arguments to the gosub method are the context, extension, and priority you want to call. The rest of parameters are optional arguments that will be available in the subroutine as variables ${ARG1}, ${ARG2}, etc.

Some Introductory Information

For people who are not familiar with Asterisk, I would like to add the following paragraphs.

Aboute Asterisk

Asterisk is an open-source software-based PBX system that lets you do telecommunications works on a Linux box. You can build auto-attendants, call centers, help desks, IVRs, VoIP providers etc with Asterisk.

About AGI

As a programmer, you can command at your will to an Asterisk box what to do. This feature is available through a standard language for talking between Asterisk and your program known as Asterisk Gateway Interface (AGI). This feature, along with another similar functionality known as Asterisk Manager Interface (AMI) makes a software developer capable of implementing almost any imaginable telecommunications application. An example application is one that reads out your new emails to you when you call it. Another application can be an IVR that dynamically adjusts its menu items based on user requirements.

About Asterisk-Java

Asterisk-Java is a library for doing AGI from Java programs. Personally, I think Asterisk-Java turns telecommunications application development into fun!