JEP-0130: Waiting Lists

This JEP defines an XMPP protocol extension that enables a user to add a non-IM user to a "waiting list" and be informed when the contact creates an IM account.

WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.

JEP Information

Status: Experimental
Type: Standards Track
Number: 0130
Version: 0.3
Last Updated: 2004-09-27
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, XMPP IM
Supersedes: None
Superseded By: None
Short Name: waitlist

Author Information

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

Yehezkel Dallal

Email: yehezkeld@followap.com

Alexandre Nolle

Email: anolle@francetelecom.com

Jean-Louis Seguineau

Email: jean-louis.seguineau@antepo.com
JID: jlseguineau@im.antepo.com

Mark Troyer

Email: mtroyer@jabber.com
JID: mtroyer@corp.jabber.com

Legal Notice

This Jabber Enhancement Proposal is copyright 1999 - 2005 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

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

Table of Contents

1. Introduction
2. Glossary
3. Requirements
4. Use Cases
4.1. IM User Retrieves Current Waiting List
4.1.1. Primary Flow
4.1.2. Alternate Flows
4.2. IM User Adds Contact to Waiting List
4.2.1. Primary Flow
4.2.2. Alternate Flows
4.3. IM User Removes Contact from Waiting List
4.3.1. Primary Flow
4.3.2. Alternate Flows
5. Protocol
5.1. IM User Interaction With WaitingListService
5.1.1. IM User Retrieves Current Waiting List
5.1.2. IM User Adds Contact to Waiting List
5.1.3. IM User Removes Contact from Waiting List
5.2. WaitingListService Interaction With InteropPartners
5.2.1. ServiceProvider's WaitingListService Retrieves Current Waiting List
5.2.2. ServiceProvider's WaitingListService Adds Contact to Waiting List
5.2.3. ServiceProvider's WaitingListService Removes Contact from Waiting List
6. Implementation Notes
7. Security Considerations
8. IANA Considerations
9. Jabber Registrar Considerations
10. XML Schema
Notes
Revision History

1. Introduction

An IM user may want to be informed when a contact creates an IM account. If the user knows some information about the contact (e.g., a phone number or email address), the user's service can use that information to place the contact on a "waiting list", then inform the user when the contact creates an IM account. This document defines an extension to XMPP Core [1] and XMPP IM [2] that enables such "waiting list" functionality, including the ability to add contacts on other domains if service providers agree to interoperate (e.g., to add a contact who uses a different mobile telephony service provider).

Note: The protocol defined herein is currently in use at several large service providers in Europe. Others are welcome to use the protocol.

2. Glossary

Table 1: Terms Used

Term Definition
Contact A person with whom an IM User seeks to communicate, identified by a URI such as tel:phone-number (see RFC 3966 [3]) or mailto:email-address (see RFC 2368 [4]).
IM User Any Customer who has registered for instant messaging services.
InteropPartner Any company that agrees to interoperate using the protocol defined herein.
JID The unique identifier of an IM User in the XMPP protocol. Outside the context of an IM session, a JID is of the form <user@domain> ("bare JID"); within the context of an IM session, a JID is of the form <user@domain/resource> ("full JID").
ServiceProvider A company that provides telephony or email services to a Customer.
URI A Uniform Resource Identifier as defined in RFC 3986 [5]. Specific URI schemes that may be useful in this specification incldue 'tel:', 'mailto:', and 'sip:', but any URI scheme may be used.
Waiting List A list of contacts whom an entity (IM User or ServiceProvider) is waiting to hear about regarding their status as instant messaging users.
WaitingListService An XMPP service that maintains waiting lists for IM Users and/or InteropPartners.

3. Requirements

This protocol MUST enable an IM user to:

  1. Request the user's current waiting list
  2. Add a contact to a local waiting list (based on some URI associated with the contact)
  3. Receive notification from a local waiting list service if the contact has (or subsequently creates) an IM account
  4. Remove a contact from the waiting list

In addition, this protocol MUST enable a service provider to:

  1. Request the service's current waiting list
  2. Add a contact to a waiting list at an interoperability partner (based on some URI associated with the contact)
  3. Receive notification from the interoperability partner if the contact has (or subsequently creates) an IM account
  4. Remove a contact from the waiting list

4. Use Cases

4.1 IM User Retrieves Current Waiting List

Before adding or removing contacts from its waiting list, an IM User SHOULD retrieve its current waiting list. The activity flow is as follows:

4.1.1 Primary Flow

  1. IM User discovers WaitingListService hosted by ServiceProvider [A1]; it is RECOMMENDED to do this immediately after logging in.
  2. IM User requests current Waiting List from WaitingListService.
  3. WaitingListService returns Waiting List to IM User, including any items for which JIDs have been discovered [A2].

4.1.2 Alternate Flows

  1. ServiceProvider does not host a WaitingListService:
    1. Use Case Ends unsuccessfully.
  2. IM User does not have a Waiting List:
    1. WaitingListService returns "Not Found" error to IM User.
    2. Use Case Ends unsuccessfully.

4.2 IM User Adds Contact to Waiting List

An IM User may know a Contact's URI but not the Contact's JID. In order to subscribe to the Contact's presence or otherwise communicate with the Contact over an instant messaging system, the IM user first needs to discover the Contact's JID based on the Contact's URI phone number or email address. However, the Contact may not yet have an IM account. Because the IM User may therefore need to wait until the Contact creates an account, the IM User needs to add the Contact to a "waiting list". The activity flow is as follows:

4.2.1 Primary Flow

  1. IM User SHOULD first complete use case for "IM User Retrieves Current Waiting List".
  2. IM User requests addition of Contact to Waiting List based on Contact's URI.
  3. WaitingListService determines that the URI scheme is supported [A1].
  4. WaitingListService determines that the information provided is a valid URI for that URI scheme [A2].
  5. WaitingListService acknowledges addition of Contact to IM User's Waiting List.
  6. WaitingListService determines that Contact's URI does not belong to a person served by ServiceProvider [A3].
  7. WaitingListService discovers WaitingListServices hosted by one or more InteropPartners.
  8. WaitingListService queries one or more InteropPartner's WaitingListServices for JID associated with URI.
  9. InteropPartner's WaitingListService determines that Contact's URI belongs to a person served by that partner [A4].
  10. InteropPartner's WaitingListService determines that Contact is an IM User [A5].
  11. OPTIONALLY, WaitingListService requires that Contact approves request.
  12. InteropPartner's WaitingListService informs ServiceProvider's WaitingListService of JID associated with Contact's URI. [A6]
  13. ServiceProvider's WaitingListService informs IM User of Contact's JID. [A8]
  14. Use Case Ends.

4.2.2 Alternate Flows

  1. The URI scheme is not supported:
    1. WaitingListService sends "Bad Request" error to IM User.
    2. Use Case Ends unsuccessfully.
  2. The information provided is not a valid URI:
    1. WaitingListService sends "Bad Request" or "Remote Server Error" error to IM User.
    2. Use Case Ends unsuccessfully.
  3. URI belongs to person served by ServiceProvider:
    1. WaitingListService determines that Contact is an IM User registered with ServiceProvider [A7].
    2. OPTIONALLY, WaitingListService requires that Contact approves request.
    3. WaitingListService informs IM User of Contact's JID.
    4. Use Case Ends.
  4. URI does not belong to a person served by InteropPartner:
    1. InteropPartner sends "Not Found" error to WaitingListService.
    2. If all InteropPartners queried return "Not Found" error, WaitingListService sends "Not Found" error (or local equivalent) to IM User.
    3. Use Case Ends unsuccessfully.
  5. Contact is not an IM User registered with InteropPartner:
    1. InteropPartner records WaitingListService's request for JID associated with URI.
    2. OPTIONALLY, InteropPartner invites Contact to register as an IM User.
    3. Contact registers.
    4. InteropPartner informs Service Provider's WaitingListService of JID associated with Contact's URI.
    5. ServiceProvider's WaitingListService informs all IM Users who requested JID associated with Contact's URI.
    6. Use Case Ends.
  6. Contact denies request:
    1. InteropPartner's WaitingListService sends "Not Authorized" error to ServiceProvider's WaitingListService.
    2. ServiceProvider's WaitingListService sends "Not Authorized" error (or local equivalent) to IM User.
    3. Use Case Ends unsuccessfully.
  7. Contact is not an IM User registered with ServiceProvider:
    1. WaitingListService records IM User's request for JID associated with URI.
    2. OPTIONALLY, WaitingListService invites Contact to register as an IM User.
    3. Contact registers.
    4. WaitingListService informs all IM Users who requested JID associated with Contact's URI.
    5. Use Case Ends.
  8. Contact's URI is not handled by any ServiceProvider:
    1. WaitingListService informs all IM Users who requested JID associated with Contact's URI that no InteropPartner services Contact's URI.
    2. Use Case Ends.

4.3 IM User Removes Contact from Waiting List

An IM User may want to remove an item from its waiting list.

4.3.1 Primary Flow

  1. IM User sends removal request to WaitingListService.
  2. WaitingListService removes IM User's request for JID associated with URI.
  3. WaitingListService informs IM User of successful removal [A1].
  4. WaitingListService sends removal request to appropriate InteropPartner's WaitingListService [A2].
  5. InteropPartner's WaitingListService determines that URI belongs to a person served by that partner.
  6. InteropPartner's WaitingListService removes ServiceProvider's WaitingListService's request for JID.
  7. InteropPartner's WaitingListService informs ServiceProvider's WaitingListService of successful removal.
  8. Use Case Ends.

4.3.2 Alternate Flows

  1. IM User never requested JID associated with URI:
    1. WaitingListService sends "Not Found" error to IM User.
    2. Use Case Ends.
  2. Contact URI is served by WaitingListService or IM User was not the only person who requested the JID:
    1. Use Case Ends.

5. Protocol

5.1 IM User Interaction With WaitingListService

This section of the document is provided for the sake of domains that implement XMPP as their local protocol; domains that implement another protocol will use their service-specific protocol to complete the user-to-domain interaction. Support for the protocol defined in this section is NOT REQUIRED for services that do not implement XMPP as their local protocol.

5.1.1 IM User Retrieves Current Waiting List

It is RECOMMENDED for an IM User's client to retrieve the waiting list immediately after logging in. However, first it must discover its local WaitingListService.

Example 1. IM User Discovers WaitingListService by Sending Agents Request to its Server

<iq type='get' id='agent1'>
  <query xmlns='jabber:iq:agents'/>
</iq>

Example 2. Server Returns Address of its WaitingListService

<iq type='result' id='agent1'>
  <query xmlns='jabber:iq:agents'>
    ...
    <agent jid='waitlist.service-provider.com'>
      <name>Waiting List Service</name>
      <service>waitinglist</service>
    </agent>
    ...
  </query>
</iq>

Example 3. IM User Discovers WaitingListService by Sending Service Discovery Request to its Server

<iq type='get' id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>

Example 4. Server Returns Address of its WaitingListService

<iq type='result' id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    ...
    <item jid='waitlist.service-provider.com'
          name='Waiting List Service'/>
    ...
  </query>
</iq>

Example 5. IM User Queries WaitingListService for Detailed Information

<iq type='get'
    from='user@service-provider.com/resource'
    to='waitlist.service-provider.com'
    id='disco2'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

The WaitingListService SHOULD return detailed information about the service it provides, including URI schemes supported.

Example 6. WaitingListService Returns Detailed Information

<iq type='result'
    from='waitlist.service-provider.com'
    to='user@service-provider.com/resource'
    id='disco2'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity category='directory'
              type='waitinglist'/>
    <feature var='http://jabber.org/protocol/waitinglist'/>
    <feature var='http://jabber.org/protocol/waitinglist/schemes/mailto'/>
    <feature var='http://jabber.org/protocol/waitinglist/schemes/tel'/>
  </query>
</iq>

Once an IM User has discovered the WaitingListService, the user's client SHOULD request its current waiting list:

Example 7. IM User Requests its Current Waiting List

<iq type='get'
    from='user@service-provider.com/resource'
    to='waitlist.service-provider.com'
    id='request1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'/>
</iq>

Upon request, the WaitingListService MUST return the current waiting list to the IM User:

Example 8. WaitingListService Returns Waiting List to IM User

<iq type='result'
    from='waitlist.service-provider.com'
    to='user@service-provider.com/resource'
    id='request1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='12345'>
      <uri scheme='tel'>3033083282</uri>
      <name>PSA</name>
    </item>
    <item id='23456'>
      <uri scheme='mailto'>editor@jabber.org</uri>
      <name>JEP Editor</name>
    </item>
  </query>
</iq>

Each ItemID MUST be unique within the scope of the client's waiting list items. The value of the ItemID is an opaque string; an implementation MAY assign semantic meaning to the ItemID (e.g., id="John Smith (mobile)" rather than id="12345"), but such meaning is implementation-specific and outside the scope of the waiting list protocol itself. The user MAY include a <name/> element containing a natural-language name for the contact.

The Waiting List MAY contain an item for which a JID has been discovered.

Example 9. IM User Asks for its Waiting List including Newly Discovered JID

<iq type='get'
    from='user@service-provider.com/resource'
    to='waitlist.service-provider.com'
    id='request1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'/>
</iq>

<iq type='result'
    from='waitlist.service-provider.com'
    to='user@service-provider.com/resource'
    id='jidask1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='12345' jid='stpeter@jabber.org'>
      <uri scheme='tel'>3033083282</uri>
      <name>PSA</name>
    </item>
    <item id='23456'>
      <uri scheme='mailto'>editor@jabber.org</uri>
      <name>JEP Editor</name>
    </item>
  </query>
</iq>

5.1.2 IM User Adds Contact to Waiting List

Once an IM User's client has discovered the WaitingListService and requested the user's waiting list, the user can add Contacts to the waiting list based on the Contact's URI. (Note: This JEP uses the example of phone numbers via the 'tel' URI scheme, but the same rules apply to waiting list items based on email addresses or other URI schemes.)

Example 10. IM User Requests Addition of Contact to Waiting List

<iq type='set'
    to='waitlist.service-provider.com'
    id='waitinglist1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item>
      <uri scheme='tel'>contact-number</uri>
      <name>contact-name</name>
    </item>
  </query>
</iq>

If the IM User provided an invalid Phone Number (e.g., too many digits) or Email Address (e.g., no '@' character), WaitingListService sends "Not Acceptable" error to IM User.

Example 11. WaitingListService Returns "Not Acceptable" Error to IM User

<iq type='error'
    from='waitlist.service-provider.com'
    to='user@service-provider.com/resource'
    id='waitinglist1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item>
      <uri scheme='tel'>+1234563033083283</uri>
      <name>contact-name</name>
    </item>
  </query>
  <error code='406' type='modify'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

(For information about error syntax, refer to Error Condition Mappings [6].)

If the IM User included a JID in the request, WaitingListService sends "Bad Request" error to IM User. (Note: A WaitingListService MUST NOT return a non-XMPP URI to an IM User based on the Contact's JID; see Security Considerations.)

Example 12. WaitingListService Returns "Bad Request" Error to IM User

<iq type='error'
    from='waitlist.service-provider.com'
    to='user@service-provider.com/resource'
    id='waitinglist1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item jid='some-jid'>
      <uri scheme='tel'>contact-number</uri>
      <name>contact-name</name>
    </item>
  </query>
  <error code='400' type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

If neither of the previous two errors was generated, WaitingListService informs IM User that request was successfully received, including unique ID number for the new waiting list item.

Example 13. WaitingListService Informs IM User that Request was Received

<iq type='result'
    from='waitlist.service-provider.com'
    to='user@service-provider.com/resource'
    id='waitinglist1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567'/>
  </query>
</iq>

If the IM User provided a URI that is not served by an InteropPartner (e.g., a phone number associated with a telephony provider that is not in the WaitingListService's whitelist of InteropPartners), WaitingListService MAY send a "Remote Server Error" error to IM User.

Example 14. WaitingListService Returns "Remote Server Error" Error to IM User

<iq type='error' id='waitinglist1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item>
      <uri scheme='tel'>contact-number</uri>
      <name>contact-name</name>
    </item>
  </query>
  <error code='502' type='wait'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

If WaitingListService knows Contact JID when the IQ result is returned to the user, it MAY include the waiting list item in the IQ result:

Example 15. WaitingListService Returns IQ Result to IM User (With Contact JID)

<iq type='result'
    from='waitlist.service-provider.com'
    to='user@service-provider.com/resource'
    id='waitinglist1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567' jid='contact@service-provider.com'>
      <uri scheme='tel'>contact-number</uri>
      <name>contact-name</name>
    </item>
  </query>
</iq>

If WaitingListService knows Contact JID (or learns Contact JID from InteropPartner), it MUST inform IM User via "JID push" message:

Example 16. WaitingListService Pushes Contact's JID to IM User

<message
    from='waitlist.service-provider.com'
    to='user@service-provider.com'>
  <body>This message contains a waiting list item.</body>
  <waitlist xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567' jid='contact@service-provider.com'>
      <uri scheme='tel'>contact-number</uri>
      <name>contact-name</name>
    </item>
  </waitlist>
</message>

Note: The JID push uses <message/> because the WaitingListService has no knowledge of the user's presence and therefore cannot assume that an IQ will be received by the user at a specific resource.

If WaitingListService learns that Contact's URI is not handled by any InteropPartner, it SHOULD inform IM User via "JID push" message:

Example 17. WaitingListService Informs IM User that No InteropPartner Handles Contact's URI

<message
    from='waitlist.service-provider.com'
    to='user@service-provider.com'>
  <body>Sorry, we cannot find this contact.</body>
  <waitlist xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567' 
          jid='contact@service-provider.com'
          type='error'>
      <uri scheme='tel'>contact-number</uri>
      <name>contact-name</name>
      <error code='404' 
             type='cancel'
             xmlns='jabber:client'>
        <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
      </error>
    </item>
  </waitlist>
</message>

In order to remove the item from the waiting list, the IM User MUST complete the "Remove Contact from Waiting List" use case.

5.1.3 IM User Removes Contact from Waiting List

Example 18. IM User Sends Removal Request to WaitingListService

<iq type='set'
    from='user@service-provider.com/resource'
    to='waitlist.service-provider.com'
    id='remove1'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567'>
      <remove/>
    </item>
  </query>
</iq>

If WaitingListService previously recorded request, WaitingListService removes request from list and returns result to IM User.

Example 19. WaitingListService Returns Result to IM User

<iq type='result'
    from='waitlist.service-provider.com'
    to='user@service-provider.com/resource'
    id='remove1'/>

If WaitingListService did not previously record this request, WaitingListService sends "Not Found" error to IM User.

Example 20. WaitingListService Returns "Not Found" Error to IM User

<iq type='error' id='waitinglist4'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567'>
      <remove/>
    </item>
  </query>
  <error code='404' type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

5.2 WaitingListService Interaction With InteropPartners

This section of the document describes the inter-domain protocol for communication between WaitingListServices. The protocol defined in this section MUST be implemented by service providers.

A ServiceProvider's WaitingListService MUST be configured with a "whitelist" of InteropPartner's WaitingListServices with which it communicates. Therefore service discovery SHOULD NOT be necessary. However, if necessary it MAY use either the Agents Information protocol or the Service Discovery protocol as described in the following examples.

Note: The InteropPartner's WaitingListService is NOT REQUIRED to be hosted by InteropPartner, and could be hosted by a third party (e.g., a neutral phone number translation service). In this case, InteropPartner would simply advertise 'waitlist.third-party.com' as its WaitingListService.

5.2.1 ServiceProvider's WaitingListService Retrieves Current Waiting List

Example 21. ServiceProvider Discovers InteropPartner's WaitingListService by Sending Agents Request to InteropPartner

<iq type='get'
    from='waitlist.service-provider.com'
    to='interop-partner.com'
    id='agent2'>
  <query xmlns='jabber:iq:agents'/>
</iq>

Example 22. InteropPartner Returns Address of its WaitingListService

<iq type='result'
    from='interop-partner.com'
    to='waitlist.service-provider.com'
    id='agent2'>
  <query xmlns='jabber:iq:agents'>
    ...
    <agent jid='waitlist.interop-partner.com'>
      <name>Waiting List Service</name>
      <service>waitinglist</service>
    </agent>
    ...
  </query>
</iq>

Example 23. ServiceProvider Discovers InteropPartner's WaitingListService by Sending Service Discovery Request to InteropPartner

<iq type='get'
    from='waitlist.service-provider.com'
    to='interop-partner.com'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>

Example 24. InteropPartner Returns Address of its WaitingListService

<iq type='result' id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    ...
    <item jid='waitlist.service-provider.com'
          name='Waiting List Service'/>
    ...
  </query>
</iq>

Example 25. Service Provider Queries InteropPartner's WaitingListService for Detailed Information

<iq type='get'
    from='waitlist.service-provider.com'
    to='waitlist.interop-partner.com'
    id='disco2'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

Example 26. InteropPartner's WaitingListService Returns Detailed Information

<iq type='result'
    from='waitlist.interop-partner.com'
    to='waitlist.service-provider.com'
    id='disco2'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity category='directory'
              type='waitinglist'/>
    <feature var='http://jabber.org/protocol/waitinglist'/>
  </query>
</iq>

5.2.2 ServiceProvider's WaitingListService Adds Contact to Waiting List

Once a ServiceProvider's WaitingListService has discovered the InteropPartner's WaitingListService and requested its waiting list, the ServiceProvider's WaitingListService can add items to its waiting list based on URI.

Example 27. ServiceProvider's WaitingListService Adds New Item to Waiting List

<iq type='set'
    from='waitlist.service-provider.com'
    to='waitlist.interop-partner.com'
    id='waitinglist2'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item>
      <uri scheme='tel'>contact-number</uri>
    </item>
  </query>
</iq>

If Contact's URI is not associated with a person served by this InteropPartner, InteropPartner sends "Not Found" error to ServiceProvider.

Example 28. InteropPartner Returns "Not Found" Error to ServiceProvider

<iq type='error'
    from='waitlist.interop-partner.com'
    to='waitlist.service-provider.com'
    id='waitinglist2'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item>
      <uri scheme='tel'>contact-number</uri>
    </item>
  </query>
  <error code='404' type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

If Contact's URI is associated with a person served by this InteropPartner, InteropPartner sends acknowledgement of waiting list addition to ServiceProvider's WaitingListService.

Example 29. InteropPartner's WaitingListService Acknowledges Receipt

<iq type='result'
    from='waitlist.interop-partner.com'
    to='waitlist.service-provider.com'
    id='waitinglist2'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567'/>
  </query>
</iq>

If Contact is an IM User served by InteropPartner, InteropPartner's WaitingListService pushes Contact's JID to ServiceProvider's WaitingListService.

Example 30. InteropPartner's WaitingListService Pushes Contact's JID to ServiceProvider's WaitingListService

<iq type='set'
    from='waitlist.interop-partner.com'
    to='waitlist.service-provider.com'
    id='jidpush4'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567' jid='user@domain'>
      <uri scheme='tel'>contact-number</uri>
    </item>
  </query>
</iq>

Example 31. ServiceProvider's WaitingListService Acknowledges Receipt of JID Push

<iq type='result'
    from='waitlist.service-provider.com'
    to='waitlist.interop-partner.com'
    id='jidpush4'/>

After receiving acknowledgement (but not before), InteropPartner's WaitingListService MUST remove that item from the waiting list for the ServiceProvider's WaitingListService.

5.2.3 ServiceProvider's WaitingListService Removes Contact from Waiting List

Example 32. ServiceProvider Requests Removal of Item from Waiting List

<iq type='set'
    from='waitlist.service-provider.com'
    to='waitlist.interop-partner.com'
    id='remove2'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567'>
      <remove/>
    </item>
  </query>
</iq>

If item exists on waiting list, InteropPartner's WaitingListService removes item from list and returns result to ServiceProvider's WaitingListService.

Example 33. InteropPartner Returns Result to ServiceProvider

<iq type='result'
    from='waitlist.interop-partner.com'
    to='waitlist.service-provider.com'
    id='remove2'/>

If item does not exist on waiting list, InteropPartner's WaitingListService sends "Not Found" error to ServiceProvider's WaitingListService.

Example 34. InteropPartner Returns "Not Found" Error to ServiceProvider

<iq type='error'
    from='waitlist.interop-partner.com'
    to='waitlist.service-provider.com'
    id='remove2'>
  <query xmlns='http://jabber.org/protocol/waitinglist'>
    <item id='34567'>
      <remove/>
    </item>
  </query>
  <error code='404' type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

6. Implementation Notes

  1. Protocols and mechanisms for inviting a Contact to register as an IM User are out of scope for this proposal and shall be determined by each InteropPartner individually.
  2. A ServiceProvider's WaitingListService MUST record which of its IM Users have requested the JID associated with Contact's URI, and an InteropPartner's WaitingListService MUST record that Service Provider's WaitingListService (not User) has requested JID associated with Contact's URI. Therefore when Contact registers, InteropPartner's WaitingListService informs its local users as well as ServiceProvider's WaitingListService, and ServiceProvider's WaitingListService informs its local users.
  3. The InteropPartner's WaitingListService is NOT REQUIRED to be hosted by InteropPartner, and could be hosted by a third party (e.g., a neutral phone number translation service). In this case, InteropPartner would simply advertise 'waitlist.third-party.com' as its WaitingListService.
  4. Once an IM User learns a Contact's JID, the IM User MAY send a normal subscription request to the Contact, setting the "to" address to Contact's JID. This interaction is defined in the base XMPP specifications and is out of scope for this document.
  5. Implementations MUST support the older Agent Information [7] protocol and SHOULD support Service Discovery [8]. Note well that the Agent Information protocol will eventually be deprecated in favor of Service Discovery.
  6. An IM User's client receives waiting list information either via a "JID push" message (received from WaitingListService at any time) or in the IQ result received after requesting the waiting list (since one or more of the waiting list items may contain a JID). (The same rule applies to a ServiceProvider's WaitingListService that receives an IQ set from an InteropPartner's WaitingListService.)
  7. When an IM User logs in, the user's client SHOULD request the current waiting list.
  8. Although the examples in this JEP show the hostname of the WaitingListService as 'waitlist.third-party.com' (etc.), this is for convenience only; the hostname MAY be any valid DNS hostname.
  9. When sending JID pushes, an implementation MAY specify a message type of 'headline', which in some deployments will prevent such messages from being stored offline for later delivery.

7. Security Considerations

A ServiceProvider's WaitingListService MUST be configured with a "whitelist" of InteropPartners with which it communicates. The WaitingListService SHOULD NOT communicate with any InteropPartners that are not on the whitelist.

Requesting JIDs via waiting lists is not bidirectional; i.e., a service MUST NOT allow an IM User to discover a Contact's non-XMPP URI based on the Contact's JID.

A service MAY require a Contact to approve the disclosure of the contact's JID, either as a global preference or for each request; however, this is a local policy matter.

8. IANA Considerations

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

9. Jabber Registrar Considerations

The Jabber Registrar [10] shall register the 'http://jabber.org/protocol/waitinglist' namespace as a result of this JEP.

For use in Service Discovery, supported URI schemes SHOULD be registered using namespace names of the form 'http://jabber.org/protocol/waitlist/schemes/SCHEME-NAME'. This JEP registers the following two namespace names for URI schemes, but others MAY be registered in the future using standard registration procedures:

10. XML Schema

The following schema is descriptive, not normative.

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/waitinglist'
    xmlns='http://jabber.org/protocol/waitinglist'
    elementFormDefault='qualified'>

  <xs:element name='query'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='item'
                    minOccurs='0'
                    maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='item'>
    <xs:complexType>
      <xs:choice minOccurs='0' maxOccurs='1'>>
        <xs:sequence xmlns:xmpp='jabber:client'>
          <xs:element ref='uri' minOccurs='1' maxOccurs='1'/>
          <xs:element ref='name' minOccurs='0' maxOccurs='1'/>
          <xs:element ref='xmpp:error' minOccurs='0' maxOccurs='1'/>
        </xs:sequence>
        <xs:element ref='remove'/>
      </xs:choice>
      <xs:attribute name='id'
                    type='xs:string'
                    use='optional'/>
      <xs:attribute name='jid'
                    type='xs:string'
                    use='optional'/>
      <xs:attribute name='type'
                    use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='error'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

  <xs:element name='uri' type='xs:string'>
    <xs:complexType>
      <xs:attribute name='scheme'
                    type='xs:NCNAME'
                    use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='name' type='string1023'/>

  <xs:element name='remove' type='empty'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name='string1023'>
    <xs:restriction base='xs:string'>
      <xs:maxLength value='1023'/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

Notes

1. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.

2. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.

3. RFC 3966: The tel URI for Telephone Numbers <http://www.ietf.org/rfc/rfc3966.txt>.

4. RFC 2368: The mailto URL scheme <http://www.ietf.org/rfc/rfc2368.txt>.

5. RFC 3986: Uniform Resource Identifiers (URI): Generic Syntax <http://www.ietf.org/rfc/rfc3986.txt>.

6. JEP-0086: Error Condition Mappings <http://www.jabber.org/jeps/jep-0086.html>.

7. JEP-0094: Agent Information <http://www.jabber.org/jeps/jep-0094.html>.

8. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.

9. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

10. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.

Revision History

Version 0.3 (2004-09-27)

Corrected error syntax used when Contact URI is not handled by any InteropPartner. (psa)

Version 0.2 (2004-09-03)

Added alternate flow for situation in which Contact URI is not handled by any InteropPartner; changed headline message type for JID pushes from SHOULD to MAY; clarified semantics of item ID; added name child of item; corrected and updated the XML schema; updated examples to use XMPP error conditions. (psa)

Version 0.1 (2004-03-18)

Initial version (see XML source for earlier revisions). (psa)

END