This document specifies a feature negotiation profile for initiating a one-to-one chat session.
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.
Status:
Experimental
Type:
Standards Track
Number: 0155
Version: 0.7
Last Updated: 2006-07-14
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, XMPP IM, JEP-0020, JEP-0068
Supersedes: None
Superseded By: None
Short Name: chatneg
Wiki Page: <http://wiki.jabber.org/index.php/Chat Session Negotiation (JEP-0155)>
Email:
stpeter@jabber.org
JID:
stpeter@jabber.org
This Jabber Enhancement Proposal is copyright 1999 - 2006 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 Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
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 protocol defined in this JEP 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.
The following 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".
The traditional model for one-to-one chat "sessions" in Jabber/XMPP is for a user to simply send a message to a contact without any formal negotiation of chat session parameters (e.g., see XMPP IM [1]). This informal approach to initiation of a chat session is perfectly acceptable in many contexts, environments, and cultures. However, it may be desirable to formally request the chat and negotiate its parameters before beginning the chat session in some circumstances, such as:
This proposal defines best practices for such a negotiation, re-using the protocol defined in Feature Negotiation [6].
In order to initiate a negotiated chat session, the initiating party ("user") sends a <message/> stanza to the receiving party ("contact") containing a <feature/> child qualified by the 'http://jabber.org/protocol/feature-neg' namespace. The <message/> stanza MUST NOT contain a <body/> child element (as specified in RFC 3921 [7]). The <message/> stanza is used because the user does not necessarily know which of the contact's resources is most available (or indeed if the contact is online). The <message/> stanza type SHOULD be "normal" (either explicitly or by non-inclusion of the 'type' attribute). The stanza SHOULD include an 'id' attribute and MUST contain a <thread/> element for tracking purposes (where the newly-generated ThreadID is unique to the proposed session). The data form MUST contain a hidden FORM_TYPE field whose value is "http://jabber.org/protocol/chatneg" and MUST contain a boolean field named "accept". [8]
The following is an example of a negotiation request:
Example 1. User requests chat session
<message type='normal'
from='romeo@montague.net/orchard'
to='juliet@capulet.com'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field label='Accept this chat?'
type='boolean'
var='accept'>
<value>true</value>
<required/>
</field>
<field label='Enable XHTML Formatting?'
type='boolean'
var='http://jabber.org/protocol/xhtml-im'>
<value>0</value>
</field>
<field label='Enable Chat State Notifications?'
type='boolean'
var='http://jabber.org/protocol/chatstates'>
<value>0</value>
</field>
<field label='Allow Message Logging?'
type='boolean'
var='logging'>
<value>0</value>
</field>
<field label='Must Both Parties Be Securely Connected to Their Servers?'
type='boolean'
var='secure'>
<value>1</value>
</field>
<field label='Reason'
type='text-single'
var='reason'>
<value>Can we talk?</value>
</field>
</x>
</feature>
</message>
In the foregoing example, Romeo requests a chat with Juliet and also queries her regarding whether she wants to allow client-side message logging and support XHTML-IM [9] and Chat State Notifications [10] extensions during this chat session. (Note: These fields are examples only; a full set of chat session negotiation parameters will be registered as described in the Jabber Registrar Considerations section of this document.)
Juliet's server delivers Romeo's request to her most available resource (which happens to be "balcony").
In any response to the request, the contact's client MUST mirror the 'id' attribute and <thread/>value so that the user's client can correctly track the response.
We assume that Juliet accepts the chat and specifies that she does not want to log messages or use XHTML formatting but that she does want to use Chat State Notifications:
Example 2. Contact accepts offer and specifies parameters
<message type='normal'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='accept'>
<value>true</value>
</field>
<field var='http://jabber.org/protocol/xhtml-im'>
<value>0</value>
</field>
<field var='http://jabber.org/protocol/chatstates'>
<value>1</value>
</field>
<field var='logging'>
<value>0</value>
</field>
<field var='secure'>
<value>1</value>
</field>
<field var='reason'>
<value>Sure, let's talk!</value>
</field>
</x>
</feature>
</message>
However, it could be that Juliet is busy so she declines the invitation.
Example 3. Contact declines offer and specifies reason
<message type='normal'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='accept'>
<value>0</value>
</field>
<field var='reason'>
<value>Sorry, can't chat now! How about tonight?</value>
</field>
</x>
</feature>
</message>
If Juliet's client does not support feature negotiation or does not support the "http://jabber.org/protocol/chatneg" FORM_TYPE, it SHOULD return a <service-unavailable/> error (but MAY return no error if, for example, Juliet does not want to reveal her presence to Romeo for whatever reason):
Example 4. Contact returns service unavailable error
<message type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field label='Accept this chat?'
type='boolean'
var='accept'>
<value>1</value>
<required/>
</field>
<field label='Enable XHTML Formatting?'
type='boolean'
var='http://jabber.org/protocol/xhtml-im'>
<value>0</value>
</field>
<field label='Enable Chat State Notifications?'
type='boolean'
var='http://jabber.org/protocol/chatstates'>
<value>0</value>
</field>
<field label='Allow Message Logging?'
type='boolean'
var='logging'>
<value>0</value>
</field>
<field label='Must Both Parties Be Securely Connected to Their Servers?'
type='boolean'
var='secure'>
<value>1</value>
</field>
<field label='Reason'
type='text-single'
var='reason'>
<value>Can we talk?</value>
</field>
</x>
</feature>
<error code='503' type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
If Juliet's client does not support one of the required features, it SHOULD return a <feature-not-implemented/> error (but MAY return no error if, for example, Juliet does not want to reveal her presence to Romeo for whatever reason):
Example 5. Contact returns feature not implemented error
<message type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='init1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field label='Accept this chat?'
type='boolean'
var='accept'>
<value>1</value>
<required/>
</field>
<field label='Enable XHTML Formatting?'
type='boolean'
var='http://jabber.org/protocol/xhtml-im'>
<value>0</value>
</field>
<field label='Enable Chat State Notifications?'
type='boolean'
var='http://jabber.org/protocol/chatstates'>
<value>0</value>
</field>
<field label='Allow Message Logging?'
type='boolean'
var='logging'>
<value>0</value>
</field>
<field label='Must Both Parties Be Securely Connected to Their Servers?'
type='boolean'
var='secure'>
<value>1</value>
</field>
<field label='Reason'
type='text-single'
var='reason'>
<value>Can we talk?</value>
</field>
</x>
</feature>
<error code='501' type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
If Juliet's client does not support one of the optional features (e.g., Chat State Notifications) but it accepts the request, it MUST set the value of that boolean variable to "0" or "false".
At any time during an existing chat session, either party MAY attempt to renegotiate the parameters of the session. The requesting party does this by sending a new <message/> stanza containing a feature negotiation form and a <thread/> element with the same value as that of the existing chat session.
Example 6. One party requests renegotiation
<message type='normal'
from='juliet@capulet.com/balcony'
to='romeo@montague.net'
id='reneg1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field label='Accept this chat?'
type='boolean'
var='accept'>
<value>true</value>
<required/>
</field>
<field label='Enable XHTML Formatting?'
type='boolean'
var='http://jabber.org/protocol/xhtml-im'>
<value>true</value>
</field>
<field label='Enable Chat State Notifications?'
type='boolean'
var='http://jabber.org/protocol/chatstates'>
<value>true</value>
</field>
<field label='Allow Message Logging?'
type='boolean'
var='logging'>
<value>false</value>
</field>
<field label='Must Both Parties Be Securely Connected to Their Servers?'
type='boolean'
var='secure'>
<value>1</value>
</field>
<field label='Reason'
type='text-single'
var='reason'>
<value>Gotta have formatting!</value>
</field>
</x>
</feature>
</message>
Example 7. Other party accepts offer and specifies parameters
<message type='normal'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='reneg1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='accept'>
<value>true</value>
</field>
<field var='http://jabber.org/protocol/xhtml-im'>
<value>true</value>
</field>
<field var='http://jabber.org/protocol/chatstates'>
<value>1</value>
</field>
<field var='logging'>
<value>0</value>
</field>
<field var='secure'>
<value>1</value>
</field>
<field var='reason'>
<value>Agreed, XHTML is fun.</value>
</field>
</x>
</feature>
</message>
In order to explicitly terminate a negotiated chat, the party that wishes to end the chat MUST do so by sending a <message/> containing a data form. The <message/> stanza SHOULD possess an 'id' attribute and MUST contain a <thread/> element with the same XML character data as the original initiation request. The data form containing a boolean field set named "terminate" set to a value of "1" or "true" and MAY also contain a "reason" field.
Example 8. Contact terminates chat and specifies reason
<message type='normal'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='term1'>
<thread>ffd7076498744578d10edabfe7f4a866</thread>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value>
</field>
<field var='terminate'>
<value>1</value>
</field>
<field var='reason'>
<value>Gotta go!</value>
</field>
</x>
</feature>
</message>
Both parties MUST then consider the chat session to be ended.
If a party receives XMPP presence of type "unavailable" from the full JID (<node@domain.tld/resource>) of the other party (i.e., the resource with which it has had an active session), the receiving party MUST consider the session to be terminated. If the receiving party then receives presence of type "available" from that same resource or another resource associated with the other party and the receiving party desires to restart the chat session, it MUST initiate a new chat session (including a newly-generated ThreadID) with the other party rather than renegotiate parameters for the terminated session. (Note: This is consistent with the handling of chat states as specified in JEP-0085.)
When mapping instant messaging flows to SIP, implementations SHOULD adhere to draft-saintandre-xmpp-simple [11].
In addition, the following mappings apply to chat session negotiation:
A client MAY require a human user to approve each chat session negotiation request or MAY auto-accept and auto-reject requests based on some user-configurable policy.
If a contact accepts a user's request or returns an error to the user, the user will effectively discover the contact's presence (at least the presence of one of the contact's resources). Due care must be exercised in determining whether to accept the request or return an error (e.g., the contact's client MUST NOT automatically accept the user's request or return an error to the user if the user is in the contact's block list).
This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [12].
The Jabber Registrar [13] shall include 'http://jabber.org/protocol/chatneg' in its registry of Service Discovery features.
Registry Submission
<var>
<name>http://jabber.org/protocol/chatneg</name>
<desc>Support for Chat Session Negotiation and its FORM_TYPE</desc>
<doc>JEP-0155</doc>
</var>
Field Standardization for Data Forms [14] defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. The following fields shall be registered for use in Chat Session Negotiation:
Registry Submission
<form_type>
<name>http://jabber.org/protocol/chatneg</name>
<doc>JEP-0155</doc>
<desc>
Forms enabling negotation of a one-to-one
chat session between two entities.
</desc>
<field
var='accept'
type='boolean'
label='Whether to accept the invitation'/>
<field
var='http://jabber.org/protocol/chatstates'
type='boolean'
label='Whether to enable Chat State Notifications per JEP-0085'/>
<field
var='http://jabber.org/protocol/xhtml-im'
type='boolean'
label='Whether to enable XHTML-IM formatting per JEP-0071'/>
<field
var='logging'
type='boolean'
label='Whether to allow client-side message logging'/>
<field
var='reason'
type='text-single'
label='A reason for chatting (or not)'/>
<field
var='secure'
type='boolean'
label='Whether both parties must be securely connected to their servers'/>
<field
var='terminate'
type='boolean'
label='Whether to terminate the session'/>
</form_type>
This proposal re-uses the format defined in JEP-0020 and therefore does not require a separate schema.
Thanks to Thomas Charron, Ian Paterson, and Jean-Louis Seguineau for their feedback.
1. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.
2. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.
3. JEP-0115: Entity Capabilities <http://www.jabber.org/jeps/jep-0115.html>.
4. RFC 3261: Session Initiation Protocol (SIP) <http://www.ietf.org/rfc/rfc3261.txt>.
5. In essence, a chat state negotiation request as specified herein is functionally equivalent to a SIP INVITE request, and acceptance of such a request is functionally equivalent to sending a SIP 200 OK response; see Section 17 of RFC 3261.
6. JEP-0020: Feature Negotiation <http://www.jabber.org/jeps/jep-0020.html>.
7. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.
8. In accordance with Section 3.2.2.1 of XML Schema Part 2: Datatypes, the allowable lexical representations for the xs:boolean datatype are the strings "0" and "false" for the concept 'false' and the strings "1" and "true" for the concept 'true'; implementations MUST support both styles of lexical representation.
9. JEP-0071: XHTML-IM <http://www.jabber.org/jeps/jep-0071.html>.
10. JEP-0085: Chat State Notifications <http://www.jabber.org/jeps/jep-0085.html>.
11. Basic Messaging and Presence Interoperability between the Extensible Messaging and Presence Protocol (XMPP) and Session Initiation Protocol (SIP) for Instant Messaging and Presence Leveraging Extensions (SIMPLE) <http://www.ietf.org/internet-drafts/draft-saintandre-xmpp-simple-05.txt> (work in progress).
12. 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/>.
13. 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/>.
14. JEP-0068: Field Data Standardization for Data Forms <http://www.jabber.org/jeps/jep-0068.html>.
Added secure field from JEP-0116.
(psa)Specified that a client must re-initiate if it receives presence unavailable; changed JEP type to Standards Track.
(psa)Added renegotiate use case.
(psa)Added terminate use case; further specified mapping to SIP.
(psa)Further specified use of id attribute and thread element.
(psa)Further described contexts in which chat session negotiation could be useful; added more examples; added reference to SIP RFC and explained basic mapping to SIP INVITE method; added Jabber Registrar considerations.
(psa)Initial JEP version.
(psa)First draft.
(psa)END