diff options
Diffstat (limited to 'doc/jabber.txt')
| -rw-r--r-- | doc/jabber.txt | 120 |
1 files changed, 106 insertions, 14 deletions
diff --git a/doc/jabber.txt b/doc/jabber.txt index ca3e0f528..a8f4a9361 100644 --- a/doc/jabber.txt +++ b/doc/jabber.txt @@ -1,15 +1,107 @@ -(res_jabber is very experimental!) - -Jabber(xmpp) is an xml based protocol primarily for presence and messaging. +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), wildfire, and many others, as well as several open source -clients, Psi, gajim, gaim etc. Jabber differs from other IM applications as it -is immensly extendable. This allows us to easily integrate Asterisk with -jabber. The Asterisk Jabber Interface is provided by res_jabber.so. res_jabber -allows for Asterisk to connect to any jabber server via the standard client -protocol or also as a simple client. Several simple functions are exposed to -the dial plan, jabberstatus, jabbersend, and soon jabberrecv. res_jabber is also used -to provide the connection interface for chan_jingle. - -The maintainer of res_jabber is Matthew O'Gorman <mogorman@digium.com> or -mog_work on irc or (preferred) mogorman@astjab.org over jabber. +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>. |