XEP-0152: Reachability Addresses

NOTICE: This document is currently within Last Call or under consideration by the XMPP Council for advancement to the next stage in the XSF standards process. The Last Call ends on . Please send your feedback to the standards@xmpp.org discussion list.

Table of Contents

1. Introduction

Sometimes it is desirable to augment instant messaging (IM) with another real-time communications medium, such as a voice conversation conducted over the traditional public switched telephone network (PSTN) or Voice over Internet Protocol (VoIP) applications. In order to facilitate this functionality, a user needs to advertise the address(es) at which they can be reached. There are several possible ways to do this:

• Publish the address(es) in the user's vCard (see vcard-temp (XEP-0054) [1] and vCard4 over XMPP (XEP-0292) [2]); this is convenient, but is not very dynamic (e.g., reachability addresses might change when the user moves to a new conference room in an office building).

• Send the address(es) within a <presence/> stanza; this option is described in the Presence Transport section of this document and is consistent with RFC 6121 [3] since reachability is one aspect of a user's availability for communication.

• Send address(es) to the appropriate Publish-Subscribe (XEP-0060) [4] node; this option is described in the PEP Transport section of this document but might not be available at all service providers.

This document defines methods for publishing addresses at which a user can be reached temporarily, as opposed to semi-permanent addresses of the kind that are more appropriately communicated in a user's vCard. We illustrate this usage through the scenario of a user sending a reachability address upon entering a physical conference room and then sending an updated notification (without a reachability address) upon leaving the conference room. Similar scenarios might apply when an XMPP implementation is used with technologies such as WebRTC and in deployments of the combined use of SIP and XMPP ("CUSAX"; ).

2. Requirements

This document addresses the following requirements:

• Enable clients to dynamically publish reachability addresses.
• Minimize network traffic.

3. Data Format

The following is an example of the data format for reachability addresses:

Example 1. Data Format for Reachability Addresses

<reach xmlns='urn:xmpp:reach:0'>
  <addr uri='tel:+1-303-555-1212'/>
  <addr uri='sip:room123@example.com'/>
</reach>
  

When publishing reachability addresses, the <reach/> element MUST contain at least one <addr/> element. Each <addr/> element MUST possess a 'uri' attribute, whose value MUST be the Uniform Resource Identifier (RFC 3986 [5]) or Internationalized Resource Identifier (RFC 3987 [6]) of an alternate communications method for reaching the user.

The <addr/> element MAY contain one or more <desc/> children whose XML character data is a natural-language description of the address; this element SHOULD possess an 'xml:lang' attribute whose value is a language tag that conforms to RFC 4646 [7] (although the default language MAY be specified at the stanza level; see RFC 6120 [8]). In order to preserve bandwidth, the <desc/> element SHOULD NOT be included when sending reachability data via presence broadcast, but MAY be included when using directed presence or the personal eventing protocol.

Example 2. Reachability Addresses With Descriptions

<reach xmlns='urn:xmpp:reach:0'>
  <addr uri='tel:+1-303-555-1212'>
    <desc xml:lang='en'>Conference room phone</desc>
  </addr>
  <addr uri='sip:room123@example.com'>
    <desc xml:lang='en'>In-room video system</desc>
  </addr>
</reach>
  

4. Data Transport

This document specifies two methods of advertising reachability addresses:

• Presence
• Personal Eventing Protocol (XEP-0163) [9] (PEP)

This document does not recommend one transport method over the other.

In addition, a contact MAY request a user's reachability addresses in an XMPP <iq/> stanza of type "get" and a user MAY send reachability addresses in an XMPP <message/> stanza. However, the presence and PEP transport methods are preferred.

<presence from='romeo@example.com/mobile'>
  <reach xmlns='urn:xmpp:reach:0'>
    <addr uri='tel:+1-303-555-1212'/>
    <addr uri='sip:room123@example.com'/>
  </reach>
</presence>
    

<presence from='romeo@montague.net/mobile' to='juliet@capulet.com'>
  <reach xmlns='urn:xmpp:reach:0'>
    <addr uri='tel:+1-303-555-1212'/>
    <addr uri='sip:room123@example.com'/>
  </reach>
</presence>
    

<presence from='romeo@example.com/mobile'/>
    

<iq type='set'
    from='romeo@example.com'
    to='pubsub.shakespeare.example'
    id='publish1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:reach:0'>
      <item id='a1s2d3f4g5h6bjeh936'>
        <reach xmlns='urn:xmpp:reach:0'>
          <addr uri='tel:+1-303-555-1212'>
            <desc xml:lang='en'>Conference room phone</desc>
          </addr>
          <addr uri='sip:room123@example.com'>
            <desc xml:lang='en'>In-room video system</desc>
          </addr>
        </reach>
      </item>
    </publish>
  </pubsub>
</iq>
    

<message from='pubsub.shakespeare.lit'
         to='juliet@capulet.com'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='urn:xmpp:reach:0'>
      <item id='a1s2d3f4g5h6bjeh936'>
        <reach xmlns='urn:xmpp:reach:0'>
          <addr uri='tel:+1-303-555-1212'>
            <desc xml:lang='en'>Conference room phone</desc>
          </addr>
          <addr uri='sip:room123@example.com'>
            <desc xml:lang='en'>In-room video system</desc>
          </addr>
        </reach>
      </item>
    </items>
  </event>
</message>
    

<iq type='set'
    from='romeo@example.com'
    to='pubsub.shakespeare.example'
    id='publish1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:reach:0'>
      <item id='a1s2d3f4g5h6bjeh936'>
        <reach xmlns='urn:xmpp:reach:0'/>
      </item>
    </publish>
  </pubsub>
</iq>
    

5. Determining Support

If an entity supports reachability addresses, it MUST advertise that fact by returning a feature of "urn:xmpp:reach:0" (see Namespace Versioning regarding the possibility of incrementing the version number) in response to a Service Discovery (XEP-0030) [10] information request.

Example 9. Service Discovery Information Request

<iq from='juliet@capulet.com/balcony' 
    id='disco1'
    to='romeo@montague.net/orchard'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  

Example 10. Service Discovery Information Response

<iq from='romeo@montague.net/orchard' 
    id='disco1'
    to='juliet@capulet.com/balcony' 
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:reach:0'/>
  </query>
</iq>
  

In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in Entity Capabilities (XEP-0115) [11]. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

6. Implementation Notes

To preserve network bandwidth, the sender ought not include the <desc/> element unless that information is deemed necessary to enable communication.

A recipient ought to attempt communications with reachability addresses in the order that the <addr/> elements appear within the <reach/> element.

7. Internationalization Considerations

If included, the <desc/> element SHOULD possess an 'xml:lang' attribute specifying the language of the human-readable descriptive text for a particular address.

8. Security Considerations

Security considerations for XMPP presence and PEP publication are described in RFC 6120, RFC 6121, XEP-0060, and XEP-0163.

9. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [12].

10. XMPP Registrar Considerations

11. XML Schema

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:reach:0'
    xmlns='urn:xmpp:reach:0'
    elementFormDefault='qualified'>

  <xs:element name='reach'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='addr' 
                    minOccurs='0'
                    maxOccurs='unbounded'
                    type='addrElementType'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:complexType name='addrElementType'>
    <xs:sequence>
      <xs:element name='desc' 
                  minOccurs='0'
                  maxOccurs='unbounded'
                  type='xs:string'/>
    </xs:sequence>
    <xs:attribute name='uri' use='required' type='xs:anyURI'/>
  </xs:complexType>

</xs:schema>
  

Appendices

Appendix A: Document Information

Series: XEP
Number: 0152
Publisher: XMPP Standards Foundation
Status: Proposed
Type: Standards Track
Version: 0.6
Last Updated: 2013-12-02
Approving Body: XMPP Council
Dependencies: XMPP Core, XMPP IM
Supersedes: None
Superseded By: None
Short Name: reach
Source Control: HTML
This document in other formats: XML  PDF

Appendix B: Author Information

Appendix C: Legal Notices

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

END