# Asterisk Project : Jabber in Asterisk

Added by mdavenport , edited by mdavenport on Aug 08, 2012

This information applies to Asterisk 10 and earlier versions. XMPP Support for Asterisk 11 has been completely rewritten

XMPP (Jabber) is an XML based protocol primarily for presence and messaging. It is an open standard and there are several open server implementations, such as ejabberd, jabberd(2), openfire, and others, as well as several open source clients, Psi, gajim, gaim etc. XMPP differs from other IM applications as it is immensly extendable. This allows us to easily integrate Asterisk with XMPP. The Asterisk XMPP Interface is provided by res_jabber.so.

`res_jabber` allows for Asterisk to connect to any XMPP (Jabber) server and is also used to provide the connection interface for `chan_jingle` and `chan_gtalk`.

Functions (`JABBER_STATUS`, `JABBER_RECEIVE`) and applications (`JabberSend`) are exposed to the dialplan.

You'll find examples of how to use these functions/applications hereafter. We assume that 'asterisk-xmpp' is properly configured in `jabber.conf`.

##### `JabberSend`

`JabberSend` sends an XMPP message to a buddy. Example:

extensions.ael

    context default {
    	_XXXX => {
    	      JabberSend(asterisk-xmpp,buddy@gmail.com,${CALLERID(name)} is calling ${EXTEN});
    	      Dial(SIP/${EXTEN}, 30);
    	      Hangup();
    	}
    }

##### `JABBER_STATUS`

As of Asterisk 1.6.0, the corresponding application `JabberStatus` is still available, but marked as deprecated in favor of this function.

`JABBER_STATUS` stores the status of a buddy in a dialplan variable for further use. Here is an AEL example of how to use it:

extensions.ael

    1234 => {
    	Set(STATUS=${JABBER_STATUS(asterisk-xmpp,buddy@gmail.com)});
    	if (${STATUS}=1) {
    		NoOp(User is online and active, ring his Gtalk client.);
    		Dial(Gtalk/asterisk-xmpp/buddy@gmail.com);
    	} else {
    		NoOp(Prefer the SIP phone);
    		Dial(SIP/1234);
    	}
    }

##### `JABBER_RECEIVE`

`JABBER_RECEIVE` waits (up to X seconds) for a XMPP message and returns its content. Used along with `JabberSend` (or `SendText`, provided it's implemented in the corresponding channel type), `JABBER_RECEIVE` helps Asterisk interact with users while calls flow through the dialplan.

`JABBER_RECEIVE`/`JabberSend` are not tied to the XMPP media modules `chan_gtalk` and `chan_jingle`, and can be used anywhere in the dialplan. In the following example, calls targeted to extension 1234 (be it accessed from SIP, DAHDI or whatever channel type) are controlled by user bob@domain.com. Asterisk notifies him that a call is coming, and asks him to take an action. This dialog takes place over an XMPP chat.

extensions.ael

    context from-ext {
    	1234 => {
    		Answer();
    		JabberSend(asterisk-xmpp,bob@jabber.org,Call from $CALLERID(num) - choose an option to process the call);
    		JabberSend(asterisk-xmpp,bob@jabber.org,1 : forward to cellphone);
    		JabberSend(asterisk-xmpp,bob@jabber.org,2 : forward to work phone);
    		JabberSend(asterisk-xmpp,bob@jabber.org,Default action : forward to your voicemail);
    		Set(OPTION=${JABBER_RECEIVE(asterisk-xmpp,bob@jabber.org,20)});
    		switch (${OPTION}) {
    			case 1:
    				JabberSend(asterisk-xmpp,bob@jabber.org,(Calling cellphone...);
    				Dial(SIP/987654321);
    				break;
    			case 2:
    				JabberSend(asterisk-xmpp,bob@jabber.org,(Calling workphone...);
    				Dial(SIP/${EXTEN});
    				break;
    			default:
    				Voicemail(${EXTEN}|u)
    		}
    	}
    }

When calling from a GoogleTalk or Jingle client, the `CALLERID(name)` is set to the XMPP id of the caller (i.e. his JID). In the following example, Asterisk chats back with the caller identified by the caller id. We also take advantage of the `SendText` implementation in `chan_gtalk` (available in `chan_jingle`, and `chan_sip` as well), to allow the caller to establish SIP calls from his GoogleTalk client:

extensions.ael

    context gtalk-in {
    	s => {
    	  NoOp(Caller id : ${CALLERID(all)});
    	  Answer();
    	  SendText(Please enter the number you wish to call);
    	  Set(NEWEXTEN=${JABBER_RECEIVE(asterisk-xmpp,${CALLERID(name)})});
    	  SendText(Calling ${NEWEXTEN} ...);
    	  Dial(SIP/${NEWEXTEN);
    	  Hangup();
    	}
    }

The maintainer of `res_jabber` is Philippe Sultan <philippe.sultan@gmail.com>.