Asterisk-IM Plugin Readme

Prerequesites

Asterisk installed with the Manager API enabled.

Installation

  1. Copy the phone plugin jar file to the OPENFIRE_HOME/plugins directory.
  2. Restart Openfire.
  3. Configure the asterisk manager connection on the PBX Integration page.

Configuration

Once the plugin is configured, Asterisk-IM can be configured by clicking on the "Asterisk-IM" tab in the Openfire. Required field on the admin page will be marked by an asterisk. You will see the following fields on the admin tool:

Client API

The client API first requires that the Asterisk-IM server plugin is installed. To initialize the client do the following:

XMPPConnection conn = new XMPPConnection("myserver.foo.com", "user", "password");
PhoneClient client = new PhoneClient(conn);
Note that the XMPPConnection passed in must be authenticated. If an unauthenticated connection is passed in an exception will be thrown.

Phone Events

Phone events are notifications from the server that the PBX is going through a state change with one of the current users' devices. Phone events are XMPP packets with a child element phone-event that belongs to the namespace http://jivesoftware.com/xmlns/phone. Phone events are XML elements that contain a type attribute describing what kind of event is being dispatched. They can also contain an attribute device which tells which device (line) the user is receiving a call on. This is useful if the user has more than one telephone line.

Current Phone Events

Event Packet Class Children
ON_PHONE
Signifies that the user has answered a call.
Presence packet with an "away" presence. org.jivesoftware.phone.client.AnswerEvent Contains a callerID child element containg the caller id of the caller.
HANG_UP
Signifies that the user has hung up the phone.
Presence packet that sets the user's presence back to its previous presence before the call. org.jivesoftware.phone.client.HangUpEvent None
RING
Signifies that the user's phone is ringing.
Message Packet org.jivesoftware.phone.client.RingingEvent Can contains a callerID child element containing the phone number of the caller. Can contains a callerIDName child element containing the name of the caller.
DIALED
Signifies that the user has dialed a number.
Message Packet org.jivesoftware.phone.client.DialedEvent Contains a callerID child element containg the caller id of the caller.

To listen for events, register an event listener with PhoneClient.addEventListener(..) method:

PhoneClient client = new PhoneClient(conn);
client.addEventListener(new BasePhoneEventListener() {

   // Override the handleRing event to see when we are receiving a call
   public void handleRing(RingEvent event) {
      log.info("receiving a call from " + event.getCallerID());
   }

});

Phone Actions

Phone actions are requests from the client to perform tasks such as dialing an number. They are implemented as IQ packets with child node of phone-action that belongs to the namespace http://jivesoftware.com/xmlns/phone. Phone actions have a type attribute which determines what action to be performed (ie DIAL, FORWARD).

Current Phone Actions:

Action Children
DIAL
Used to dial an extension (or full phone number).
Contains an element extension which contains the number to be dialed, or an element jid which contains the jid of the person to dial. If jid is used the jid must be registered with asterisk-im on the same server.
FORWARD
Forwards a call to another extension.
Contains an element extension which contains the number to be dialed, or an element jid which contains the jid of the person to dial. If jid is used the jid must be registered with asterisk-im on the same server.


Links

The Asterisk-IM support page.
The Openfire home page.
The Asterisk PBX Home page.
The Asterisk-Java API. Asterisk-IM is implemented using this.
The VOIP wiki, a great Asterisk resource.