Getting Started

Asterisk is a powerful and highly flexible phone system.

Part of the great power of Asterisk is the ability to directly control it via an external application.

Asterisk-Java is a java library that provides an API to control and interact with Asterisk.

The easiest way to get started programming with Asterisk is via Activities which are new to Asterisk-Java 2.0.

The aim of Activities is to provide a high level abstracted API that lets you build complex telephony applications without requiring detailed knowledge of how the raw Asterisk interfaces work.

General Advice

Dont' use dial plan if you can avoid it! Dialplan is slow and hard to debug. Instead do everything in AGI. Our call center system (Noojee Contact) is a seriously complex asterisk application and we have about 10 lines of dialplan.

This is all of our dialplan.

[Handset]
; If the emergency number is dialed, don't muck about, just dial it!
exten => ${emergency_number},1,Dial(default/${emergency_number})
exten => ${emergency_number},n,Hangup()

exten => _X.,1,Verbose(1,${CONTEXT}: Received handset call for "${EXTEN}" )
exten => _X.,n,AGI(agi://127.0.0.1/route?targ=${EXTEN}&frcCtx=Pre-Handset)
exten => _X.,n,Verbose(1,${CONTEXT}: Returned from Handset Agi")
exten => _X.,n,Hangup

[inbound]
exten => _X.,1,Verbose(1,${CONTEXT}: Routing "${DID}" to route context Pre-inbound)
exten => _X.,n,AGI(agi://127.0.0.1/route?targ=${DID}&frcCtx=Pre-inbound)
exten => _X.,n,Verbose(1,${CONTEXT}: Returned from agi)
exten => _X.,n,Hangup

Everything else is done with AGI and Activities with a sprinkling of Actions and Event handling (although we are working to replace all of these with Activities).

Did you know you can originate directly into AGI? This is really powerful and eliminates the need for dialplan when doing AGI.

Configuring Asterisk

Before you can use Asterisk-Java your Asterisk server must be configured to allow Asterisk Manager Interface (AMI) connections.

To create an AMI connection point you need to configure:

/etc/asterisk/manager.conf

Enter the following configuration in the manager.conf file.

[myconnection]
secret=agoodpassword
deny=0.0.0.0/0.0.0.0
permit=1.1.1.1/32 
read = system,call,log,verbose,command,agent,user
write = system,call,log,verbose,command,agent,user

Replace the ip address 1.1.1.1 with the ip address of the client that will run your asterisk-java application.

Save manager.conf and restart Asterisk [asterisk will actually reload this file each time you attempt to make a manager connection].

Now create a java class file that implements AsteriskSettings

package com.mycompany.asterisk;

import org.asteriskjava.pbx.internal.asterisk.AsteriskSettings;

package org.asteriskjava.examples.activities;

import org.asteriskjava.pbx.DefaultAsteriskSettings;

public class ExamplesAsteriskSettings extends DefaultAsteriskSettings
{

	@Override
	public String getManagerPassword()
	{
		// this password MUST match the password (secret=) in manager.conf
		return "a good password";
	}

	@Override
	public String getManagerUsername()
	{
		// this MUST match the section header '[myconnection]' in manager.conf
        return "myconnection";
	}

	@Override
	public String getAsteriskIP()
	{
		// The IP address or FQDN of your Asterisk server.
        return "2.2.2.2";
	}

	@Override
	public String getAgiHost()
	{
		// The IP Address or FQDN of you asterisk-java application.
		return "1.1.1.1";
	}

}

You're now set to make your first call.

When your application starts you need to do a once off initialisation of the PBXFactory.

	/**
    	 * Initialise the PBX Factory. You need to implement your own AsteriskSettings class.
    	 */
        PBXFactory.init(new MyAsteriskSettings());
        
        /**
         * Activities utilise an agi entry point in your dial plan.
         * You can create your own entry point in dialplan or have
         * asterisk-java add it automatically as we do here.
         */
        AsteriskPBX asteriskPbx = (AsteriskPBX) PBXFactory.getActivePBX();
        asteriskPbx.createAgiEntryPoint();

Now that Asterisk-java is initialised and you are connected to the Asterisk server you are ready to dial.

    static private void dial()
    {
        try
        {
            PBX pbx = PBXFactory.getActivePBX();

            // We are going to dial from extension 100 to 5551234
            
            // The trunk MUST match the section header (e.g. [default]) that appears
            // in your /etc/asterisk/sip.d file (assuming you are using a SIP trunk).
            // The trunk is used to select which SIP trunk to dial through.
            Trunk trunk = pbx.buildTrunk("default");

            // We are going to dial from extension 100
            EndPoint from = pbx.buildEndPoint(TechType.SIP, "100");
            // Provide confirmation to the agent which no. we are dialing by
            // showing it on their handset.
            CallerID fromCallerID = pbx.buildCallerID("5551234", "Dialing");

            // The caller ID to display on the called parties phone.
            // On most systems the caller id name part won't display
            CallerID toCallerID = pbx.buildCallerID("5558100", "Asterisk Java is calling");
            // The party we are going to call.
            EndPoint to = pbx.buildEndPoint(TechType.SIP, trunk, "5551234");

	 // Now dial. This method won't return until the call is answered
	 // or the dial timeout is reached.
            DialActivity dial = pbx.dial(null, from, fromCallerID, to, toCallerID);

			 // We should have a live call here.			
            Call call = dial.getNewCall();
				
            Thread.sleep(20000);
				
			 // Bit tired now so time to hangup.
            pbx.hangup(call);
        }
        catch (PBXException | InterruptedException e)
        {
            System.out.println(e);
        }
 
    }