XEP-0181: Jingle DTMF

This specification defines an XML format for encapsulating Dual Tone Multi-Frequency (DTMF) events in informational messages sent within the context of Jingle audio sessions, e.g. to be used in the context of Interactive Voice Response (IVR) systems.

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.

Document Information

Series: XEP
Number: 0181
Publisher: XMPP Standards Foundation
Status: Proposed
Type: Standards Track
Version: 0.9
Last Updated: 2008-04-18
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0166
Supersedes: None
Superseded By: None
Short Name: TO-BE-ASSIGNED
Wiki Page: <http://wiki.jabber.org/index.php/Jingle DTMF (XEP-0181)>

Author Information

Legal Notices

Discussion Venue

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

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

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.

Conformance Terms

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

Table of Contents

1. Introduction

Traditional telephony systems 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 for interoperability with the public switched telephone network (PSTN).

If XMPP application use Jingle [1] for voice chat (see Jingle Audio via RTP [2]) and wish to exchange DTMF events, they MUST support the protocol described in this document. However, they MAY also support non-XMPP methods of communicating DTMF information, such as the "audio/telephone-event" and "audio/tone" media types as sent over the Real-time Transport Protocol (RFC 3550 [3]).

2. Format

The format for the representation of DTMF events in XMPP is as follows (see Protocol Namespaces regarding issuance of one or more permanent namespaces):

Example 1. Basic DTMF Format

<dtmf xmlns='urn:xmpp:tmp:jingle:dtmf'
      action='[button-down|button-up]'
      code='0-9,#,*,A-D'
      duration='milliseconds'
      volume='0-63'/>
  

The <dtmf/> element SHOULD possess an 'action' attribute, the value of which MUST be either "button-up" or "button-down" (specifying whether the button is being depressed or released). This enables DTMF tones to be reconstructed in real time. If the 'action' attribute is not included, the recipient MUST assume that the action is a "button-down" event.

Unless the 'action' attribute has a value of "button-up", the <dmtf/> element MUST possess a 'code' attribute that specifies the tone to be generated. The value of the 'code' attribute SHOULD be one the following characters: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and * (however, the characters A, B, C, and D MAY be sent as well [4]).

The OPTIONAL 'duration' attribute specifies indicates the duration of the event, in milliseconds, expressed as an unsigned integer. The receiver SHOULD ignore the event if the 'duration' value is zero. If the 'duration' attribute is not included and the event is explicitly or implicitly a "button-down" event, the recipient MUST assume that the event expires after a reasonable timeout (100 milliseconds is RECOMMENDED) or when a "button-up" event is received, whichever comes first.

The OPTIONAL 'volume' attribute specifies the power level of the tone, expressed in dBm0 after dropping the sign. Power levels range from 0 to -63 dBm0. Thus, larger values denote lower volume.

The <dtmf> element SHOULD be sent as the payload of a Jingle session-info message as illustrated in the following example (see Protocol Namespaces regarding issuance of one or more permanent namespaces).

Example 2. Entity Sends DTMF Message

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

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

Example 3. 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 4. Receiving 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 does not understand the specified code, it MUST return a <feature-not-implemented/> stanza error.

Example 5. Receiving 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 6. 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 Jingle DTMF (i.e., sending of DTMF in the XMPP signalling channel as specified herein), it MUST return a Service Discovery [7] feature of "urn:xmpp:tmp:jingle:dtmf" in response to service discovery information requests. Naturally, support MAY also be determined via the dynamic, presence-based profile of Service Discovery defined in Entity Capabilities [8].

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:tmp:jingle:dtmf'
    xmlns='urn:xmpp:tmp:jingle:dtmf'
    elementFormDefault='qualified'>

  <xs:element name='dtmf'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='action' use='optional' default='button-down'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='button-down'/>
                <xs:enumeration value='button-up'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name='code' type='DTMFString' use='required'/>
          <xs:attribute name='duration' type='xs:nonNegativeInteger' use='optional'/>
          <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 Olivier Crête and Paul Witty for their feedback. Several sentences were borrowed from RFC 4733.

Notes

Revision History

END