tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 6231

 
 
 

An Interactive Voice Response (IVR) Control Package for the Media Control Channel Framework

Part 2 of 6, p. 11 to 34
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 11 
4.  Element Definitions

   This section defines the XML elements for this package.  The elements
   are defined in the XML namespace specified in Section 8.2.

   The root element is <mscivr> (Section 4.1).  All other XML elements
   (requests, responses, and notification elements) are contained within
   it.  Child elements describe dialog management (Section 4.2) and
   audit (Section 4.4) functionality.  The IVR dialog element (contained
   within dialog management elements) is defined in Section 4.3.
   Response status codes are defined in Section 4.5 and type definitions
   in Section 4.6.

   Implementation of this Control Package MUST address the Security
   Considerations described in Section 7.

Top      Up      ToC       Page 12 
   Implementation of this Control Package MUST adhere to the syntax and
   semantics of XML elements defined in this section and the schema
   (Section 5).  Since XML schema is unable to support some types of
   syntactic constraints (such as attribute and element co-occurrence),
   some elements in this package specify additional syntactic
   constraints in their textual definition.  If there is a difference in
   constraints between the XML schema and the textual description of
   elements in this section, the textual definition takes priority.

   The XML schema supports extensibility by allowing attributes and
   elements from other namespaces.  Implementations MAY support
   additional capabilities by means of attributes and elements from
   other (foreign) namespaces.  Attributes and elements from foreign
   namespaces are not described in this section.

   Some elements in this Control Package contain attributes whose value
   is a URI.  These elements include: <dialogprepare> (Section 4.2.1),
   <dialogstart> (Section 4.2.2), <media> (Section 4.3.1.5), <grammar>
   (Section 4.3.1.3.1), and <record> (Section 4.3.1.4).  The MS MUST
   support both HTTP [RFC2616] and HTTPS [RFC2818] protocol schemes for
   fetching and uploading resources, and the MS MAY support other
   schemes.  The implementation SHOULD support storage of authentication
   information as part of its configuration, including security
   certificates for use with HTTPS.  If the implementation wants to
   support user authentication, user certifications and passwords can
   also be stored as part of its configuration or the implementation can
   extend the schema (adding, for example, an http-password attribute in
   its own namespace) and then map user authentication information onto
   the appropriate headers following the HTTP authentication model
   [RFC2616].

   Some elements in this Control Package contain attributes whose value
   is descriptive text primarily for diagnostic use.  The implementation
   can indicate the language used in the descriptive text by means of a
   'desclang' attribute ([RFC2277], [RFC5646]).  The desclang attribute
   can appear on the root element as well as selected subordinate
   elements (see Section 4.1).  The desclang attribute value on the root
   element applies to all desclang attributes in subordinate elements
   unless the subordinate element has an explicit desclang attribute
   that overrides it.

   Usage examples are provided in Section 6.

4.1.  <mscivr>

   The <mscivr> element has the following attributes (in addition to
   standard XML namespace attributes such as xmlns):

Top      Up      ToC       Page 13 
   version:  a string specifying the mscivr package version.  The value
      is fixed as '1.0' for this version of the package.  The attribute
      is mandatory.

   desclang:  specifies the language used in descriptive text attributes
      of subordinate elements (unless the subordinate element provides a
      desclang attribute that overrides the value for its descriptive
      text attributes).  The descriptive text attributes on subordinate
      elements include: the reason attribute on <response>
      (Section 4.2.4), <dialogexit> (Section 4.2.5.1), and
      <auditresponse> (Section 4.4.2); desc attribute on <variabletype>
      and <format> (Section 4.4.2.2.5.1).  A valid value is a language
      identifier (Section 4.6.11).  The attribute is optional.  The
      default value is i-default (BCP 47 [RFC5646]).

   The <mscivr> element has the following defined child elements, only
   one of which can occur:

   1.  dialog management elements defined in Section 4.2:

       <dialogprepare>  prepare a dialog.  See Section 4.2.1.

       <dialogstart>  start a dialog.  See Section 4.2.2.

       <dialogterminate>  terminate a dialog.  See Section 4.2.3.

       <response>  response to a dialog request.  See Section 4.2.4.

       <event>  dialog or subscription notification.  See Section 4.2.5.

   2.  audit elements defined in Section 4.4:

       <audit>  audit package capabilities and managed dialogs.  See
          Section 4.4.1.

       <auditresponse>  response to an audit request.  See
          Section 4.4.2.

   For example, a request to the MS to start an IVR dialog playing a
   prompt:

Top      Up      ToC       Page 14 
   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogstart connectionid="ssd3r3:sds345b">
     <dialog>
      <prompt>
       <media loc="http://www.example.com/welcome.wav"/>
      </prompt>
     </dialog>
    </dialogstart>
   </mscivr>

   and a response from the MS that the dialog started successfully:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <response status="200" dialogid="d1"/>
   </mscivr>

   and finally a notification from the MS indicating that the dialog
   exited upon completion of playing the prompt:

  <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr"
          desclang="en">
   <event dialogid="d1">
    <dialogexit status="1" reason="successful completion of the dialog">
     <promptinfo termmode="completed"/>
    </dialogexit>
   </event>
  </mscivr>

   The language of the descriptive text in the reason attribute of
   <dialogexit> is explicitly indicated by the desclang attribute of the
   <mscivr> root element.

4.2.  Dialog Management Elements

   This section defines the dialog management XML elements for this
   Control Package.  These elements are divided into requests,
   responses, and notifications.

   Request elements are sent to the MS to request a specific dialog
   operation to be executed.  The following request elements are
   defined:

   <dialogprepare>:  prepare a dialog for later execution

   <dialogstart>:  start a (prepared) dialog on a connection or
      conference

   <dialogterminate>:  terminate a dialog

Top      Up      ToC       Page 15 
   Responses from the MS describe the status of the requested operation.
   Responses are specified in a <response> element (Section 4.2.4) that
   includes a mandatory attribute describing the status in terms of a
   numeric code.  Response status codes are defined in Section 4.5.  The
   MS MUST respond to a request message with a response message.  If the
   MS is not able to process the request and carry out the dialog
   operation, the request has failed and the MS MUST indicate the class
   of failure using an appropriate 4xx response code.  Unless an error
   response code is specified for a class of error within this section,
   implementations follow Section 4.5 in determining the appropriate
   status code for the response.

   Notifications are sent from the MS to provide updates on the status
   of a dialog or operations defined within the dialog.  Notifications
   are specified in an <event> element (Section 4.2.5).

Top      Up      ToC       Page 16 
                             +---------+
                             |  IDLE   |
                             +---------+
                               |     |
                               |     |
               <dialogprepare>/|     |<dialogstart>/
                               |     |
           +---------+         |     |             +---------+
  +-----<--|         |<--------+     +------------>|         |+------>-+
  | +-<----|PREPARING|                             |STARTING |         |
  | |      |         |                 ----------->|         |---->--+ |
  | |      +---------+                /            +---------+       | |
  | |           |                    /                  |            | |
  | |           |/200 response      /      /200 response|            | |
  | |           |                  /                    |            | |
  | |           |                 /                     |            | |
  | |           |                /                      |            | |
  V V           v               /<dialogstart>/         v            | |
  | |      +---------+         /                   +---------+       | |
  | |      |         |--------+               +----|         |       | |
  | |      |PREPARED |---------+              |    | STARTED |       | |
  | |      |         |         |              +--->|         |       | |
  | |      |         |--------+| <dialogterminate>/|         |       | |
  | |      +---------+        ||  200 response     +---------+       | |
  | |                         ||                    |                | |
  | | /dialogexit notification||                    |                | |
  | |           (timeout)     ||                    |                | |
  | |                         ||                    |                | |
  | |                         ||                    |                | |
  | |                         ||                    |                | |
  | |                         ||<dialogterminate>/  |                | |
  | |                         ||  200 response      |                | |
  | |                         ||       +            |/dialogexit     | |
  | |                         || /dialogexit        | notification   | |
  | |                         || notification       |                | |
  | |                         ||                    |                | |
  | |                         vv                    |                | |
  | |      /ERROR response  +-----------+           |                | |
  | +---------------------->|           |<----------+ /ERROR response| |
  +------------------------>|TERMINATED |<---------------------------+ |
       <dialogterminate>/   |           |<-----------------------------+
           410 response     +-----------+ <dialogterminate>/410 response

                        Figure 1: Dialog Lifecycle

   The MS implementation MUST adhere to the dialog lifecycle shown in
   Figure 1, where each dialog has the following states:

Top      Up      ToC       Page 17 
   IDLE:  the dialog is uninitialized.

   PREPARING:  the dialog is being prepared.  The dialog is assigned a
      valid dialog identifier (see below).  If an error occurs, the
      dialog transitions to the TERMINATED state and the MS MUST send a
      response indicating the error.  If the dialog is terminated before
      preparation is complete, the dialog transitions to the TERMINATED
      state and the MS MUST send a 410 response (Section 4.5) for the
      prepare request.

   PREPARED:  the dialog has been successfully prepared and the MS MUST
      send a 200 response indicating the prepare operation was
      successful.  If the dialog is terminated, then the MS MUST send a
      200 response, the dialog transitions to the TERMINATED state and
      the MS MUST send a dialogexit notification event (see
      Section 4.2.5.1).  If the duration the dialog remains in the
      PREPARED state exceeds the maximum preparation duration, the
      dialog transitions to the TERMINATED state and the MS MUST send a
      dialogexit notification with the appropriate error status code
      (see Section 4.2.5.1).  A maximum preparation duration of 300s is
      RECOMMENDED.

   STARTING:  the dialog is being started.  If the dialog has not
      already been prepared, it is first prepared and assigned a valid
      dialog identifier (see below).  If an error occurs the dialog
      transitions to the TERMINATED state and the MS MUST send a
      response indicating the error.  If the dialog is terminated, the
      dialog transitions to the TERMINATED state and the MS MUST send a
      410 response (Section 4.5) for the start request.

   STARTED:  the dialog has been successfully started and is now active.
      The MS MUST send a 200 response indicating the start operation was
      successful.  If any dialog events occur that were subscribed to,
      the MS MUST send a notifications when the dialog event occurs.
      When the dialog exits (due to normal termination, an error, or a
      terminate request), the MS MUST send a dialogexit notification
      event (see Section 4.2.5.1) and the dialog transitions to the
      TERMINATED state.

   TERMINATED:  the dialog is terminated and its dialog identifier is no
      longer valid.  Dialog notifications MUST NOT be sent for this
      dialog.

   Each dialog has a valid identifier until it transitions to a
   TERMINATED state.  The dialog identifier is assigned by the MS unless
   the <dialogprepare> or <dialogstart> request already specifies a

Top      Up      ToC       Page 18 
   identifier (dialogid) that is not associated with any other dialog on
   the MS.  Once a dialog is in a TERMINATED state, its dialog
   identifier is no longer valid and can be reused for another dialog.

   The identifier is used to reference the dialog in subsequent
   requests, responses, and notifications.  In a <dialogstart> request,
   the dialog identifier can be specified in the prepareddialogid
   attribute indicating the prepared dialog to start.  In
   <dialogterminate> and <audit> requests, the dialog identifier is
   specified in the dialogid attribute, indicating which dialog is to be
   terminated or audited, respectively.  If these requests specify a
   dialog identifier already associated with another dialog on the MS,
   the MS sends a response with a 405 status code (see Section 4.5) and
   the same dialogid as in the request.  The MS MUST specify a dialog
   identifier in notifications associated with the dialog.  The MS MUST
   specify a dialog identifier in responses unless it is a response to a
   syntactically invalid request.

   For a given dialog, the <dialogprepare> or <dialogstart> request
   elements specify the dialog content to execute either by including
   inline a <dialog> element (the dialog language defined in this
   package; see Section 4.3) or by referencing an external dialog
   document (a dialog language defined outside this package).  When
   referencing an external dialog document, the request element contains
   a URI reference to the remote document (specifying the dialog
   definition) and, optionally, a type attribute indicating the MIME
   media type associated with the dialog document.  Consequently, the
   dialog language associated with a dialog on the MS is identified
   either inline by a <dialog> child element or by a src attribute
   referencing a document containing the dialog language.  The MS MUST
   support inline the IVR dialog language defined in Section 4.3.  The
   MS MAY support other dialog languages by reference.

4.2.1.  <dialogprepare>

   The <dialogprepare> request is sent to the MS to request preparation
   of a dialog.  Dialog preparation consists of (a) retrieving an
   external dialog document and/or external resources referenced within
   an inline <dialog> element and (b) validating the dialog document
   syntactically and semantically.

   A prepared dialog is executed when the MS receives a <dialogstart>
   request referencing the prepared dialog identifier (see
   Section 4.2.2).

   The <dialogprepare> element has the following attributes:

Top      Up      ToC       Page 19 
   src:  specifies the location of an external dialog document to
      prepare.  A valid value is a URI (see Section 4.6.9).  The MS MUST
      support both HTTP [RFC2616] and HTTPS [RFC2818] schemes and the MS
      MAY support other schemes.  If the URI scheme is unsupported, the
      MS sends a <response> with a 420 status code (Section 4.5).  If
      the document cannot be retrieved within the timeout interval, the
      MS sends a <response> with a 409 status code.  If the document
      contains a type of dialog language that the MS does not support,
      the MS sends a <response> with a 421 status code.  The attribute
      is optional.  There is no default value.

   type:  specifies the type of the external dialog document indicated
      in the 'src' attribute.  A valid value is a MIME media type (see
      Section 4.6.10).  If the URI scheme used in the src attribute
      defines a mechanism for establishing the authoritative MIME media
      type of the media resource, the value returned by that mechanism
      takes precedence over this attribute.  The attribute is optional.
      There is no default value.

   maxage:  Used to set the max-age value of the 'Cache-Control' header
      in conjunction with an external dialog document fetched using
      HTTP, as per [RFC2616].  A valid value is a non-negative integer
      (see Section 4.6.4).  The attribute is optional.  There is no
      default value.

   maxstale:  Used to set the max-stale value of the 'Cache-Control'
      header in conjunction with an external dialog document fetched
      using HTTP, as per [RFC2616].  A valid value is a non-negative
      integer (see Section 4.6.4).  The attribute is optional.  There is
      no default value.

   fetchtimeout:  the maximum timeout interval to wait when fetching an
      external dialog document.  A valid value is a Time Designation
      (see Section 4.6.7).  The attribute is optional.  The default
      value is 30s.

   dialogid:  string indicating a unique name for the dialog.  If a
      dialog with the same name already exists on the MS, the MS sends a
      <response> with a 405 status code (Section 4.5).  If this
      attribute is not specified, the MS MUST create a unique name for
      the dialog (see Section 4.2 for dialog identifier assignment).
      The attribute is optional.  There is no default value.

   The <dialogprepare> element has the following sequence of child
   elements:

   <dialog>  an IVR dialog (Section 4.3) to prepare.  The element is
      optional.

Top      Up      ToC       Page 20 
   <params>:  specifies input parameters (Section 4.2.6) for dialog
      languages defined outside this specification.  The element is
      optional.  If a parameter is not supported by the MS for the
      external dialog language, the MS sends a <response> with a 427
      status code (Section 4.5).

   The dialog to prepare can be specified either inline with a <dialog>
   child element or externally (for dialog languages defined outside
   this specification) using the src attribute.  It is a syntax error if
   both an inline <dialog> element and a src attribute are specified and
   the MS sends a <response> with a 400 status code (see Section 4.5).
   The type, maxage, maxstale, and fetchtimeout attributes are only
   relevant when a dialog is specified as an external document.

   For example, a <dialogprepare> request to prepare an inline IVR
   dialog with a single prompt:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogprepare>
     <dialog>
      <prompt>
       <media loc="http://www.example.com/welcome.wav"/>
      </prompt>
     </dialog>
    </dialogprepare>
   </mscivr>

   In this example, a request with a specified dialogid to prepare a
   VoiceXML dialog document located externally:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogprepare dialogid="d2" type="application/voicexml+xml"
                   src="http://www.example.com/mydialog.vxml"
                   fetchtimeout="15s"/>
   </mscivr>

   Since MS support for dialog languages other than the IVR dialog
   language defined in this package is optional, if the MS does not
   support the dialog language, it would send a response with the status
   code 421 (Section 4.5).  Further information on using VoiceXML can be
   found in Section 9.

4.2.2.  <dialogstart>

   The <dialogstart> element is sent to the MS to start a dialog.  If
   the dialog has not been prepared, the dialog is prepared (retrieving
   external document and/or external resources referenced within
   <dialog> element and the dialog document validated syntactically and

Top      Up      ToC       Page 21 
   semantically).  Media processors (e.g., DTMF and prompt queue) are
   activated and associated with the specified connection or conference.

   The <dialogstart> element has the following attributes:

   src:  specifies the location of an external dialog document to start.
      A valid value is a URI (see Section 4.6.9).  The MS MUST support
      both HTTP [RFC2616] and HTTPS [RFC2818] schemes and the MS MAY
      support other schemes.  If the URI scheme is unsupported, the MS
      sends a <response> with a 420 status code (Section 4.5).  If the
      document cannot be retrieved with the timeout interval, the MS
      sends a <response> with a 409 status code.  If the document
      contains a type of dialog language that the MS does not support,
      the MS sends a <response> with a 421 status code.  The attribute
      is optional.  There is no default value.

   type:  specifies the type of the external dialog document indicated
      in the 'src' attribute.  A valid value is a MIME media type (see
      Section 4.6.10).  If the URI scheme used in the src attribute
      defines a mechanism for establishing the authoritative MIME media
      type of the media resource, the value returned by that mechanism
      takes precedence over this attribute.  The attribute is optional.
      There is no default value.

   maxage:  Used to set the max-age value of the 'Cache-Control' header
      in conjunction with an external dialog document fetched using
      HTTP, as per [RFC2616].  A valid value is a non-negative integer
      (see Section 4.6.4).  The attribute is optional.  There is no
      default value.

   maxstale:  Used to set the max-stale value of the 'Cache-Control'
      header in conjunction with an external dialog document fetched
      using HTTP, as per [RFC2616].  A valid value is a non-negative
      integer (see Section 4.6.4).  The attribute is optional.  There is
      no default value.

   fetchtimeout:  the maximum timeout interval to wait when fetching an
      external dialog document.  A valid value is a Time Designation
      (see Section 4.6.7).  The attribute is optional.  The default
      value is 30s.

   dialogid:  string indicating a unique name for the dialog.  If a
      dialog with the same name already exists on the MS, the MS sends a
      <response> with a 405 status code (Section 4.5).  If neither the
      dialogid attribute nor the prepareddialogid attribute is
      specified, the MS MUST create a unique name for the dialog (see
      Section 4.2 for dialog identifier assignment).  The attribute is
      optional.  There is no default value.

Top      Up      ToC       Page 22 
   prepareddialogid:  string identifying a dialog previously prepared
      using a dialogprepare (Section 4.2.1) request.  If neither the
      dialogid attribute nor the prepareddialogid attribute is
      specified, the MS MUST create a unique name for the dialog (see
      Section 4.2 for dialog identifier assignment).  The attribute is
      optional.  There is no default value.

   connectionid:  string identifying the SIP dialog connection on which
      this dialog is to be started (see Appendix A.1 of [RFC6230]).  The
      attribute is optional.  There is no default value.

   conferenceid:  string identifying the conference on which this dialog
      is to be started (see Appendix A.1 of [RFC6230]).  The attribute
      is optional.  There is no default value.

   Exactly one of the connectionid or conferenceid attributes MUST be
   specified.  If both the connectionid and conferenceid attributes are
   specified or neither is specified, it is a syntax error and the MS
   sends a <response> with a 400 status code (Section 4.5).

   It is an error if the connection or conference referenced by a
   specific connectionid or conferenceid attribute is not available on
   the MS at the time the <dialogstart> request is executed.  If an
   invalid connectionid is specified, the MS sends a <response> with a
   407 status code (Section 4.5).  If an invalid conferenceid is
   specified, the MS sends a <response> with a 408 status code.

   The <dialogstart> element has the following sequence of child
   elements:

   <dialog>:  specifies an IVR dialog (Section 4.3) to execute.  The
      element is optional.

   <subscribe>:  specifies subscriptions to dialog events
      (Section 4.2.2.1).  The element is optional.

   <params>:  specifies input parameters (Section 4.2.6) for dialog
      languages defined outside this specification.  The element is
      optional.  If a parameter is not supported by the MS for the
      external dialog language, the MS sends a <response> with a 427
      status code (Section 4.5).

   <stream>:  determines the media stream(s) associated with the
      connection or conference on which the dialog is executed
      (Section 4.2.2.2).  The <stream> element is optional.  Multiple
      <stream> elements can be specified.

Top      Up      ToC       Page 23 
   The dialog to start can be specified either (a) inline with a
   <dialog> child element, (b) externally using the src attribute (for
   dialog languages defined outside this specification), or (c) by
   referencing a previously prepared dialog using the prepareddialogid
   attribute.  If exactly one of the src attribute, the
   prepareddialogid, or a <dialog> child element is not specified, it is
   a syntax error and the MS sends a <response> with a 400 status code
   (Section 4.5).  If the prepareddialogid and dialogid attributes are
   specified, it is also a syntax error and the MS sends a <response>
   with a 400 status code.  The type, maxage, maxstale, and fetchtimeout
   attributes are only relevant when a dialog is specified as an
   external document.

   The <stream> element provides explicit control over which media
   streams on the connection or conference are used during dialog
   execution.  For example, if a connection supports both audio and
   video streams, a <stream> element could be used to indicate that only
   the audio stream is used in receive mode.  In cases where there are
   multiple media streams of the same type for a dialog, the AS MUST use
   <stream> elements to explicitly specify the configuration.  If no
   <stream> elements are specified, then the default media configuration
   is that defined for the connection or conference.

   If a <stream> element is in conflict (a) with another <stream>
   element, (b) with specified connection or conference media
   capabilities, or (c) with a Session Description Protocol (SDP) label
   value as part of the connectionid (see Appendix A.1 of [RFC6230]),
   then the MS sends a <response> with a 411 status code (Section 4.5).
   If the media stream configuration is not supported by the MS, then
   the MS sends a <response> with a 428 status code (Section 4.5).

   The MS MAY support multiple, simultaneous dialogs being started on
   the same connection or conference.  For example, the same connection
   can receive different media streams (e.g., audio and video) from
   different dialogs, or receive (and implicitly mix where appropriate)
   the same type of media streams from different dialogs.  If the MS
   does not support starting another dialog on the same connection or
   conference, it sends a <response> with a 432 status code
   (Section 4.5) when it receives the second (or subsequent) dialog
   request.

   For example, a request to start an ivr dialog on a connection
   subscribing to DTMF notifications:

Top      Up      ToC       Page 24 
   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogstart connectionid="connection1">
     <dialog>
      <prompt>
       <media loc="http://www.example.com/getpin.wav"/>
      </prompt>
      <collect maxdigits="2"/>
     </dialog>
    <subscribe>
     <dtmfsub matchmode="all"/>
    </subscribe>
    </dialogstart>
   </mscivr>

   In this example, the dialog is started on a conference where the
   conference only receives an audio media stream from the dialog:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogstart conferenceid="conference1">
     <dialog>
      <record maxtime="384000s"/>
     </dialog>
     <stream media="audio" direction="recvonly"/>
    </dialogstart>
   </mscivr>

4.2.2.1.  <subscribe>

   The <subscribe> element allows the AS to subscribe to, and be
   notified of, specific events that occur during execution of the
   dialog.  Notifications of dialog events are delivered using the
   <event> element (see Section 4.2.5).

   The <subscribe> element has no attributes.

   The <subscribe> element has the following sequence of child elements
   (0 or more occurrences):

   <dtmfsub>:  Subscription to DTMF input during the dialog
      (Section 4.2.2.1.1).  The element is optional.

   If a request has a <subscribe> with no child elements, the MS treats
   the request as if no <subscribe> element were specified.

   The MS MUST support <dtmfsub> subscription for the IVR dialog
   language defined in this specification (Section 4.3).  It MAY support
   other dialog subscriptions (specified using attributes and child
   elements from a foreign namespace).  If the MS does not support a

Top      Up      ToC       Page 25 
   subscription specified in a foreign namespace, the MS sends a
   response with a 431 status code (see Section 4.5).

4.2.2.1.1.  <dtmfsub>

   The <dtmfsub> element has the following attributes:

   matchmode:  controls which DTMF input is subscribed to.  Valid values
      are "all" - notify all DTMF key presses received during the
      dialog; "collect" - notify only DTMF input matched by the collect
      operation (Section 4.3.1.3); and "control" - notify only DTMF
      input matched by the runtime control operation (Section 4.3.1.2).
      The attribute is optional.  The default value is "all".

   The <dtmfsub> element has no child elements.

   DTMF notifications are delivered in the <dtmfnotify> element
   (Section 4.2.5.2).

   For example, the AS wishes to subscribe to DTMF key press matching a
   runtime control:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogstart dialogid="d3" connectionid="connection1">
     <dialog>
      <prompt>
       <media loc="http://www.example.com/getpin.wav"/>
      </prompt>
      <control ffkey="2" rwkey="3"/>
     </dialog>
    <subscribe>
     <dtmfsub matchmode="control"/>
    </subscribe>
    </dialogstart>
   </mscivr>

   Each time a '2' or '3' DTMF input is received, the MS sends a
   notification event:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <event dialogid="d3">
      <dtmfnotify matchmode="collect" dtmf="2"
          timestamp="2008-05-12T12:13:14Z"/>
    </event>
   </mscivr>

Top      Up      ToC       Page 26 
4.2.2.2.  <stream>

   The <stream> element has the following attributes:

   media:  a string indicating the type of media associated with the
      stream.  A valid value is a MIME type-name as defined in Section
      4.2 of [RFC4288].  The following values MUST be used for common
      types of media: "audio" for audio media, and "video" for video
      media.  See [IANA] for registered MIME type names.  The attribute
      is mandatory.

   label:  a string indicating the SDP label associated with a media
      stream [RFC4574].  The attribute is optional.

   direction:  a string indicating the direction of the media flow
      relative to the endpoint conference or connection.  Defined values
      are "sendrecv" (the endpoint can send media to, and receive media
      from, the dialog), "sendonly" (the endpoint can only send media to
      the dialog), "recvonly" (the endpoint can only receive media from
      the dialog), and "inactive" (stream is not to be used).  The
      default value is "sendrecv".  The attribute is optional.

   The <stream> element has the following sequence of child elements:

   <region>:  an element to specify the area within a mixer video layout
      where a media stream is displayed (Section 4.2.2.2.1).  The
      element is optional.

   <priority>:  an element to configure priority associated with the
      stream in the conference mix (Section 4.2.2.2.2).  The element is
      optional.

   If conferenceid is not specified or if the "media" attribute does not
   have the value of "video", then the MS ignores the <region> and
   <priority> elements.

   For example, assume a User Agent connection with multiple audio and
   video streams associated with the user and a separate web camera.  In
   this case, the dialog could be started to record only the audio and
   video streams associated with the user:

Top      Up      ToC       Page 27 
   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogstart connectionid="connection1">
     <dialog>
      <record maxtime="384000s"/>
     </dialog>
     <stream media="audio" label="camaudio" direction="inactive"/>
     <stream media="video" label="camvideo" direction="inactive"/>
     <stream media="audio" label="useraudio" direction="sendonly"/>
     <stream media="video" label="uservideo" direction="sendonly"/>
    </dialogstart>
   </mscivr>

   Using the <region> element, the dialog can be started on a conference
   mixer so that the video output from the dialog is directed to a
   specific area within a video layout.  For example:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogstart conferenceid="conference1">
     <dialog>
      <prompt>
        <media loc="http://www.example.com/presentation.3gp"/>
      </prompt>
     </dialog>
     <stream media="video" direction="recvonly">
       <region>1</region>
     </stream>
    </dialogstart>
   </mscivr>

4.2.2.2.1.  <region>

   The <region> element is used to specify a named area within a
   presentation layout where a video media stream is displayed.  The MS
   could, for example, play video media into an area of a video layout
   where the layout and its named regions are specified using the Mixer
   Control Package [MIXER-CP].

   The <region> element has no attributes and its content model
   specifies the name of the region.

   If the region name is invalid, then the MS reports a 416 status code
   (Section 4.5) in the response to the request element containing the
   <region> element.

4.2.2.2.2.  <priority>

   The <priority> element is used to explicitly specify the priority of
   the dialog for presentation in a conference mix.

Top      Up      ToC       Page 28 
   The <priority> element has no attributes and its content model
   specifies a positive integer (see Section 4.6.5).  The lower the
   value, the higher the priority.

4.2.3.  <dialogterminate>

   A dialog can be terminated by sending a <dialogterminate> request
   element to the MS.

   The <dialogterminate> element has the following attributes:

   dialogid:  string identifying the dialog to terminate.  If the
      specified dialog identifier is invalid, the MS sends a response
      with a 405 status code (Section 4.5).  The attribute is mandatory.

   immediate:  indicates whether or not a dialog in the STARTED state is
      to be terminated immediately (in other states, termination is
      always immediate).  A valid value is a boolean (see
      Section 4.6.1).  A value of true indicates that the dialog is
      terminated immediately and the MS MUST send a dialogexit
      notification (Section 4.2.5.1) without report information.  A
      value of false indicates that the dialog terminates after the
      current iteration and the MS MUST send a dialogexit notification
      with report information.  The attribute is optional.  The default
      value is false.

   The MS MUST reply to the <dialogterminate> request with a <response>
   element (Section 4.2.4), reporting whether or not the dialog was
   terminated successfully.

   For example, immediately terminating a STARTED dialog with dialogid
   "d4":

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogterminate dialogid="d4" immediate="true"/>
   </mscivr>

   If the dialog is terminated successfully, then the response to the
   dialogterminate request would be:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <response status="200" dialogid="d4"/>
   </mscivr>

4.2.4.  <response>

   Responses to dialog management requests are specified with a
   <response> element.

Top      Up      ToC       Page 29 
   The <response> element has following attributes:

   status:  numeric code indicating the response status.  Valid values
      are defined in Section 4.5.  The attribute is mandatory.

   reason:  string specifying a reason for the response status.  The
      attribute is optional.  There is no default value.

   desclang:  specifies the language used in the value of the reason
      attribute.  A valid value is a language identifier
      (Section 4.6.11).  The attribute is optional.  If not specified,
      the value of the desclang attribute on <mscivr> (Section 4.1)
      applies.

   dialogid:  string identifying the dialog.  If the request specifies a
      dialogid, then that value is used.  Otherwise, with
      <dialogprepare> and <dialogstart> requests, the dialogid generated
      by the MS is used.  If there is no available dialogid because the
      request is syntactically invalid (e.g., a <dialogterminate>
      request with no dialogid attribute specified), then the value is
      the empty string.  The attribute is mandatory.

   connectionid:  string identifying the SIP dialog connection
      associated with the dialog (see Appendix A.1 of [RFC6230]).  The
      attribute is optional.  There is no default value.

   conferenceid:  string identifying the conference associated with the
      dialog (see Appendix A.1 of [RFC6230]).  The attribute is
      optional.  There is no default value.

   For example, a response when a dialog was prepared successfully:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <response status="200" dialogid="d5"/>
   </mscivr>

   The response if dialog preparation failed due to an unsupported
   dialog language:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <response status="421" dialogid="d5"
       reason="Unsupported dialog language: application/voicexml+xml"/>
   </mscivr>

   In this example, a <dialogterminate> request does not specify a
   dialogid:

Top      Up      ToC       Page 30 
   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <dialogterminate/>
   </mscivr>

   The response status indicates a 400 (Syntax error) status code and
   the dialogid attribute has an empty string value:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <response status="400" dialogid=" "
       reason="Attribute required: dialogid"/>
   </mscivr>

4.2.5.  <event>

   When a dialog generates a notification event, the MS sends the event
   using an <event> element.

   The <event> element has the following attributes:

   dialogid:  string identifying the dialog that generated the event.
      The attribute is mandatory.

   The <event> element has the following child elements, only one of
   which can occur:

   <dialogexit>:  indicates that the dialog has exited
      (Section 4.2.5.1).

   <dtmfnotify>:  indicates that a DTMF key press occurred
      (Section 4.2.5.2).

4.2.5.1.  <dialogexit>

   The <dialogexit> event indicates that a prepared or active dialog has
   exited because it is complete, it has been terminated, or an error
   occurred during execution (for example, a media resource cannot be
   played).  This event MUST be sent by the MS when the dialog exits.

   The <dialogexit> element has the following attributes:

   status:  a status code indicating the status of the dialog when it
      exits.  A valid value is a non-negative integer (see
      Section 4.6.4).  The MS MUST support the following values:

      0  indicates the dialog has been terminated by a <dialogterminate>
         request.

      1  indicates successful completion of the dialog.

Top      Up      ToC       Page 31 
      2  indicates the dialog terminated because the connection or
         conference associated with the dialog has terminated.

      3  indicates the dialog terminated due to exceeding its maximum
         duration.

      4  indicates the dialog terminated due to an execution error.

      All other valid but undefined values are reserved for future use,
      where new status codes are assigned using the Standards Action
      process defined in [RFC5226].  The AS MUST treat any status code
      it does not recognize as being equivalent to 4 (dialog execution
      error).  The attribute is mandatory.

   reason:  a textual description that the MS SHOULD use to provide a
      reason for the status code, e.g., details about an error.  A valid
      value is a string (see Section 4.6.6).  The attribute is optional.
      There is no default value.

   desclang:  specifies the language used in the value of the reason
      attribute.  A valid value is a language identifier
      (Section 4.6.11).  The attribute is optional.  If not specified,
      the value of the desclang attribute on <mscivr> (Section 4.1)
      applies.

   The <dialogexit> element has the following sequence of child
   elements:

   <promptinfo>:  report information (Section 4.3.2.1) about the prompt
      execution in an IVR <dialog>.  The element is optional.

   <controlinfo>:  reports information (Section 4.3.2.2) about the
      control execution in an IVR <dialog>.  The element is optional.

   <collectinfo>:  reports information (Section 4.3.2.3) about the
      collect execution in an IVR <dialog>.  The element is optional.

   <recordinfo>:  reports information (Section 4.3.2.4) about the record
      execution in an IVR <dialog>.  The element is optional.

   <params>:  reports exit parameters (Section 4.2.6) for a dialog
      language defined outside this specification.  The element is
      optional.

   For example, when an active <dialog> exits normally, the MS sends a
   dialogexit <event> reporting information:

Top      Up      ToC       Page 32 
   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <event dialogid="d6">
     <dialogexit status="1">
      <collectinfo dtmf="1234"  termmode="match"/>
     </dialogexit>
    </event>
   </mscivr>

4.2.5.2.  <dtmfnotify>

   The <dtmfnotify> element provides a notification of DTMF input
   received during the active dialog as requested by a <dtmfsub>
   subscription (Section 4.2.2.1).

   The <dtmfnotify> element has the following attributes:

   matchmode:  indicates the matching mode specified in the subscription
      request.  Valid values are as follows:

         "all" - all DTMF key presses notified individually;

         "collect" - only DTMF input matched by the collect operation
         notified; and

         "control" - only DTMF input matched by the control operation
         notified.

      The attribute is optional.  The default value is "all".

   dtmf:  DTMF key presses received according to the matchmode.  A valid
      value is a DTMF string (see Section 4.6.3) with no space between
      characters.  The attribute is mandatory.

   timestamp:  indicates the time (on the MS) at which the last key
      press occurred according to the matchmode.  A valid value is a
      dateTime expression (Section 4.6.12).  The attribute is mandatory.

   For example, a notification of DTMF input matched during the collect
   operation:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <event dialogid="d3">
      <dtmfnotify matchmode="collect" dtmf="3123"
        timestamp="2008-05-12T12:13:14Z"/>
    </event>
   </mscivr>

Top      Up      ToC       Page 33 
4.2.6.  <params>

   The <params> element is a container for <param> elements
   (Section 4.2.6.1).

   The <params> element has no attributes, but the following child
   elements are defined (0 or more):

   <param>:  specifies a parameter name and value (Section 4.2.6.1).

   For example, usage with a dialog language defined outside this
   specification to send additional parameters into the dialog:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
   <dialogstart type="application/x-dialog"
                src="nfs://nas01/dialog4" connectionid="c1">
     <params>
      <param name="mode">playannouncement</param>
      <param name="prompt1">nfs://nas01/media1.3gp</param>
      <param name="prompt2">nfs://nas01/media2.3gp</param>
     </params>
    </dialogstart>
   </mscivr>

4.2.6.1.  <param>

   The <param> element describes a parameter name and value.

   The <param> element has the following attributes:

   name:  a string indicating the name of the parameter.  The attribute
      is mandatory.

   type:  specifies a type indicating how the inline value of the
      parameter is to be interpreted.  A valid value is a MIME media
      type (see Section 4.6.10).  The attribute is optional.  The
      default value is "text/plain".

   encoding:  specifies a content-transfer-encoding schema applied to
      the inline value of the parameter on top of the MIME media type
      specified with the type attribute.  A valid value is a content-
      transfer-encoding schema as defined by the "mechanism" token in
      Section 6.1 of [RFC2045].  The attribute is optional.  There is no
      default value.

   The <param> element content model is the value of the parameter.
   Note that a value that contains XML characters (e.g., "<") needs to
   be escaped following standard XML conventions.

Top      Up      ToC       Page 34 
   For example, usage with a dialog language defined outside this
   specification to receive parameters from the dialog when it exits:

   <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
    <event dialogid="d6">
     <dialogexit status="1">
     <params>
      <param name="mode">recording</param>
      <param name="recording1" type="audio/x-wav" encoding="base64">
       <![CDATA[
        R0lGODlhZABqALMAAFrMYr/BvlKOVJKOg2xZUKmenMfDw8tgWJpV
       ]]>
      </param>
     </params>
     </dialogexit>
    </event>
   </mscivr>



(page 34 continued on part 3)

Next RFC Part