This document describes a protocol for phone and instant messaging integration. It will eventually be turned into a JEP and submitted to the JSF once implementation details have been worked out.
This JEP describes a protocol for exposing telephony features through XMPP. This is not a VOIP/soft-phone protocol, but instead a method for integrating instant messaging with existing phone systems (eg Asterisk).
The functionality falls into three major areas:
The current implementation of this protocol specifically targets Asterisk and its available feature set. However, the final JEP will be phone system agnostic with a mechanism for discovering which features are available for each integration.
A user's presence is updated when on a phone call. The Wildfire/Asterisk implementation will update the user's presence automatically by adding the following packet extension to the user's presence:
<phone-status xmlns="http://jivesoftware.com/xmlns/phone" status="ON_PHONE" >
Adding a packet extension to presence is not the generally accepted method for handling extended presence information in XMPP. Instead, pubsub is used such as with JEP-0108: User Activity. However, Wildfire does not currently support pubsub. When this protocol is turned into an official JEP, pubsub will likely be required so that we can publish this extended presence information in the "correct" way.
Wildfire can also be configured to change the user's availability to "Away -- on the phone" when the user is on a call (in addition to the packet extension). This is useful when interacting with clients that don't understand the extended presence information or when using transports to other IM networks where extended presence information is not available.
Events are sent to the user when their phone is ringing, when a call ends, etc. As with presence, pubsub should probably be the mechanism used for sending this information, but message packets are used to send events for the time being.
The following packet extension will be sent to convey phone events:
<phone-event status="RING" device="SIP/6131" id="a7f2ag">
<callerID>5037061376</callerID>
</phone-event>
The current event statuses are RING, DIALED, ON_PHONE, HANG_UP. The device is the phone device that the event was generated for. In this case, it's a SIP phone. Users may have several devices, such as when their phone rings for their personal number and for a sales line. The id attribute is a unique ID for the phone call. For a normal call events received for the same id will include; RING or DIALED, ON_PHONE, and HANG_UP.
Information contained inside phone events is still evolving. At the moment, callerID is optionally available for RING events. In the future, additional information will be available to aid in screen pops. For example, based on the callerID, the system may do a CRM database lookup to find the person's name, company, avatar, etc.
Actions are sent by the client to perform tasks such as dialing, checking for messages, etc. Actions are sent as IQ's (type set), as with the following child stanza:
<phone-action xmlns="http://jivesoftware.com/xmlns/phone" type="DIAL">
<extension>5035555555</extension>
</phone-action>
Currently supported types are DIAL and FORWARD.
In most implementations, issuing a dial command will cause the user's phone to ring. Once the user picks up, the specified extension will be dialed.
Dialing can also be performed by jid too. The jid must be dialed must be mapped on the server to an extension
<phone-action type="DIAL">
<jid>andrew@jivesoftware.com</jid>
</phone-action>
Issuing a action wth a type FORWARD should transfer a call that has already been established to a third party. The FORWARD type requires an extension or jid child element
<phone-action xmlns="http://jivesoftware.com/xmlns/phone" type="FORWARD">
<extension>5035555555</extension>
</phone-action>
To discover the phone component a disco items query needs to be sent to the server:
<iq type='get' from='test@jivesoftware.com' to='jivesoftware.com' id='items1'> <query xmlns='http/jabber.org/protocol/disco#items'/> </iq>
The jid item with the name phone should be used. If no item named phone is present, the server does not support this feature
<iq from="jivesoftware.com" type="result" to="test@jivesoftware.com/Psi" id="items1" >
<query xmlns="http/jabber.org/protocol/disco#items">
<item name="Public Chatrooms" jid="conference.jivesoftware.com" />
<item name="phone" jid="phone.jivesoftware.com" />
<item name="User Search" jid="search.jivesoftware.com" />
</query>
</iq>
To determine whether a specific user has support the phone service, and info disco query must be sent to the phone component. The username must be set as the node attribute on the query.
<iq type='get'
from='andrew@jivesoftware.com/home'
to='phone.jivesoftware.com'
id='info3'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='andrew'/>
</iq>
If the user is supported you will receive a reponse that contains the feature http://jivesoftware.com/phone
<iq type='result'
from='phone.jivesoftware.com'
to='andrew@jivesoftware.com'
id='info3'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='andrew'>
<identity category='directory'
type='phone'
name='phone'>
<feature var='http://jabber.org/protocol/disco#info'/>
<feature var='http://jivesoftware.com/phone'/>
</query>
</iq>
If the user is does not have support the result will not contain the http://jivesoftware.com/phone feature:
<iq type='result'
from='phone.jivesoftware.com'
to='andrew@jivesoftware.com'
id='info3'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='andrew'>
<identity category='directory'
type='phone'
name='phone'>
<feature var='http://jabber.org/protocol/disco#info'/>
</query>
</iq>