RFC 6231
An Interactive Voice Response (IVR) Control Package for the Media Control Channel Framework
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.
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):
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:
<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
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).
+---------+ | 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:
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
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:
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.
<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
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.
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.
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:
<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
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>
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:
<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.
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.
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:
<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.
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:
<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>
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.
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)
