XEP-0155: Chat Session Negotiation

Peter Saint-Andre

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

Ian Paterson

Email: ian.paterson@clientside.co.uk
JID: ian@zoofy.com

1. Introduction

2. Use Cases

2.1. Initiating a Chat

2.2. Renegotiating a Chat

2.3. Switching Resources

2.4. Terminating a Chat

3. Mapping to SIP

4. Implementation Notes

4.1. Auto Accept or Reject

4.2. Unavailable Presence

5. Security Considerations

6. IANA Considerations

7. XMPP Registrar Considerations

7.1. Service Discovery Features

7.2. Field Standardization

8. XML Schema

9. Acknowledgements

Notes

Revision History

2.1 Initiating a Chat

In order to initiate a negotiated chat session, the initiating party ("user") sends a <message/> [9] 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 [10]). The <message/> stanza type SHOULD be "normal" (either explicitly or by non-inclusion of the 'type' attribute). The stanza 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". [11] The inclusion of "otr" and "security" fields is also RECOMMENDED. Note: The options within any 'list-single' fields SHOULD appear in order of preference.

Note: Chat sessions may be conducted between entities who are never online at the same time. However, if the user is interested only in an immediate chat session then the user SHOULD instruct the contact's server not to store the message for later delivery using the Advanced Message Processing [12] protocol.

In the following example of a negotiation request, Romeo requests a chat with Juliet and also queries her regarding whether she wants to enable all message logging (see Message Archiving [13]) [14] and support the XHTML-IM [15] and Chat State Notifications [16] extensions during this chat session. He also requires that they are both connected securely to their servers, and asks which language she prefers amoungst those he can write. (Note: These fields are examples only; a full set of chat session negotiation parameters will be registered as described in the XMPP Registrar Considerations section of this document.)

Example 1. User requests chat session

<message type='normal'
         from='romeo@montague.net/orchard'
         to='juliet@capulet.com'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <feature xmlns='http://jabber.org/protocol/feature-neg'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Open chat with Romeo?</title>
      <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='Off-The-Record?' type='list-single' var='otr'>
        <value>false</value>
        <option label='Allow message logging'>
          <value>false</value>
        </option>
        <option label='Disable all message logging'>
          <value>true</value>
        </option>
      </field>
      <field label='XHTML Formatting?'
             type='list-single'
             var='http://jabber.org/protocol/xhtml-im'>
        <value>true</value>
        <option label='Disable'><value>false</value></option>
        <option label='Enable'><value>true</value></option>
      </field>
      <field label='Chat State Notifications?'
             type='list-single'
             var='http://jabber.org/protocol/chatstates'>
        <value>true</value>
        <option label='Disable'><value>false</value></option>
        <option label='Enable'><value>true</value></option>
      </field>
      <field label='Minimum security level'
             type='list-single'
             var='security'>
        <value>c2s</value>
        <option label='Both parties must be securely connected to their servers'>
          <value>c2s</value>
        </option>
      </field>
      <field label='Primary written language of the chat'
             type='list-single'
             var='language'>
        <value>en</value>
        <option label='English'><value>en</value></option>
        <option label='Italiano'><value>it</value></option>
      </field>
    </x>
  </feature>
  <amp xmlns='http://jabber.org/protocol/amp'>
    <rule action='drop' condition='deliver' value='stored'/>
  </amp>
</message>
    

The user MAY request a session with a specific resource of the contact. However, if the user specifies no resource (or if the specified resource is not available), then the contact's server delivers the request to the contact's most available resource (which in the examples below happens to be "balcony"). If no resource is available (and no Advanced Message Processing rule included in the request specifies otherwise) then the server MAY store the request for later delivery. In this case, if the contact is interested only in an immediate chat session when it eventually receives the request, it SHOULD initiate a new chat session negotiation (including a newly-generated ThreadID) instead of responding to the user's request. Note: Sending any response to the user's original request would leak presence information since it would divulge the fact that the contact had been offline rather than just ignoring the user.

In any response to the user's request, the contact's client MUST mirror the <thread/> value so that the user's client can correctly track the response.

If the contact's client does not support one of the default values or if the contact has disabled its support (as for Chat State Notifications and XHTML formatting in the example below), and the client can still accept the request, then it MUST set that field to a value that it can support.

If the contact's client is configured to show the form to the client instead of responding automatically it SHOULD replace the content of the <title/> element and of all label attributes of the <field/> and <option/> elements with it's own localised versions before showing the form to the client - even if the form already appears to be in the correct language. Note: If a client fails to localise the form then an malicious contact might, for examples, either switch the labels on the 'security' and 'otr' fields, or use the <title/> to mislead the user regarding the identity of the contact.

In the example below we assume that Juliet accepts the chat and specifies that she prefers to speak Italian with Romeo:

Example 2. Contact accepts chat and specifies parameters

<message type='normal'
         from='juliet@capulet.com/balcony'
         to='romeo@montague.net/orchard'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <feature xmlns='http://jabber.org/protocol/feature-neg'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'>
        <value>http://jabber.org/protocol/chatneg</value>
      </field>
      <field var='accept'><value>true</value></field>
      <field var='otr'><value>false</value></field>
      <field var='http://jabber.org/protocol/xhtml-im'>
        <value>false</value>
      </field>
      <field var='http://jabber.org/protocol/chatstates'>
        <value>false</value>
      </field>
      <field var='security'><value>c2s</value></field>
      <field var='language'><value>it</value></field>
    </x>
  </feature>
</message>
    

Note: Both entities MUST assume the session has been established with the resource of the contact that sends the reply, even if the user sent its request to a different resource of the contact.

If the contact does not want to reveal presence to the user for whatever reason then the contact's client SHOULD return no response or error (see Security Considerations). Also, if the contact is using a legacy client then it MAY not support returning any response or error. In both these cases the user MAY, proceed to send stanzas to the contact outside the context of a negotiated chat session.

However, if the contact simply prefers not to chat then the client SHOULD decline the invitation:

Example 3. Contact declines offer and specifies reason

<message type='normal'
         from='juliet@capulet.com/balcony'
         to='romeo@montague.net/orchard'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <feature xmlns='http://jabber.org/protocol/feature-neg'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'>
        <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 the contact'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:

Example 4. Contact returns service unavailable error

<message type='error'
         from='juliet@capulet.com/balcony'
         to='romeo@montague.net/orchard'>
  <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>
      ...
    </x>
  </feature>
  <error code='503' type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</message>
    

If the contact's client does not support one or more of the required features, it SHOULD return a <feature-not-implemented/> error, specifying the field(s) not implemented using the 'var' attribute of one or more <field/> child elements of a <feature/> child element of the <error/> scoped by the 'http://jabber.org/protocol/feature-neg' namespace:

Example 5. Contact returns feature not implemented error

<message type='error'
         from='juliet@capulet.com/balcony'
         to='romeo@montague.net/orchard'>
  <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>
      ...
    </x>
  </feature>
  <error code='501' type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <field var='otr'/>
    </feature>
  </error>
</message>
    

If the contact's client supports none of the options for one or more fields, it SHOULD return a <not-acceptable/> error, specifying the field(s) with unsupported options using the 'var' attribute of one or more <field/> child elements of a <feature/> child element of the <error/> scoped by the 'http://jabber.org/protocol/feature-neg' namespace:

Example 6. Contact returns options not acceptable error

<message type='error'
         from='juliet@capulet.com/balcony'
         to='romeo@montague.net/orchard'>
  <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>
      ...
    </x>
  </feature>
  <error code='406' type='modify'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <field var='security'/>
    </feature>
  </error>
</message>
    

Finally, if the contact accepted the chat then the user SHOULD reply with a result form containing an 'accept' field set to 'true' (or '1') to confirm to the contact that the combination of values it submitted was acceptable, and that the chat session is open. [17] The user MAY include other content (e.g., a <body/> element) in the confirmation stanza:

Example 7. User confirms session is open

<message type='normal'
         from='romeo@montague.net/orchard'
         to='juliet@capulet.com/balcony'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <feature xmlns='http://jabber.org/protocol/feature-neg'>
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE'>
        <value>http://jabber.org/protocol/chatneg</value>
      </field>
      <field var='accept'><value>1</value></field>
    </x>
  </feature>
  <body>I forgot what I wanted to say!</body>
</message>
    

2.2 Renegotiating a Chat

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.

Note: The "accept" field SHOULD NOT be included in a renegotiation form. The set of other fields in the form MAY be different from the set included in the initial session negotitation.

Example 8. One party requests renegotiation

<message type='normal'
         from='juliet@capulet.com/balcony'
         to='romeo@montague.net/orchard'>
  <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='Off-The-Record?' type='list-single' var='otr'>
        <value>true</value>
        <option label='Disable all message logging'>
          <value>true</value>
        </option>
      </field>
      <field label='Reason' type='text-single' var='reason'>
        <value>Lets keep this private!</value>
      </field>
    </x>
  </feature>
</message>
    

Example 9. Other party accepts offer and specifies parameters

<message type='normal'
         from='romeo@montague.net/orchard'
         to='juliet@capulet.com/balcony'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <feature xmlns='http://jabber.org/protocol/feature-neg'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'>
        <value>http://jabber.org/protocol/chatneg</value>
      </field>
      <field var='otr'><value>true</value></field>
    </x>
  </feature>
</message>
    

If the other party's client does not support one or more of the required features, it SHOULD return a <feature-not-implemented/> error instead, while if it supports none of the options for one or more fields, it SHOULD return a <not-acceptable/> error instead (see Initiating a Chat). In either of these cases the existing negotiated chat session parameters are maintained. Either party MAY then terminate the chat session as specified in the section Terminating a Chat.

2.3 Switching Resources

Either party MAY ask to continue the session using another of its resources. The requesting party does this by submitting a form with a "continue" field containing the value of the new resource:

Example 10. One party asks to switch session to another of its resources

<message type='normal'
         from='juliet@capulet.com/balcony'
         to='romeo@montague.net/orchard'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <feature xmlns='http://jabber.org/protocol/feature-neg'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'>
        <value>http://jabber.org/protocol/chatneg</value>
      </field>
      <field var='continue'><value>PDA</value></field>
    </x>
  </feature>
</message>
    

The requesting party SHOULD NOT send stanzas within the session from either resource until the other party has accepted or rejected (with a <feature-not-implemented/> error) the switch to the new resource.

The other party SHOULD accept the switch since the requesting party might otherwise be unable to continue the session:

Example 11. Other party accepts switch

<message type='normal'
         from='romeo@montague.net/orchard'
         to='juliet@capulet.com/balcony'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <feature xmlns='http://jabber.org/protocol/feature-neg'>
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE'>
        <value>http://jabber.org/protocol/chatneg</value>
      </field>
      <field var='continue'><value>PDA</value></field>
    </x>
  </feature>
</message>
    

Once the other party has accepted the switch then all stanzas sent within the chat session MUST be to or from the new resource. Note: Both parties MUST ensure that they comply with all the other chat session negotiation parameters that were previously agreed for this session.

2.4 Terminating a Chat

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 of type "submit". The <message/> stanza MUST contain a <thread/> element with the same XML character data as the original initiation request. The data form containing a boolean field named "terminate" set to a value of "1" or "true" and MAY also contain a "reason" field.

Example 12. One party terminates chat and specifies reason

<message type='normal'
         from='juliet@capulet.com/balcony'
         to='romeo@montague.net/orchard'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <feature xmlns='http://jabber.org/protocol/feature-neg'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'>
        <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.

The other party's client MAY explicitly acknowledge the termination of the chat by sending a <message/> containing a data form of type "result", with no "reason" field and the value of the "terminate" field set to "1" or "true". The client MUST mirror the <thread/> value it received.

Example 13. Other party acknowledges chat termination

<message type='normal'
         from='romeo@montague.net/orchard'
         to='juliet@capulet.com/balcony'>
  <thread>ffd7076498744578d10edabfe7f4a866</thread>
  <feature xmlns='http://jabber.org/protocol/feature-neg'>
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE'>
        <value>http://jabber.org/protocol/chatneg</value>
      </field>
      <field var='terminate'><value>1</value></field>
    </x>
  </feature>
</message>
    

4.1 Auto Accept or Reject

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 (see Security Considerations).

4.2 Unavailable Presence

If a party receives an XMPP presence stanza 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) during a chat session, the receiving party SHOULD assume that the other client will still be able to continue the session (perhaps it simply became "invisible", or it is persisting the state of the negotiated chat until it reconnects and receives "offline" messages).

However, the receiving party MAY assume that the other client will not be able to continue the session. [19] In that case it MUST explicitly terminate the session (see Terminating a Chat) - since its assumption could be incorrect. If after terminating the session the receiving party later 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, then it MUST initiate a new chat session (including a newly-generated ThreadID) with the other party. It MUST NOT renegotiate parameters for the terminated session. (Note: This is consistent with the handling of chat states as specified in XEP-0085.)

7.1 Service Discovery Features

The XMPP Registrar [21] 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>XEP-0155</doc>
</var>
    

7.2 Field Standardization

Field Standardization for Data Forms [22] 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>XEP-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='continue'
      type='text-single'
      label='Another resource with which to continue the session'/>
  <field
      var='http://jabber.org/protocol/chatstates'
      type='list-single'
      label='Whether to enable Chat State Notifications per XEP-0085'>
    <option label='Disable'>
      <value>false</value>
    </option>
    <option label='Enable'>
      <value>true</value>
    </option>
  </field>
  <field
      var='http://jabber.org/protocol/xhtml-im'
      type='list-single'
      label='Whether to enable XHTML-IM formatting per XEP-0071'/>
    <option label='Disable'>
      <value>false</value>
    </option>
    <option label='Enable'>
      <value>true</value>
    </option>
  </field>
  <field
      var='language'
      type='list-single'
      label='Primary written language of the chat (each
            value appears in order of preference and 
            conforms to RFC 4646 and the IANA registry)'/>
  <field
      var='otr'
      type='list-single'
      label='Off-The-Record'>
    <option label='Allow message logging'>
      <value>false</value>
    </option>
    <option label='Disable absolutely all message logging 
                   including automatic archiving - see 
                   XEP-0136'>
      <value>true</value>
    </option>
  </field>
  <field
      var='reason'
      type='text-single'
      label='A reason for chatting (or not)'/>
  <field
      var='security'
      type='list-single'
      label='Minimum security level'>
    <option label='Secure connections not required'>
      <value>none</value>
    </option>
    <option label='Both parties must be securely connected to their servers'>
      <value>c2s</value>
    </option>
    <option label='Both parties must be securely connected to each other'>
      <value>e2e</value>
    </option>
  </field>
  <field
      var='terminate'
      type='boolean'
      label='Whether to terminate the session'/>
</form_type>
      

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

2. XEP-0116: Encrypted Sessions <http://www.xmpp.org/extensions/xep-0116.html>.

3. XEP-0136: Message Archiving <http://www.xmpp.org/extensions/xep-0136.html>.

4. XEP-0030: Service Discovery <http://www.xmpp.org/extensions/xep-0030.html>.

5. XEP-0115: Entity Capabilities <http://www.xmpp.org/extensions/xep-0115.html>.

6. RFC 3261: Session Initiation Protocol (SIP) <http://www.ietf.org/rfc/rfc3261.txt>.

7. 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.

8. XEP-0020: Feature Negotiation <http://www.xmpp.org/extensions/xep-0020.html>.

9. 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).

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

11. 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.

12. XEP-0079: Advanced Message Processing <http://www.xmpp.org/extensions/xep-0079.html>.

13. XEP-0136: Message Archiving <http://www.xmpp.org/extensions/xep-0136.html>.

14. A client MUST NOT set the 'otr' field to 'true' unless it has confirmed that its server will allow it to switch off Automated Archiving (see Message Archiving).

15. XEP-0071: XHTML-IM <http://www.xmpp.org/extensions/xep-0071.html>.

16. XEP-0085: Chat State Notifications <http://www.xmpp.org/extensions/xep-0085.html>.

17. See Encrypted Sessions for examples where the user might find the values submitted by the contact unacceptable.

18. 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).

19. In general, if a party is not subscribing to the other party's presence then it will never assume the other party is is unable to continue a session.

20. 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/>.

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

22. XEP-0068: Field Data Standardization for Data Forms <http://www.xmpp.org/extensions/xep-0068.html>.

Version 0.10 (2006-10-31)

Version 0.9 (2006-10-08)

Version 0.8 (2006-10-02)

Version 0.7 (2006-07-14)

Version 0.6 (2006-07-13)

Version 0.5 (2006-01-24)

Version 0.4 (2006-01-03)

Version 0.3 (2005-12-30)

Version 0.2 (2005-07-15)

Version 0.1 (2005-07-14)

Version 0.0.1 (2005-07-12)