XEP-0181: Jingle DTMF

WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems are advised to carefully consider whether it is appropriate to deploy implementations of this protocol before it advances to a status of Draft.

Table of Contents

1. Introduction

Traditional telephony systems such as the public switched telephone network (PSTN) use Dual Tone Multi-Frequency (DTMF) events for dialing and to issue commands such as those used in interactive voice response (IVR) applications. Internet telephony systems also use DTMF tones, usually for interoperability with the PSTN but sometimes also in native Internet services.

XMPP applications that use Jingle [1] and the Real-time Transport Protocol (RFC 3550 [2]) for voice chat as described in Jingle RTP Sessions [3] MUST support and prefer native RTP methods of communicating DTMF information, in particular the "audio/telephone-event" and "audio/tone" media types. Such applications SHOULD NOT use the protocol described herein for communicating DTMF information with RTP-aware endpoints.

However, XMPP applications MAY support and use the protocol described herein for communicating DTMF information with endpoints that are not RTP-aware, such as gateways to the PSTN.

2. Format

The format for the representation of DTMF events over XMPP is as follows (see Namespace Versioning regarding the possibility of incrementing the version number):

<dtmf xmlns='urn:xmpp:jingle:dtmf:0'
      code='0-9,#,*,A-D'
      duration='milliseconds'
      volume='0-63'/>
  

The <dmtf/> element MUST be empty.

The attributes of the <dmtf/> element are as follows.

The <dtmf> element SHOULD be sent as the payload of a Jingle session-info message as illustrated in the following example.

Example 1. Entity sends DTMF message

<iq from='juliet@capulet.com/balcony'
    id='dtmf1'
    to='ivr.shakespeare.lit'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:0'
          action='session-info'
          initiator='juliet@capulet.com/balcony'
          sid='a73sjjvkla37jfea'>
    <dtmf xmlns='urn:xmpp:jingle:dtmf:0'
          code='7'
          duration='400'
          volume='42'/>
  </jingle>
</iq>
  

The receiving entity MUST send an IQ result if it can process the DTMF:

Example 2. Receiving entity acknowledges DTMF message

<iq from='ivr.shakespeare.lit'
    id='dtmf1'
    to='juliet@capulet.com/balcony'
    type='result'/>
  

If the receiving entity does not support this protocol, it MUST return a <service-unavailable/> stanza error.

Example 3. Receiving entity does not support DTMF protocol

<iq from='ivr.shakespeare.lit'
    id='dtmf1'
    to='juliet@capulet.com/balcony'
    type='error'>
  <error type='cancel'>
    <service-unavailable 
      xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
  

If the receiving entity supports this protocol but does not understand the specified code, it MUST return a <feature-not-implemented/> stanza error.

Example 4. Receiving entity does not understand code

<iq from='ivr.shakespeare.lit'
    id='dtmf1'
    to='juliet@capulet.com/balcony'
    type='error'>
  <error type='cancel'>
    <feature-not-implemented 
      xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
  

If the receiving entity is using or wishes to use a different method for exchanging DTMF events (e.g., the methods specified in RFC 2833 [5] or its successor RFC 4733 [6]), it MUST return a <not-acceptable/> stanza error.

Example 5. Receiving prefers non-XMPP DTMF method

<iq from='ivr.shakespeare.lit'
    id='dtmf1'
    to='juliet@capulet.com/balcony'
    type='error'>
  <error type='cancel'>
    <not-acceptable 
      xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
  

3. Determining Support

If an entity supports sending of DTMF in the XMPP signalling channel as specified herein, it MUST return a Service Discovery [7] feature of "urn:xmpp:jingle:dtmf:0" in response to service discovery information requests.

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 [8]. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

4. Security Considerations

This document introduces no known security vulnerabilities.

5. IANA Considerations

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

6. XMPP Registrar Considerations

7. XML Schema

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

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

  <xs:element name='dtmf'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='code'
                        type='DTMFString'
                        use='required'/>
          <xs:attribute name='duration'
                        type='xs:nonNegativeInteger'
                        use='optional'
                        default='100'/>
          <xs:attribute name='volume'
                        type='VolumeDigit'
                        use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name="DTMFString">
    <xs:restriction base="xs:string">
      <xs:pattern value="(#|\*|0|1|2|3|4|5|6|7|8|9|A|B|C|D)" />
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="VolumeDigit">
    <xs:restriction base="xs:integer">
      <xs:minInclusive value="0"/>
      <xs:maxInclusive value="63"/>
    </xs:restriction>
  </xs:simpleType>

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

</xs:schema>
  

8. Acknowledgements

Thanks to Diana Cionoiu, Olivier Crête, Robert McQueen, and Paul Witty for their feedback. Several sentences were borrowed from RFC 4733.

Appendices

Appendix A: Document Information

Series: XEP
Number: 0181
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.12
Last Updated: 2009-10-02
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0166
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
Source Control: HTML  RSS
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 3920) and XMPP IM (RFC 3921) 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