XMPP (Jabber) is an xml based protocol primarily for presence and messaging.
It is an open standard and there are several open server implementations,
ejabberd, jabberd(2), openfire, and many 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 :

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

**** JABBER_STATUS ****

Note : as of version 1.6, 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 :

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.

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 :

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>.
