XEP-0181: Jingle DTMF

This specification defines an XML format for encapsulating Dual Tone Multi-Frequency (DTMF) data 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.8
Last Updated: 2008-03-20
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) 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).

XMPP clients that use Jingle [1] for voice chat (see Jingle Audio via RTP [2]) MUST support the protocol described in this document to exchange DTMF information, although they MAY also support other methods of communicating DTMF information.

2. Tone Format

The format for the XML DTMF representation 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='integer'/>
  

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 and act as if a "button-up" event occurs after a reasonable timeout (100 milliseconds is RECOMMENDED) or when another DMTF event is received.

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. [3]

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'/>
  </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 understand or cannot process the payload, it MUST return a <feature-not-implemented/> stanza error, which SHOULD include a Jingle-specific error condition of <unsupported-info/>.

Example 4. Receiving Does Not Understand DTMF Info Message

<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'/>
    <unsupported-info xmlns='urn:xmpp:tmp:jingle:errors'/>
  </error>
</iq>
  

3. Negotiating the DTMF Method

This specification defines two DTMF methods: sending DTMF natively over the XMPP channel and sending DTMF events or tones over the RTP media channel using RFC 4733 [4]. In particular, some applications may want to stream Jingle voice RTP directly to a non-XMPP entity, such as a SIP phone (see RFC 3261 [5]), in which case the DTMF needs to be sent in the media channel.

To request that the voice session will switch to use of the RFC 4733 format for communicating DTMF, a client sends a <dtmf-method/> element, qualified by the 'urn:xmpp:tmp:jingle:dtmf' namespace as the payload of a Jingle session-info message.

The dtmf-method element MUST contain the 'method' attribute, the value of which SHOULD be either 'rtp' or 'xmpp'.

When specifying use of RFC 4733, the <dtmf-method/> element MUST include a <payload-type/> element whose 'name' attribute has a value of either "telephone-event" or "tone", which correspond to the "audio/telephone-event" and "audio/tone" media types described in RFC 4733.

Example 5. Client Requests Use of RFC 4733

<iq from='juliet@capulet.com/balcony'
    id='dtmf2'
    to='ivr.shakespeare.lit'
    type='set'>
  <jingle xmlns='urn:xmpp:tmp:jingle'
          action='session-info'
          initiator='juliet@capulet.com/balcony'
          sid='a73sjjvkla37jfea'>
    <dtmf-method xmlns='urn:xmpp:tmp:jingle:dtmf' method='rtp'>
      <payload-type clockrate='8000' id='100' name='telephone-event'/>
    </dtmf-method>
  </jingle>
</iq>
  

If the recipient supports the requested DTMF method and payload-type and it wishes to use that method, it MUST send an empty IQ result:

Example 6. Recipient Acknowledges Request

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

If the recipient does not support the requested DTMF method (and, if included, payload-type), it MUST return a <feature-not-implemented/> stanza error, which SHOULD include a DTMF-specific error condition of <unsupported-dtmf-method/>:

Example 7. Recipient Refuses Request

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

Either client can request a switch back to the native XMPP method if desired.

Example 8. Client Requests Use of XMPP Signalling

<iq from='juliet@capulet.com/balcony'
    id='dtmf3'
    to='ivr.shakespeare.lit'
    type='set'>
  <jingle xmlns='urn:xmpp:tmp:jingle'
          action='session-info'
          initiator='juliet@capulet.com/balcony'
          sid='a73sjjvkla37jfea'>
    <dtmf-method xmlns='urn:xmpp:tmp:jingle:dtmf' method='xmpp'/>
  </jingle>
</iq>
  

Since the XMPP method is mandatory-to-implement, the recipient sends an empty IQ result to acknowledge the switch:

Example 9. Recipient Acknowledges Request

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

4. Determining Support

If an entity supports Jingle DTMF (which natively includes sending of DTMF in the XMPP signalling channel), it MUST return a Service Discovery [6] feature of "urn:xmpp:tmp:jingle:dtmf" in response to service discovery information requests.

If an entity also supports sending of DTMF in the content channel, it MUST also return a service discovery feature of "urn:xmpp:jingle:dtmf:rtp" 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 [7].

5. Security Considerations

This document introduces no known security vulnerabilities.

6. IANA Considerations

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

7. XMPP Registrar Considerations

8. 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:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='dtmf-method'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='payload-type' minOccurs='0' maxOccurs='1'/>
      </xs:sequence>
      <xs:attribute name='method' use='required' default='xmpp'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='rtp'/>
            <xs:enumeration value='xmpp'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

  <xs:element name='payload-type'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='clockrate' type='xs:short' use='optional'/>
          <xs:attribute name='id' type='xs:unsignedByte' use='required'/>
        </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='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    

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

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

  <xs:element name='unsupported-dtmf-method' type='empty'/>

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

</xs:schema>
    

9. Acknowledgements

Thanks to Paul Witty for his feedback.

Notes

Revision History

END