A Basic Interactive Voice Response (IVR) Control Package for the Session Initiation Protocol (SIP)
draft-boulton-ivr-control-package-02

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on April 29, 2007.

Abstract

This document defines a Session Initiation (SIP) Control Package for basic Interactive Voice Response (IVR) interaction. The control of Media Servers and their related resources in decomposed network architectures plays an important role in various Next Generation Networks. This Control Package provides IVR functionality using the SIP Control Framework.

Table of Contents

1.  Introduction
2.  Conventions and Terminology
3.  Control Package Definition
    3.1.  Control Package Name
    3.2.  Framework Message Usage
    3.3.  Common XML Support
    3.4.  CONTROL Message Body
    3.5.  REPORT Message Body
4.  Element Definitions
    4.1.  Requests
        4.1.1.  <dialogprepare>
        4.1.2.  <dialogstart>
        4.1.3.  <dialogterminate>
    4.2.  Responses
        4.2.1.  <response>
    4.3.  Notifications
        4.3.1.  <event>
    4.4.  <data>
    4.5.  <subscribe>
5.  IVR Template Dialogs
    5.1.  Play Announcement
    5.2.  Prompt and Collect
    5.3.  Prompt and Record
    5.4.  Status Codes
    5.5.  Type Definitions
6.  AS-MS Interaction Examples
    6.1.  Starting an IVR dialog
    6.2.  IVR dialog fails to start
    6.3.  Preparing and starting an IVR dialog
    6.4.  Terminating a dialog immediately
    6.5.  Terminating a dialog non-immediately
7.  Template Dialog Examples
    7.1.  playannouncement
    7.2.  promptandcollect
    7.3.  promptandrecord
8.  Formal Syntax
9.  Security Considerations
10.  IANA Considerations
    10.1.  Control Package Registration
    10.2.  URN Sub-Namespace Registration
11.  Change Summary
12.  Acknowledgments
13.  References
    13.1.  Normative References
    13.2.  Informative References
§  Authors' Addresses
§  Intellectual Property and Copyright Statements

1.  Introduction

The SIP Control Framework [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.) provides a generic approach for establishment and reporting capabilities of remotely initiated commands. The Framework utilizes many functions provided by the Session Initiation Protocol [RFC3261] (Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, “SIP: Session Initiation Protocol,” June 2002.) (SIP) for the rendezvous and establishment of a reliable channel for control interactions. The Control Framework also introduces the concept of a Control Package. A Control Package is an explicit usage of the Control Framework for a particular interaction set. This specification defines a package for basic IVR.

The scope of the package is control of media server functions for basic interactive media (e.g. play a prompt, collecting DTMF, recording user input) as well as notifications related to these functions.

These functions and notifications are defined as messages in XML [XML] (Bray, T., Paoli, J., Sperberg-McQueen, C M., Maler, E., and F. Yergeau, “Extensible Markup Language (XML) 1.0 (Third Edition),” February 2004.). The message use XML elements for preparing, starting and stopping dialogs, as well as elements for responses and notifications ([CCXML10] (Auburn, R J., “Voice Browser Call Control: CCXML Version 1.0,” June 2005.), [MSML] (Saleem, A. and G. Sharratt, “Media Session Markup Language (MSML),” June 2006.) and [MSCP] (McGlashan, S., Auburn, R., Burke, D., Candell, E., and R. Surapaneni, “Media Server Control Protocol (MSCP),” July 2006.)).

This basic IVR package uses template dialogs to provide IVR functionality. Three template dialogs are defined:

playannouncement:

a dialog to play one or more prompts to the user

promptandcollect:

a dialog to prompt the user and collect their input

promptandrecord:

a dialog to prompt the user and record their input

Template dialogs are intended to provide basic IVR functionality ([H.248.9] (, “Gateway control protocol: Advanced media server packages,” .), [RFC4240] (Burger, E., Van Dyke, J., and A. Spitzer, “Basic Network Media Services with SIP,” December 2005.), [MSML] (Saleem, A. and G. Sharratt, “Media Session Markup Language (MSML),” June 2006.), [RFC2897] (Cromwell, D., “Proposal for an MGCP Advanced Audio Package,” August 2000.) and [MSCML] (Van Dyke, J., Burger, E., and A. Spitzer, “Media Server Control Markup Language (MSCML) and Protocol,” June 2006.)). The template approach follows previous approaches in that it provides IVR functionality which is commonly required for applications. It differs in that the functionality is expressed in XML using a reference to the template dialog, and parameters expressed in a simple XML data structure. This is a lightweight approach since the contents of the dialog itself does not need to be transported over the control channel (or fetched from an external source), only a template reference plus configuration data is required. From the developer's perspective, this simplifies application development: they do not need to write their IVR dialog using custom XML elements, they only need to reference the template dialog and, if required, populate a simple XML data structure to pass configuration data.

To use a template dialog, the AS developer references it by name in an XML message for preparing or starting a dialog; for example <dialogstart src="promptandrecord"/>. The XML message may also contain template input parameters in a <data> element to configure specific behavior defined by the template dialog; e.g. using "prompts" with the value "http://www.example.com/welcome.wav". If the dialog starts successfully, a <response status="200"/> is returned. When the dialog is completed, the MS returns template output parameters in a dialogexit <event> notification to the AS.

The implementation of template dialogs requires only that they adhere to the syntax and semantics of templates described in this document.

Other control packages MAY be defined which extend the capabilities of the templates dialogs defined in this document. Such control packages MUST respect the syntax and semantics of this control package.

This document specifies how the basic IVR control package fulfils the requirements of the SIP Control Framework control packages (Section 3 (Control Package Definition)), which XML elements are defined by the package (Section 4 (Element Definitions)), the template dialog definitions (Section 5 (IVR Template Dialogs)) as well as providing examples (Section 6 (AS-MS Interaction Examples), Section 7 (Template Dialog Examples)) and an XML schema (Section 8 (Formal Syntax)).

2.  Conventions and Terminology

In this document, BCP 14/RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119] defines the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL". In addition, BCP 15 indicates requirement levels for compliant implementations.

The following additional terms are defined for use in this document:

Dialog:

A dialog performs media interaction with a user. A dialog is identified by a URI and has an associated mimetype. Dialogs typically feature basic capabilities such as playing audio prompts, collecting DTMF input and recording audio input from the user. More advanced dialogs may also feature synthesized speech, recording and playback of video, recognition of spoken input, and mixed initiative conversations.

Application server:

A SIP [RFC3261] (Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, “SIP: Session Initiation Protocol,” June 2002.) application server (AS) hosts and executes services such as interactive media and conferencing in an operator's network. An AS influences and impacts the SIP session, in particular by terminating SIP sessions on a media server, which is under its control.

Media Server:

A media server (MS) processes media streams on behalf of an AS by offering functionality such as interactive media, conferencing, and transcoding to the end user. Interactive media functionality is realized by way of dialogs, which are identified by a URI and initiated by the application server.

3.  Control Package Definition

This section fulfills the mandatory requirement for information that MUST be specified during the definition of a Control Framework Package, as detailed in Section 9 of [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.).

3.1.  Control Package Name

The Control Framework requires a Control Package definition to specify and register a unique name and version.

The name and version of this Control Package is "msc-ivr-basic/1.0" (Media Server Control - Interactive Voice Response - Basic - version 1.0 ).

3.2.  Framework Message Usage

IVR functionality includes capabilities such as playing prompts, collecting DTMF and recording user input. These functions are expressed using template dialogs defined in Section 5 (IVR Template Dialogs).

This package defines XML elements in Section 4 (Element Definitions) and provides an XML Schema in Section 8 (Formal Syntax).

The XML elements in this package are split into requests, responses and event notifications. Requests are carried in CONTROL message bodies; <dialogprepare>, <dialogstart> and <dialogterminate> elements are defined as package requests. Responses are carried either in REPORT message or Control Framework 200 response bodies; the <response> element is defined as a package response. Event notifications are also carried in REPORT message bodies; the <event> element is defined for package event notifications.

Note that package responses are different from framework response codes. Framework error response codes (see Section 8 of [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.)) are used when the request or event notification is invalid; for example, a request is invalid XML (400), or not understood (500). Package responses are carried in 200 response or REPORT message bodies. This package's response codes are defined in Section 4.2.1 (<response>).

The schema uses "connection-id" and "conf-id" attributes which are imported from schema defined in core Control Framework [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.).

3.3.  Common XML Support

The Control Framework requires a Control Package definition to specify if the attributes for media dialog or conference references are required.

This package requires that the XML Schema in Section 16.1 of [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.) MUST be supported for media dialogs and conferences.

3.4.  CONTROL Message Body

A valid CONTROL body message MUST conform to the schema defined in Section 8 (Formal Syntax) and described in Section 4 (Element Definitions). XML messages appearing in CONTROL messages MUST contain a <dialogprepare>, <dialogstart> or <dialogterminate> request element (Section 4.1 (Requests)).

3.5.  REPORT Message Body

A valid REPORT body MUST conform to the schema defined in Section 8 (Formal Syntax) and described in Section 4 (Element Definitions). XML messages appearing in REPORT messages MUST contain a <response> (Section 4.2 (Responses)), or a (notification) <event> element (Section 4.3 (Notifications)).

4.  Element Definitions

This section defines the XML messages for this control package.

[Editors Note: since XML Schema may not be able to express all constraints expressed in these definitions, in cases where there is a difference in constraints, the definitions in the section take priority.]

4.1.  Requests

The following request elements are defined:

<dialogprepare>:

prepare an IVR dialog for later execution

<dialogstart>:

start an IVR dialog on a connection or conference

<dialogterminate>:

terminate an active IVR dialog

4.1.1.  <dialogprepare>

The <dialogprepare> request is sent from the AS to the MS to request preparation of an IVR dialog. A prepared dialog is executed when the AS sends a <dialogstart> request referencing the prepared dialog (see Section 4.1.2 (<dialogstart>)).

A <dialogprepare> element has the following attributes:

src:

string identifying the URI of the dialog document to prepare. The attribute is mandatory. The MS MUST support "playannouncement", "promptandcollect" and "promptandrecord" template dialogs as the value for this attribute.

dialogid:

string indicating a unique name for the dialog. If this attribute is not specified, the MS creates a unique name for the dialog. The value is used in subsequent references to the dialog (e.g. as dialogid in a <response>). It is an error if a dialog with the same name already exists on the MS. The attribute is optional.

The <dialogprepare> element has the following child elements:

<data>:

an XML data structure (see Section 4.4 (<data>)) to pass parameters into the dialog. It is an error if a specified parameter is not supported by the implementation. The element is optional.

<subscribe>:

an XML data structure (see Section 4.5 (<subscribe>)) indicating notification events to which the AS subscribes. It is an error if a specified notification event is not supported by the implementation. The element is optional.

For example, a request to prepare a playannouncement dialog where a single prompt is played once:

<dialogprepare src="playannouncement">
  <data>
     <item name="prompts"
              value="http://www.example.com/prompt1.wav"/>
     <item name="iterations" value="1"/>
  </data>
</dialogprepare>

When an MS has successfully received a <dialogprepare> request, it MUST reply with a <response> element (Section 4.2 (Responses)).

4.1.2.  <dialogstart>

The <dialogstart> element is sent by the AS to request execution of a dialog. The dialog may be defined in the dialogstart request itself, or reference a previously prepared dialog.

The <dialogstart> element has the following attributes:

src:

string identifying the URI of the dialog document to start. The attribute is optional. The MS MUST support playannouncement, promptandcollect and promptandrecord template dialogs as the value for this attribute.

dialogid:

string indicating a unique name for the dialog. If this attribute is not specified, the MS creates a unique name for the dialog. The value is used in subsequent references to the dialog (e.g. as dialogid in a <response>). It is an error if a dialog with the same name already exists on the MS. The attribute is optional.

prepareddialogid:

string identifying a dialog previously prepared using a dialogprepare request. The attribute is optional.

connection-id:

string identifying the SIP dialog connection on which this dialog is to be started (see Section 16.1 of [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.)). The attribute is optional.

conf-id:

string identifying the conference on which this dialog is to be started (see Section 16.1 of [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.)). The attribute is optional.

If the prepareddialogid is specified, it is an error to specify the src or dialogid attributes.

If the prepareddialogid is not specified, exactly the src attribute MUST be specified; otherwise, it is an error.

Exactly one of the connection-id or conf-id attributes MUST be specified. It is an error to specify both connection-id and conf-id.

The <dialogstart> element has the following child elements defined:

<stream>:

contains the following attributes:

media:

a string indicating the type of media associated with the stream. It is strongly recommended that the following values are used for common types of media: "audio" for audio media, and "video" for video media. The attribute is mandatory.

label:

a string indicating the SDP label associated with a media stream ([RFC4574] (Levin, O. and G. Camarillo, “The Session Description Protocol (SDP) Label Attribute,” August 2006.)). The attribute is optional.

direction:

a string indicating the direction of the media flow between a dialog and its end point conference or connection. Defined values are: "sendrecv" (media can be sent and received), "sendonly" (media can only be sent), and "recvonly" (media can only be received). The default value is "sendrecv". The attribute is optional.

One or more <stream> elements may be specified so that individual media streams can be controlled independently; for example, audio only for transmission, but video only for reception. The <stream> element is optional. If no <stream> elements are specified, then the default is the media configuration of the connection or conference. It is an error if a <stream> element is in conflict with (a) another <stream> element, (b) with dialog, connection or conference media capabilities, or (c) with a SDP label value as part of the connection-id (see Section 16.1 of [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.)).

<data>:

an XML data structure (see Section 4.4 (<data>)) to pass parameters into the dialog. It is an error if a specified parameter is not supported by the implementation. The element is optional.

<subscribe>:

an XML data structure (see Section 4.5 (<subscribe>)) indicating notification events to which the AS subscribes. It is an error if a specified notification event is not supported by the implementation.The element is optional.

[Editors Note: the <stream> element assumes that the use of the SDP label by itself is insufficent for media stream control. In particular, the SDP label does not address directionality, nor does it address conferences. Further investigation of the <stream> is is required.]

If the prepareddialogid is specified and the <dialogprepare> contained a <data> element, it is an error to specify it in <dialogstart>. Likewise, If the prepareddialogid is specified and the <dialogprepare> contained a <subscribe> element, it is an error to specify it in <dialogstart>.

For example, a request to start a promptandrecord template dialog on a conference:

 <dialogstart conf-id="conference11" src="playandrecord">
    <data>
      <item name="maxtime" value="384000s"/>
    </data>
 </dialogstart>

When an MS has successfully received a <dialogstart> request, it MUST reply with a <response> element (Section 4.2 (Responses)).

4.1.3.  <dialogterminate>

A dialog that has been successfully prepared or started can be terminated by a <dialogterminate> request element from the AS.

The <dialogterminate> element has the following attributes:

dialogid:

string identifying an existing dialog. The attribute is mandatory.

immediate:

string with the values "true" or "false" indicating whether the dialog is to be terminated immediately or not. If a dialog is terminated immediately, no further dialog event notifications are sent (including a dialogexit <event>). The default is "false". The attribute is optional.

For example, assuming a dialog with the dialogid "vxi1" has been started, it can be terminated immediately with the following request:

<dialogterminate dialogid="vxi1" immediate="true"/>

When an MS has successfully received a <dialogterminate> request, it MUST reply with a <response> element (Section 4.2 (Responses)).

4.2.  Responses

Responses are specified in a <response> element.

4.2.1.  <response>

Reponses to requests are indicated by a <response> element.

The <response> element has following attributes:

status:

numeric code indicating the response status. The attribute is mandatory.

reason:

string specifying a reason for the response status. The attribute is optional.

dialogid:

string identifying the dialog. The attribute is optional.

connection-id:

string identifying the SIP dialog connection associated with the dialog (see Section 16.1 of [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.)). The attribute is optional.

conf-id:

string identifying the conference associated with the dialog (see Section 16.1 of [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.)). The attribute is optional.

The following status codes are defined:

[Editors Note: more status codes may need to be defined.]

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

<response status="200" dialogid="vxi1"/>

The response if dialog preparation failed due to an unknown template:

 <response status="409" dialogid="vxi1"
    reason="Unknown template: promptandrecod"/>

For example, a response when the dialog was started successfully.

 <response status="200" dialogid="vxi1"
              connection-id="7HDY839~HJKSkyHS"/>

4.3.  Notifications

Event notifications are specified in an <event> element.

4.3.1.  <event>

Dialog event notifications are either manual or automatic.

Manual event notifications are defined when an AS subscribes to notifications for dialog events using the <subscribe> element of <dialogprepare> or <dialogstart>.

Automatic event notifications are defined as part of a Control Package. The AS SHOULD NOT subscribe to these event notifications. The MS MUST support these event notifications. This package defines one automatic notification event: "dialogexit" which indicates that an active dialog has terminated. Note that this notification is not sent if the dialog has been terminated by the AS using a <dialogterminate/> request where "immediate=true".

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

The <event> element has the following attributes:

name:

string indicating the name of dialog event. The string is restricted to a sequence of alphanumeric or "." characters. The attribute is mandatory.

dialogid:

string identifying the dialog. The attribute is mandatory.

The <event> element has the following child element:

<data>:

an XML data structure (see Section 4.4 (<data>)) to pass information additional information about the dialog event. The element is optional.

For example, when a dialog exits the MS may send a dialogexit <event> with data indicating the status of a template dialog:

<event name="dialogexit" dialogid="vxi1">
 <data>
   <item name="status" value="1"/>
 </data>
</event>

4.4.  <data>

The <data> element is a general container for parameterized data.

The <data> element has no attributes, but has the following child elements defined:

<item>:

contains the following attributes:

name:

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

value:

a string indicating the value of the parameter. Multiple values of a parameters can be specified using space separation. The attribute is mandatory.

Multiple <item> elements may be specified.

For example, a <data> specifying promptandcollect template parameters with simple values:

<data>
   <item name="iterations" value="5"/>
   <item name="timeout" value="10s"/>
</data>

In this example, a <data> specifying a playannouncement template with a complex value for the prompts parameter:

<data>
 <item name="prompts" value="http://example.com/balance.wav
          http://example.com/five.wav http://example.com/euros.wav"/>
</data>

[Editors Note: we may also want to investigate the use of <item>s nested within a top-level <item> to specify complex values. ]

4.5.  <subscribe>

The <subscribe> element is a container for specifying dialog notification events to which an AS subscribes. Notifications of dialog events are delivered using the <event> element (see Section 4.3.1 (<event>)).

The <subscribe> element has no attributes, but has the following child elements defined:

<notify>:

contains the following attributes:

name:

a string indicating the name of the event to be notified of. The attribute is mandatory.

The <notify> element may have a <data> child element.

Multiple <notify> elements may be specified.

For example, the AS wishes to subscribe to DTMF and bargein notification events associated with a dialog:

<dialogstart src="promptandcollect"
     connection-id="7HDY839~HJKSkyHS~HUwkuh7ns">
 <subscribe>
    <notify name="dtmf"/>
    <notify name="bargein"/>
  </subscribe>
</dialogstart>

If the MS supports these notification events, then it would use the <event> element to send notifications during the dialog to the AS when the events occured.

[Editors Note: It may be possible to define a general event subscription mechanism as part of the SIP Control Framework.]

[Editors Note: This Control Package does not specify dialog notification events apart from "dialogexit". Later versions may define events such as: "dtmf" (a DTMF key is pressed), "mediastart" (media playback started), "bargein" (user has barged in on a prompt), and "rtpcontrol" (control data, e.g. VFU, PoC, etc, is received over the RTP control channel.]

5.  IVR Template Dialogs

The execution of IVR template dialog takes place on the MS. The AS specifies the name of the template and configuration parameters, and receives the result from the MS after the dialog has been executed.

Input parameters are used to configure and customize the behavior of the template. For many input parameters, the templates provide default values; a developer can specify an alternative value if the default is not appropriate for their application. Input parameters for templates may be mandatory, requiring a specific value to be provided.

The result of executing a template dialog is reported to the AS using output parameters. These parameters may describe status information, error information or information collected from the user. Output parameters are mandatory or optional depending on the specific template; mandatory parameters must be specified by the implementation.

Template dialogs are invoked by referencing them in the src attribute of <dialogprepare> (Section 4.1.1 (<dialogprepare>)) or <dialogstart> (Section 4.1.2 (<dialogstart>)). Input parameters are specified in the <data> child element (Section 4.4 (<data>)) of these elements. Output parameters are specified in the <data> child element of a dialogexit <event> notification (Section 4.3.1 (<event>)). The detailed mapping of template dialogs to XML CONTROL and REPORT messages is described in Section 3 (Control Package Definition) and examples are provided in Section 7 (Template Dialog Examples).

The implementation of template dialogs MUST adhere to the syntax and semantics of templates described in this document. Implementations MAY support additional parameters of the defined template dialogs. Implementations MAY support additional template dialogs. The actual implementation may be based on any technology or scripting language.

The media requirements on the template implementation are restricted to the capability to play audio prompts (specified as URI (URI)s), collect DTMF input, and record audio input. The implementation MUST support G.711 audio formats (headerless and wav) for playback and recording. The implementation MAY support other media formats.

[Editors Note: Later versions may consider additional media requirements including TTS, ASR, video, etc. ]

5.1.  Play Announcement

A template dialog to play announcements to the user.

The template dialog is invoked using the URI "playannouncement".

The dialog execution model consists of:

1. Playing prompts (prompts) in the order specified until completion.
2. Repeating step 1 for the value of iterations (iterations).
3. Returning status (status) and reason (reason) parameters.

The input and output parameters are summarized and defined below.

Note that playannouncement requires at least one prompt specified in prompts (prompts).

The following additional input parameters are under consideration for later versions:

5.2.  Prompt and Collect

A template dialog to play prompts and collect DTMF input.

The dialog is invoked with the URI "promptandcollect".

The dialog execution model consists of:

1. Clearing the digit buffer depending on the value of cleardigitbuffer (cleardigitbuffer).
2. Playing prompts (prompts) in the order specified. The bargein (bargein) parameter determines whether user input can be collected during prompt playback stops (if so, prompt playback is stopped).
3. Collecting DTMF input from the user. Valid DTMF patterns are either a simple digit string where the maximum length is determined by maxdigits (maxdigits) and may be terminated by the character in termchar (termchar); or a custom DTMF grammar specified by grammar (grammar). The parameters timeout (timeout), interdigittimeout (interdigittimeout) and termtimeout (termtimeout) control user input timeout, interdigit timeout and the terminating timeout respectively.
4. If no input is collected or the input is invalid, steps 1 - 3 are repeated for the value of iterations (iterations).
5. Returning status (status), reason (reason) and result (result) parameters.

The input and output parameter are summarized and defined below.

[Editors note: The format of the custom DTMF grammar is not yet defined. Possibilities include: [SRGS] (Hunt, A. and S. McGlashan, “Speech Recognition Grammar Specification Version 1.0,” March 2004.), [H.248.1] (, “Gateway control protocol: Version 3,” .), and [KPML] (Burger, E. and M. Dolly, “A Session Initiation Protocol (SIP) Event Package for Key Press Stimulus (KPML),” July 2006.). If more than one format is permitted, then an additional input parameter "grammartype" would indicate the format used in the grammar parameter.]

In addition to the prompt extensions described in Table 7 (Additional playannouncement parameters), the following parameters are under consideration for later versions:

5.3.  Prompt and Record

A template dialog to prompt the user and record their audio input.

The dialog is invoked with the URI "promptandrecord".

The dialog execution model consists of:

1. Playing prompts (prompts) in the order specified until completion.
2. Recording audio input from the user. Recording is initiated if user input is received before timeout (timeout) expires. The recording is terminated by DTMF input, the maximum duration being exceeded or a final silence after recording, as specified in dtmfterm (dtmfterm), maxtime (maxtime) and finalsilence (finalsilence) parameters respectively.
3. If recording is not initiated, steps 1 - 2 are repeated for the value of iterations (iterations).
4. Returning status (status), reason (reason) and result (result) parameters.

The input and output parameter are summarized and defined below.

In addition to the prompt extensions described in Table 7 (Additional playannouncement parameters), the following additional parameters are under consideration for a later version.

5.4.  Status Codes

The following table describes the codes returned in the status output parameter for template dialogs.

5.5.  Type Definitions

This section defines types referenced in template parameters.

5.5.1.  Boolean

The value space of boolean is the set {true, false}.

5.5.2.  DTMFChar

A DTMF character. The value space is the set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *, A, B, C, D}.

5.5.3.  DTMFString

A String composed of one or more DTMFChar (DTMFChar)s.

5.5.4.  Non-Negative Integer

The value space of non-negative integer is the infinite set {0,1,2,...}.

5.5.5.  Positive Integer

The value space of positive integer is the infinite set {1,2,...}.

5.5.6.  String

A string in the character encoding associated with the XML element.

5.5.7.  Time Designation

A time designation consists of a non-negative real number followed by a time unit identifier.

The time unit identifiers are: "ms" (milliseconds) and "s" (seconds).

Examples include: "3s", "850ms", "0.7s", ".5s" and "+1.5s".

5.5.8.  URI

Uniform Resource Indicator as defined in [RFC2396] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifiers (URI): Generic Syntax,” August 1998.).

5.5.9.  URIList

A list of URI (URI)s.

6.  AS-MS Interaction Examples

The following example assume a control channel has been established as described in the SIP Control Framework [SIPCF] (Boulton, C., Melanchuk, T., McGlashan, S., and A. Shiratzky, “A Control Framework for the Session Initiation Protocol (SIP),” October 2006.).

The XML messages are in angled brackets; the REPORT status is in round brackets. Other aspects of the protocol are omitted for readability.

6.1.  Starting an IVR dialog

An IVR dialog is started successfully, and dialogexit notification <event> is sent from the MS to the AS when the dialog exits normally.

          Application Server (AS)                   Media Server (MS)
             |                                             |
             |       (1) CONTROL: <dialogstart>            |
             |  ---------------------------------------->  |
             |                                             |
             |       (2) 202                               |
             |  <---------------------------------------   |
             |                                             |
             |       (3) REPORT: (pending)                 |
             |  <----------------------------------------  |
             |                                             |
             |       (4) 200                               |
             |  ---------------------------------------->  |
             |                                             |
             |       (5) REPORT: <response status="200"/>  |
             |                   (terminate)               |
             |  <----------------------------------------  |
             |                                             |
             |       (6) 200                               |
             |  ---------------------------------------->  |
             |                                             |
             |       (7) REPORT:<event name="dialogexit"/> |
             |                   (notify)                  |
             |  <----------------------------------------  |
             |                                             |
             |       (8) 200                               |
             |  ---------------------------------------->  |
             |                                             |

6.2.  IVR dialog fails to start

An IVR dialog fails to start due to an unknown template.

          Application Server (AS)                   Media Server (MS)
             |                                             |
             |       (1) CONTROL: <dialogstart>            |
             |  ---------------------------------------->  |
             |                                             |
             |       (2) 202                               |
             |  <---------------------------------------   |
             |                                             |
             |       (3) REPORT: (pending)                 |
             |  <----------------------------------------  |
             |                                             |
             |       (4) 200                               |
             |  ---------------------------------------->  |
             |                                             |
             |       (5) REPORT: <response status="409"/>  |
             |                   (terminate)               |
             |  <----------------------------------------  |
             |                                             |
             |       (6) 200                               |
             |  ---------------------------------------->  |
             |                                             |

6.3.  Preparing and starting an IVR dialog

An IVR dialog is prepared and started successfully, and then the dialog exits normally.

          Application Server (AS)                   Media Server (MS)
             |                                             |
             |       (1) CONTROL: <dialogprepare>          |
             |  ---------------------------------------->  |
             |                                             |
             |       (2) 202                               |
             |  <---------------------------------------   |
             |                                             |
             |       (3) REPORT: (pending)                 |
             |  <----------------------------------------  |
             |                                             |
             |       (4) 200                               |
             |  ---------------------------------------->  |
             |                                             |
             |       (5) REPORT: <response status="200"/>  |
             |                   (terminate)               |
             |  <----------------------------------------  |
             |                                             |
             |       (6) 200                               |
             |  ---------------------------------------->  |
             |                                             |
             |       (7) CONTROL: <dialogstart>            |
             |  ---------------------------------------->  |
             |                                             |
             |       (8) 202                               |
             |  <---------------------------------------   |
             |                                             |
             |       (9) REPORT: (pending)                 |
             |  <----------------------------------------  |
             |                                             |
             |       (10) 200                              |
             |  --------------------------------------->   |
             |                                             |
             |       (11) REPORT: <response status="200"/> |
             |                   (terminate)               |
             |  <----------------------------------------  |
             |                                             |
             |       (12) 200                              |
             |  ---------------------------------------->  |
             |                                             |
             |       (13) REPORT:<event name="dialogexit"/>|
             |                   (notify)                  |
             |  <----------------------------------------  |
             |                                             |
             |       (14) 200                              |
             |  ---------------------------------------->  |
             |                                             |

6.4.  Terminating a dialog immediately

An IVR dialog is started successfully, and then terminated immediately by the AS. No dialog notification <event>s are sent back to the AS.

          Application Server (AS)                   Media Server (MS)
             |                                             |
             |       (1) CONTROL: <dialogstart>            |
             |  ---------------------------------------->  |
             |                                             |
             |       (2) 202                               |
             |  <---------------------------------------   |
             |                                             |
             |       (3) REPORT: (pending)                 |
             |  <----------------------------------------  |
             |                                             |
             |       (4) 200                               |
             |  ---------------------------------------->  |
             |                                             |
             |       (5) REPORT: <response status="200"/>  |
             |                   (terminate)               |
             |  <----------------------------------------  |
             |                                             |
             |       (6) 200                               |
             |  ---------------------------------------->  |
             |                                             |
             |       (7) CONTROL: <dialogterminate>        |
             |  ---------------------------------------->  |
             |                                             |
             |       (8) 200: <response status="200"/>     |
             |  <----------------------------------------  |
             |                                             |

Note that in (8) the response to the <dialogterminate/> request is carried on a framework 200 response.

6.5.  Terminating a dialog non-immediately

An IVR dialog is started successfully, and then terminated non-immediately by the AS, allowing the MS to send a dialogexit notification <event> with information collected during the dialog.

          Application Server (AS)                   Media Server (MS)
             |                                             |
             |       (1) CONTROL: <dialogstart>            |
             |  ---------------------------------------->  |
             |                                             |
             |       (2) 202                               |
             |  <---------------------------------------   |
             |                                             |
             |       (3) REPORT: (pending)                 |
             |  <----------------------------------------  |
             |                                             |
             |       (4) 200                               |
             |  ---------------------------------------->  |
             |                                             |
             |       (5) REPORT: <response status="200"/>  |
             |                   (terminate)               |
             |  <----------------------------------------  |
             |                                             |
             |       (6) 200                               |
             |  ---------------------------------------->  |
             |                                             |
             |       (7) CONTROL: <dialogterminate>        |
             |  ---------------------------------------->  |
             |                                             |
             |       (8) 200: <response status="200"/>     |
             |  <----------------------------------------  |
             |                                             |
             |       (9) REPORT:<event name="dialogexit"/> |
             |                   (notify)                  |
             |  <----------------------------------------  |
             |                                             |
             |       (10) 200                              |
             |  ---------------------------------------->  |
             |                                             |

Note that in (8) the response to the <dialogterminate/> request is carried on a framework 200 response.

7.  Template Dialog Examples

The following examples show how playannouncement, promptandcollect and promptandrecord template dialogs are used with <dialogprepare>, <dialogstart> and <event> elements.

The examples do not specify all messages between the AS and MS.

7.1.  playannouncement

This example prepares an announcement composed of two prompts.

<dialogprepare src="playannouncement">
    <data>
       <item name="prompts"
             value="http://www.example.com/media/Number_09.wav
                    http://www.example.com/media/Number_11.wav"/>
       <item name="iterations" value="2"/>
    </data>
</dialogprepare>

If the dialog is prepared successfully, a dialogprepared message is returned:

<response status="200" dialogid="vxi78"/>

The prepared dialog is then started on a conference playing the prompts twice:

<dialogstart prepareddialogid="vxi78" conf-id="conference11"/>

In the case of a successful dialog, the output is provided in <event>; for example

<event name="dialogexit" dialogid="vxi78">
    <data>
       <item name="status" value="1"/>
    </data>
</event>

In this example, the dialog is started on a sip dialog connection, but no <data> is specified:

<dialogstart src="playannouncement"
             connection-id="7HDY839~HJKSkyHS~HUwkuh7ns"/>

and an error message is returned:

<event name="dialogexit" dialogid="vxi79">
    <data>
       <item name="status" value="602"/>
       <item name="reason" value="prompts not defined"/>
    </data>
</event>

7.2.  promptandcollect

This example plays no prompts and just waits for input from the user:

<dialogstart src="promptandcollect"
             connection-id="7HDY839~HJKSkyHS~HUwkuh7ns"/>

If the dialog is successful, then "dialogexit" <event> contains the dtmf collected in its result parameter:

<event name="dialogexit" dialogid="vxi80">
    <data>
       <item name="status" value="1"/>
       <item name="result" value="12345"/>
    </data>
</event>

In this example, a prompt is played and then we wait for 3 hours for a two digit sequence:

<dialogstart src="promptandcollect"
             connection-id="7HDY839~HJKSkyHS~HUwkuh7ns">
 <data>
  <item name="prompts" value="http://www.example.com/prompt1.wav"/>
  <item name="timeout" value="1080s"/>
  <item name="maxdigits" value="2"/>
  <item name="iterations" value="1"/>
 </data>
</dialogstart>

If no user input is collected within 3 hours, then following would be returned:

<event name="dialogexit" dialogid="vxi81">
    <data>
       <item name="status" value="603"/>
    </data>
</event>

And finally in this example, one of the input parameters is invalid:

<dialogstart src="promptandcollect"
             connection-id="7HDY839~HJKSkyHS~HUwkuh7ns">
 <data>
   <item name="prompts" value="http://www.example.com/prompt1.wav"/>
   <item name="iterations" value="two"/>
   <item name="cleardigitbuffer" value="true"/>
   <item name="bargein" value="true"/>
   <item name="timeout" value="4s"/>
   <item name="interdigittimeout" value="2s"/>
   <item name="termtimeout" value="0s"/>
   <item name="maxdigits" value="2"/>
 </data>
</dialogstart>

The error is reported in a dialogexit <event>:

<event name="dialogexit" dialogid="vxi82">
    <data>
       <item name="status" value="601"/>
       <item name="reason" value="iterations invalid: two"/>
    </data>
</event>

7.3.  promptandrecord

In this example, the user is prompted, then their input is recorded for a maximum of 30 seconds.

<dialogstart src="promptandrecord"
             connection-id="7HDY839~HJKSkyHS~HUwkuh7ns">
    <data>
       <item name="prompts"
             value="http://www.example.com/media/sayname.wav
                    http://www.example.com/media/beep.wav"/>
       <item name="dtmfterm" value="false"/>
       <item name="maxtime" value="30s"/>
    </data>
</dialogstart>

If successful, the following is returned in a dialogexit <event>:

<event name="dialogexit" dialogid="vxi83">
 <data>
  <item name="status" value="1"/>
  <item name="result" value="http://www.example.com/recording1.wav"/>
 </data>
</event>

8.  Formal Syntax

[Editors Note: A later version of the XML schema will provide more constraints as expressed in the textual definitions; for example, single occurrence of <data> elements, co-occurence on attributes, etc.]

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="urn:ietf:params:xml:ns:msc-ivr-basic"
xmlns:fw="urn:ietf:params:xml:ns:control:framework-attributes"
elementFormDefault="qualified"
xmlns="urn:ietf:params:xml:ns:msc-ivr-basic"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

 <xsd:annotation>
  <xsd:documentation>Basic IVR 1.0 schema (20061019)</xsd:documentation>
 </xsd:annotation>

   <xsd:import
    namespace="urn:ietf:params:xml:ns:control:framework-attributes"
   schemaLocation="framework.xsd"/>

 <xsd:element name="dialogprepare">
  <xsd:complexType>
   <xsd:choice minOccurs="0" maxOccurs="unbounded">
    <xsd:element ref="data"/>
    <xsd:element ref="subscribe"/>
    <xsd:any namespace="##other" processContents="strict"/>
   </xsd:choice>
   <xsd:attribute name="src" type="URI.datatype" use="required"/>
   <xsd:attribute name="dialogid" type="dialogid.datatype"/>
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>

 </xsd:element>

 <xsd:element name="dialogstart">
  <xsd:complexType>
   <xsd:choice minOccurs="0" maxOccurs="unbounded">
    <xsd:element ref="stream"/>
    <xsd:element ref="data"/>
    <xsd:element ref="subscribe"/>
    <xsd:any namespace="##other" processContents="strict"/>
   </xsd:choice>
   <xsd:attribute name="src" type="URI.datatype"/>
   <xsd:attribute name="dialogid" type="dialogid.datatype"/>
   <xsd:attribute name="prepareddialogid" type="dialogid.datatype"/>
   <xsd:attributeGroup ref="fw:framework-attributes"/>
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>
 </xsd:element>

 <xsd:element name="dialogterminate">
  <xsd:complexType>
   <xsd:choice minOccurs="0" maxOccurs="unbounded">
    <xsd:any namespace="##other" processContents="strict"/>
   </xsd:choice>
   <xsd:attribute name="dialogid" type="dialogid.datatype"
       use="required"/>
   <xsd:attribute name="immediate" type="boolean.datatype"
       default="false"/>
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>
 </xsd:element>


 <xsd:element name="response">
  <xsd:complexType>
   <xsd:choice minOccurs="0" maxOccurs="unbounded">
    <xsd:any namespace="##other" processContents="strict"/>
   </xsd:choice>
   <xsd:attribute name="status" type="status.datatype"
       use="required"/>
   <xsd:attribute name="reason" type="xsd:string"/>
   <xsd:attribute name="dialogid" type="dialogid.datatype"/>
   <xsd:attributeGroup ref="fw:framework-attributes"/>
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>
 </xsd:element>


 <xsd:element name="event">
  <xsd:complexType>
   <xsd:choice minOccurs="0" maxOccurs="unbounded">
    <xsd:element ref="data"/>
    <xsd:any namespace="##other" processContents="strict"/>
   </xsd:choice>
   <xsd:attribute name="name" type="eventname.datatype"
       use="required"/>
   <xsd:attribute name="dialogid" type="dialogid.datatype"
       use="required"/>
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>
 </xsd:element>



 <!-- DATATYPES -->

    <xsd:simpleType name="URI.datatype">
        <xsd:restriction base="xsd:anyURI"/>
    </xsd:simpleType>

    <xsd:simpleType name="dialogid.datatype">
        <xsd:restriction base="xsd:string"/>
    </xsd:simpleType>

 <xsd:simpleType name="boolean.datatype">
  <xsd:restriction base="xsd:NMTOKEN">
   <xsd:enumeration value="true"/>
   <xsd:enumeration value="false"/>
  </xsd:restriction>
 </xsd:simpleType>


 <xsd:simpleType name="eventname.datatype">
  <xsd:restriction base="xsd:NMTOKEN">
   <xsd:pattern value="[a-zA-Z0-9\.]+"/>
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="status.datatype">
  <xsd:restriction base="xsd:NMTOKEN">
   <xsd:pattern value="[0-9][0-9][0-9]"/>
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="media.datatype">
    <xsd:restriction base="xsd:string"/>
 </xsd:simpleType>

 <xsd:simpleType name="label.datatype">
    <xsd:restriction base="xsd:string"/>
 </xsd:simpleType>

 <xsd:simpleType name="direction.datatype">
  <xsd:restriction base="xsd:NMTOKEN">
   <xsd:enumeration value="sendrecv"/>
   <xsd:enumeration value="sendonly"/>
   <xsd:enumeration value="recvonly"/>
  </xsd:restriction>
 </xsd:simpleType>


 <!-- SHARED ELEMENTS -->

 <xsd:element name="data">
  <xsd:complexType>
   <xsd:choice minOccurs="0" maxOccurs="unbounded">
    <xsd:element ref="item"/>
    <xsd:any namespace="##other" processContents="strict"/>
   </xsd:choice>
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>
 </xsd:element>

 <xsd:element name="item">
  <xsd:complexType>
   <xsd:attribute name="name" type="xsd:string"
       use="required"/>
   <xsd:attribute name="value" type="xsd:string"
       use="required"/>
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>
 </xsd:element>


 <xsd:element name="stream">
  <xsd:complexType>
   <xsd:choice minOccurs="0" maxOccurs="unbounded">
    <xsd:any namespace="##other" processContents="strict"/>
   </xsd:choice>
   <xsd:attribute name="media" type="media.datatype"
       use="required"/>
   <xsd:attribute name="label" type="label.datatype"/>
   <xsd:attribute name="direction" type="direction.datatype"
                  default="sendrecv" />
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>
 </xsd:element>


 <xsd:element name="subscribe">
  <xsd:complexType>
   <xsd:choice minOccurs="0" maxOccurs="unbounded">
    <xsd:element ref="notify"/>
   </xsd:choice>
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>
 </xsd:element>

 <xsd:element name="notify">
  <xsd:complexType>
   <xsd:choice minOccurs="0" maxOccurs="1">
    <xsd:element ref="data"/>
   </xsd:choice>
   <xsd:attribute name="name" type="xsd:string" use="required"/>
   <xsd:anyAttribute namespace="##other" processContents="strict"/>
  </xsd:complexType>
 </xsd:element>

</xsd:schema>

9.  Security Considerations

Security Considerations to be included in later versions of this document.

10.  IANA Considerations

This document registers a new SIP Control Framework Package and a new XML namespace.

10.1.  Control Package Registration

Control Package name: msc-ivr-basic/1.0

10.2.  URN Sub-Namespace Registration

XML namespace: urn:ietf:params:xml:ns:msc-ivr-basic

11.  Change Summary

The following are the major changes between the -02 of the draft and the -01 version.

• added version 1.0 to package name
• separate section for element definitions
• dialogterminate treated as request rather than notification
• simplified responses: single element <response>
• removed response elements: <dialogprepared>, <dialogstarted>, <errordialognotprepared>, <errordialognotstarted>
• simplified event notifications to single <event> element carried in a REPORT
• <dialogexit> element replaced with <event name="dialogexit">
• removed <dialoguser> element
• added <stream> element as child of <dialogstart>
• removed 'type' attribute from <dialogprepare> and <dialogstart>
• added dialogid attribute to <dialogprepare> and <dialogstart>
• removed template "Sample Implementation" section
• renamed <namelist> to <data>
• re-organized so that template details after general package framework and element description.

The following are the primary changes between the -01 of the draft and the -00 version.

• Removed requirement for VoiceXML dialog support
• Added requirement for template dialog support

12.  Acknowledgments

The authors would like to thank Adnan Saleem of Convedia and Gene Shtirmer of Intel for useful review of this work.

13.  References

13.1. Normative References

13.2. Informative References

Authors' Addresses

Full Copyright Statement

Copyright © The IETF Trust (2006).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.