RFC 6231
An Interactive Voice Response (IVR) Control Package for the Media Control Channel Framework
An Interactive Voice Response (IVR) Control Package for the Media Control Channel Framework 🎀
okay bestie, let's start with the title block 💅 this is RFC 6231, published in May 2011 as a Standards Track document 🔥 It's from the IETF (Internet Engineering Task Force), and the ISSN is 2070-1721 ✨
Three authors wrote it:
- S. McGlashan from Hewlett-Packard 💜
- T. Melanchuk from Rainwillow 🦋
- C. Boulton from NS-Technologies 🌸
The title block doesn't list anything this RFC obsoletes or updates, so it stands on its own 🧚
Abstract
okay so the whole point of this doc is a Media Control Channel Framework Package for IVR (Interactive Voice Response) dialogs 📞✨ that's the stuff where a computer talks to you and asks you to press buttons, and it works on media connections and conferences 🎧
the package gives you dialog management request elements for preparing, starting, and terminating a dialog, plus the responses and notifications that go with them 💖 the dialogs themselves are written in a dialog language 🎀
this package also ships its own lightweight IVR dialog language 😭 it covers prompt playback, runtime controls, Dual-Tone Multi-Frequency (DTMF) collection, and media recording 🔥 but other dialog languages are allowed too, so it's not a one-language situation 🌈
lastly, there are elements for auditing what the package can do and for auditing IVR dialogs 💅 iconic, honestly 👑
Status of This Memo
this is an Internet Standards Track document ⭐
it's a product of the IETF, which means it reflects the consensus of the IETF community 🫶 it got public review and was approved for publication by the Internet Engineering Steering Group (IESG) ✨ if you want more on Internet Standards, check out Section 2 of RFC 5741 🦋
for the current status, any errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc6231 💜
Copyright Notice
copyright (c) 2011 IETF Trust and the persons identified as the document authors 🎀 all rights reserved 💅
this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which you can read at http://trustee.ietf.org/license-info 🌸 those rules are in effect on the publication date, so please read them carefully because they explain your rights and restrictions 🙈
any Code Components pulled out of this document need to include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions 🔥 they come with no warranty, same as the Simplified BSD License says 🫶
some of the material here came from IETF Documents or IETF Contributions published (or made publicly available) before November 10, 2008 🍓 the people who control the copyright on some of that stuff may not have given the IETF Trust permission to allow modifications outside the IETF Standards Process 😭 so unless you get a proper license from them, this document can't be modified outside the IETF Standards Process, and derivative works can't be made outside it either 🌈 the one exception is formatting it for publication as an RFC or translating it into languages other than English ✨
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 8
3. Control Package Definition . . . . . . . . . . . . . . . . . 9
3.1. Control Package Name . . . . . . . . . . . . . . . . . . 9
3.2. Framework Message Usage . . . . . . . . . . . . . . . . . 9
3.3. Common XML Support . . . . . . . . . . . . . . . . . . . 10
3.4. CONTROL Message Body . . . . . . . . . . . . . . . . . . 10
3.5. REPORT Message Body . . . . . . . . . . . . . . . . . . . 10
3.6. Audit . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . 11
4. Element Definitions . . . . . . . . . . . . . . . . . . . . . 11
4.1. <mscivr> . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2. Dialog Management Elements . . . . . . . . . . . . . . . 14
4.2.1. <dialogprepare> . . . . . . . . . . . . . . . . . . . 18
4.2.2. <dialogstart> . . . . . . . . . . . . . . . . . . . . 20
4.2.2.1. <subscribe> . . . . . . . . . . . . . . . . . . . 24
4.2.2.1.1. <dtmfsub> . . . . . . . . . . . . . . . . . . 25
4.2.2.2. <stream> . . . . . . . . . . . . . . . . . . . . 26
4.2.2.2.1. <region> . . . . . . . . . . . . . . . . . . 27
4.2.2.2.2. <priority> . . . . . . . . . . . . . . . . . 27
4.2.3. <dialogterminate> . . . . . . . . . . . . . . . . . . 28
4.2.4. <response> . . . . . . . . . . . . . . . . . . . . . 28
4.2.5. <event> . . . . . . . . . . . . . . . . . . . . . . . 30
4.2.5.1. <dialogexit> . . . . . . . . . . . . . . . . . . 30
4.2.5.2. <dtmfnotify> . . . . . . . . . . . . . . . . . . 32
4.2.6. <params> . . . . . . . . . . . . . . . . . . . . . . 33
4.2.6.1. <param> . . . . . . . . . . . . . . . . . . . . . 33
4.3. IVR Dialog Elements . . . . . . . . . . . . . . . . . . . 34
4.3.1. <dialog> . . . . . . . . . . . . . . . . . . . . . . 35
4.3.1.1. <prompt> . . . . . . . . . . . . . . . . . . . . 38
4.3.1.1.1. <variable> . . . . . . . . . . . . . . . . . 39
4.3.1.1.1.1. Date Type . . . . . . . . . . . . . . . . 40
4.3.1.1.1.2. Time Type . . . . . . . . . . . . . . . . 41
4.3.1.1.1.3. Digits Type . . . . . . . . . . . . . . . 42
4.3.1.1.2. <dtmf> . . . . . . . . . . . . . . . . . . . 42
4.3.1.1.3. <par> . . . . . . . . . . . . . . . . . . . . 43
4.3.1.1.3.1. <seq> . . . . . . . . . . . . . . . . . . 45
4.3.1.2. <control> . . . . . . . . . . . . . . . . . . . . 46
4.3.1.3. <collect> . . . . . . . . . . . . . . . . . . . . 49
4.3.1.3.1. <grammar> . . . . . . . . . . . . . . . . . . 52
4.3.1.4. <record> . . . . . . . . . . . . . . . . . . . . 53
4.3.1.5. <media> . . . . . . . . . . . . . . . . . . . . . 57
4.3.2. Exit Information . . . . . . . . . . . . . . . . . . 59
4.3.2.1. <promptinfo> . . . . . . . . . . . . . . . . . . 59
4.3.2.2. <controlinfo> . . . . . . . . . . . . . . . . . . 59
4.3.2.2.1. <controlmatch> . . . . . . . . . . . . . . . 59
4.3.2.3. <collectinfo> . . . . . . . . . . . . . . . . . . 60
4.3.2.4. <recordinfo> . . . . . . . . . . . . . . . . . . 60
4.3.2.4.1. <mediainfo> . . . . . . . . . . . . . . . . . 61
4.4. Audit Elements . . . . . . . . . . . . . . . . . . . . . 61
4.4.1. <audit> . . . . . . . . . . . . . . . . . . . . . . . 61
4.4.2. <auditresponse> . . . . . . . . . . . . . . . . . . . 63
4.4.2.1. <codecs> . . . . . . . . . . . . . . . . . . . . 65
4.4.2.1.1. <codec> . . . . . . . . . . . . . . . . . . . 65
4.4.2.2. <capabilities> . . . . . . . . . . . . . . . . . 66
4.4.2.2.1. <dialoglanguages> . . . . . . . . . . . . . . 68
4.4.2.2.2. <grammartypes> . . . . . . . . . . . . . . . 68
4.4.2.2.3. <recordtypes> . . . . . . . . . . . . . . . . 68
4.4.2.2.4. <prompttypes> . . . . . . . . . . . . . . . . 68
4.4.2.2.5. <variables> . . . . . . . . . . . . . . . . . 69
4.4.2.2.5.1. <variabletype> . . . . . . . . . . . . . 69
4.4.2.2.6. <maxpreparedduration> . . . . . . . . . . . . 70
4.4.2.2.7. <maxrecordduration> . . . . . . . . . . . . . 70
4.4.2.3. <dialogs> . . . . . . . . . . . . . . . . . . . . 70
4.4.2.3.1. <dialogaudit> . . . . . . . . . . . . . . . . 71
4.5. Response Status Codes . . . . . . . . . . . . . . . . . . 71
4.6. Type Definitions . . . . . . . . . . . . . . . . . . . . 77
4.6.1. Boolean . . . . . . . . . . . . . . . . . . . . . . . 77
4.6.2. DTMFChar . . . . . . . . . . . . . . . . . . . . . . 77
4.6.3. DTMFString . . . . . . . . . . . . . . . . . . . . . 77
4.6.4. Non-Negative Integer . . . . . . . . . . . . . . . . 77
4.6.5. Positive Integer . . . . . . . . . . . . . . . . . . 77
4.6.6. String . . . . . . . . . . . . . . . . . . . . . . . 78
4.6.7. Time Designation . . . . . . . . . . . . . . . . . . 78
4.6.8. Percentage . . . . . . . . . . . . . . . . . . . . . 78
4.6.9. URI . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.6.10. MIME Media Type . . . . . . . . . . . . . . . . . . . 78
4.6.11. Language Identifier . . . . . . . . . . . . . . . . . 78
4.6.12. DateTime . . . . . . . . . . . . . . . . . . . . . . 79
5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 79
6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.1. AS-MS Dialog Interaction Examples . . . . . . . . . . . . 105
6.1.1. Starting an IVR Dialog . . . . . . . . . . . . . . . 105
6.1.2. IVR Dialog Fails to Start . . . . . . . . . . . . . . 106
6.1.3. Preparing and Starting an IVR Dialog . . . . . . . . 107
6.1.4. Terminating a Dialog . . . . . . . . . . . . . . . . 108
6.2. IVR Dialog Examples . . . . . . . . . . . . . . . . . . . 108
6.2.1. Playing Announcements . . . . . . . . . . . . . . . . 109
6.2.2. Prompt and Collect . . . . . . . . . . . . . . . . . 109
6.2.3. Prompt and Record . . . . . . . . . . . . . . . . . . 111
6.2.4. Runtime Controls . . . . . . . . . . . . . . . . . . 112
6.2.5. Subscriptions and Notifications . . . . . . . . . . . 113
6.2.6. Dialog Repetition until DTMF Collection Complete . . 113
6.3. Other Dialog Languages . . . . . . . . . . . . . . . . . 114
6.4. Foreign Namespace Attributes and Elements . . . . . . . . 115
7. Security Considerations . . . . . . . . . . . . . . . . . . . 116
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 119
8.1. Control Package Registration . . . . . . . . . . . . . . 119
8.2. URN Sub-Namespace Registration . . . . . . . . . . . . . 120
8.3. XML Schema Registration . . . . . . . . . . . . . . . . . 120
8.4. MIME Media Type Registration for
application/msc-ivr+xml . . . . . . . . . . . . . . . . . 120
8.5. IVR Prompt Variable Type Registration Information . . . . 121
9. Using VoiceXML as a Dialog Language . . . . . . . . . . . . . 122
9.1. Preparing a VoiceXML Dialog . . . . . . . . . . . . . . . 122
9.2. Starting a VoiceXML Dialog . . . . . . . . . . . . . . . 123
9.2.1. Session Protocol Information . . . . . . . . . . . . 124
9.2.2. Session Media Stream Information . . . . . . . . . . 125
9.2.3. Session Parameter Information . . . . . . . . . . . . 127
9.3. Terminating a VoiceXML Dialog . . . . . . . . . . . . . . 128
9.4. Exiting a VoiceXML Dialog . . . . . . . . . . . . . . . . 128
9.5. Call Transfer . . . . . . . . . . . . . . . . . . . . . . 129
10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 130
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 130
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 130
12.1. Normative References . . . . . . . . . . . . . . . . . . 130
12.2. Informative References . . . . . . . . . . . . . . . . . 1321. Introduction ✨
Okay bestie, so the Media Control Channel Framework [RFC6230] is the generic way to set up and report on commands that get started remotely 💅. Its nickname is the Channel Framework, same thing, and it borrows a lot from the Session Initiation Protocol (SIP) [RFC3261] to find the other side and set up a reliable channel for control chatter 🦋. The framework also brings in the idea of a Control Package, which is basically a specific way of using the Control Framework for one particular set of interactions 🎀. This document is the Control Package for Interactive Voice Response (IVR) dialogs on media connections and conferences 📞. Quick heads up: when this doc says "dialog," it means an IVR dialog, and it has nothing to do with a SIP dialog 🙈. And "IVR" is used in the broad sense here, so media other than voice can be used for dialog interaction too 🌈.
The package lets you prepare, start, and terminate dialog interactions with dialog management request elements, and it gives you the responses and notifications that go along with them 🫶. The dialog interactions are described in a dialog language, which has a clearly defined syntax and semantics for what's allowed, like playing a prompt or recording input from the user ✨. This package ships a lightweight IVR dialog language that covers prompt playback, runtime controls, DTMF collection, and media recording, and it also lets other dialog languages be used 💜. Those dialog languages go inside the dialog management elements that prepare and start dialog interactions 🍓. The package also has elements for auditing both the package's capabilities and the IVR dialogs 🧚.
This package was designed to meet the IVR requirements in "Media Server Control Protocol Requirements" [RFC5167], specifically REQ-MCP-28, REQ-MCP-29, and REQ-MCP-30 👑. It gets there by building on two big approaches to IVR dialog design. Together they cover a wide range of IVR use cases and show up in a ton of apps that are widely deployed today 🔥.
First, the package gives you the major IVR features of SIP media server languages like netann [RFC4240], Media Server Control Markup Language (MSCML) [RFC5022], and Media Server Markup Language (MSML) [RFC5707]. Those languages are built on older non-SIP languages too ([H.248.9], [RFC2897]) 💅. The key difference is that this package does all of that IVR stuff through the Channel Framework, which is honestly iconic 👑.
Second, the design lines up with key concepts of the web model from the W3C Voice Browser languages 🌸. The main dialog management mechanism is closely aligned with Call Control XML (CCXML) [CCXML10] ✨.
The dialog functionality here is mostly a subset of VoiceXML ([VXML20], [VXML21]). Basic prompting, DTMF collection, and media recording are included where it makes sense, but none of the advanced VoiceXML constructs come along, like <form>, its interpretation algorithm, or a dynamic data model 🙈. W3C is working on VoiceXML 3.0 [VXML30], and we expect more alignment there, especially around a set of basic independent primitive elements (prompt, collect, record, and runtime controls) that different dialog languages can reuse 🦋.
By reusing and building on design patterns from these IVR language approaches, this package wants to feel familiar to current IVR developers and be enough for most IVR apps 💖. It also paves a path toward other languages for more advanced stuff 🚀.
This Control Package defines a lightweight IVR dialog language. Its scope covers these IVR functions:
- playing one or more media resources as a prompt to the user
- runtime controls (including VCR controls like speed and volume)
- collecting DTMF input from the user according to a grammar
- recording user media input
Some stuff is out of scope for this dialog language, like ASR (Automatic Speech Recognition), TTS (Text-to-Speech), fax, automatic prompt recovery ('media fallback'), and media transformation 🙅♀️. Those can be handled by other dialog languages (like VoiceXML) used alongside this package, by extensions to this package (adding foreign elements or attributes from another namespace), or by other Control Packages 💜.
The functionality of this package is defined by messages that contain XML [XML] elements, sent over the Media Control Channel Framework 🎀. The XML elements come in three types: dialog management elements, a dialog element that defines the lightweight IVR dialog language used with the dialog management elements, and elements for auditing the package's capabilities and the dialogs it manages 🧚.
Dialog management elements handle the general lifecycle of a dialog. There are elements for preparing a dialog, starting it on a conference or connection, and terminating its execution 🌈. Each of these elements sits inside a Media Control Channel Framework CONTROL message that goes to the media server 📨. Once the action is executed, the media server sends back a REPORT message (or a 200 response to the CONTROL message if it can finish in time) with a response element saying whether the operation worked. If the dialog can't start, the error shows up in that response 🙈. After a dialog starts successfully, the media server can send more event notifications in a framework CONTROL message ✨. This package defines two event notifications: a DTMF event for DTMF activity, and a dialogexit event for when the dialog exits 💅. If the dialog ran successfully, the dialogexit event includes the info collected during it 🎀. If something goes wrong during execution (like a media resource failing to play, or no recording resource being available), the error info gets reported in the dialogexit event 💀. Once a dialogexit event is sent, the dialog lifecycle is over 🪦.
The dialog management elements that prepare and start a dialog specify the dialog using a dialog language. A dialog language has well-defined syntax and semantics for its dialog operations 💖. Usually dialog languages are written in XML, where the root element has a designated XML namespace. When they're used as standalone documents, they also have an associated MIME media type 📄. For example, VoiceXML is an XML dialog language with the root element <vxml>, the designated namespace http://www.w3.org/2001/vxml, and standalone documents are associated with the MIME media type application/voicexml+xml [RFC4267] 🌸.
This Control Package defines its own lightweight IVR dialog language. The root element is <dialog>, and it uses the same designated namespace as the other elements defined in this package (see Section 8.2) 🫶. The root element holds child elements for playing prompts to the user, specifying runtime controls, collecting DTMF input from the user, and recording media input from the user 🎤. Those child elements can co-occur to give you 'play announcement', 'prompt and collect', and 'prompt and record' functionality 🔥.
The dialog management elements that prepare and start a dialog can specify the dialog language in one of two ways: either by including a fragment with the root element inline, or by referencing an external dialog document 🦋. The dialog language defined in this package is specified inline. Other dialog languages, like VoiceXML, can be used by referencing an external dialog document 🍓.
Here's how the document is laid out. Section 3 explains how this Control Package meets the requirements for a Media Control Channel Framework Control Package 📋. Section 4 covers the syntax and semantics of the defined elements, which means dialog management (Section 4.2), the IVR dialog element (Section 4.3), and audit elements (Section 4.4) 🧠. Section 5 describes an XML schema for these elements and allows extensibility by permitting attributes and elements from other namespaces 🧩. Section 6 has examples of using the package 💡. Section 7 covers the important security considerations for using this Control Package 🚨. Section 8 has the IANA registration info for this Control Package, including its name, XML namespace, and MIME media type, and it also sets up a registry for prompt variables 📚. Finally, Section 9 gives more info on using VoiceXML when it's supported as an external dialog language 🎀.
2. Conventions and Terminology
In this document, BCP 14 [RFC2119] defines the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" 📖. BCP 15 also indicates requirement levels for compliant implementations 💅.
These are the additional terms defined for this document 💜:
- Dialog: A dialog does media interaction with a user, following the concept of an IVR (Interactive Voice Response) dialog. This sense of 'dialog' is completely unrelated to a SIP dialog 🙈. A dialog is specified either as inline XML or through a URI reference to an external dialog document 🔗. Traditional IVR dialogs usually have features like playing audio prompts, collecting DTMF input, and recording audio input from the user 🎧. More inclusive definitions also cover other media types, runtime controls, synthesized speech, recording and playback of video, recognition of spoken input, and mixed initiative conversations 🌈.
- Application Server: A SIP [RFC3261] application server (AS) hosts and runs services like interactive media and conferencing in an operator's network 🏢. An AS influences and impacts the SIP session, most notably by terminating SIP sessions on a media server that it controls 👑.
- Media Server: A media server (MS) processes media streams on behalf of an AS, offering things like interactive media, conferencing, and transcoding to the end user 🎬. Interactive media functionality happens through dialogs that the application server starts 🫶.
3. Control Package Definition
This section covers the mandatory info that MUST be specified when defining a Control Framework Package, as detailed in Section 7 of [RFC6230] 📝.
3.1. Control Package Name
The Control Framework requires a Control Package to specify and register a unique name 🏷️.
The name of this Control Package is msc-ivr/1.0 (Media Server Control - Interactive Voice Response - version 1.0) 🎀. Its IANA registration is specified in Section 8.1 🦋.
Since this is the initial ("1.0") version of the Control Package, there are no backwards-compatibility issues to address 💖.
3.2. Framework Message Usage
okay so the Control Framework is super strict about this one 💅 Every Control Package has to spell out exactly which CONTROL messages it uses, plus which way they flow (who can send what to whom). It also has to say which role type is allowed to start each kind of request. Bestie, that's a lot of paperwork, but it keeps everything tidy ✨
This package defines its Control and response messages as XML elements from Section 4, and the message bodies use the MIME media type from Section 8.4 🎀 Every one of those elements (requests, responses, and notifications) lives inside a root <mscivr> element (Section 4.1). Iconic 🦋
Here's the vibe: the MS is the Control Server 🖥️ It takes requests from the AS (which is the Control Client) and sends back responses. Dialog management requests and responses are in Section 4.2, and audit requests and responses are in Section 4.4. Dialog management and audit responses get carried in a framework 200 response or in REPORT message bodies. All of this package's response codes are listed in Section 4.5.
Quick heads-up! Package responses are NOT the same thing as framework response codes 🙈 The framework error codes (see Section 7 of [RFC6230]) are for when the request or event notification is invalid. Like, the XML is broken (400), or the request just isn't understood (500). Different drawer, different socks 🧦
The MS also flips roles and acts as a Control Client when it sends event notifications to the AS (Control Server) 🔄 Those notifications (Section 4.2.5) ride along in CONTROL message bodies. And the AS MUST respond with a Control Framework 200 response. No ghosting allowed, bestie 💀
3.3. Common XML Support
the Control Framework says a Control Package has to state whether the attributes for media dialog or conference references are required 📝
So here's the deal: this package REQUIRES that the XML schema in Section A.1 of [RFC6230] MUST be supported for media dialogs and conferences 💜 Non-negotiable, periodt 💅
The package uses "connectionid" and "conferenceid" attributes across its various element definitions (Section 4). Those attributes are defined in the framework schema, and the XML schema in Section 5 just imports them from there. Borrowing from the framework = super efficient 🧚
3.4. CONTROL Message Body
the Control Framework wants every Control Package to say what body can go inside a CONTROL command request, and to point at where the detailed syntax and semantics live for each body type 🗺️
When the MS is acting as the Control Server, it gets Control message bodies that use the MIME media type from Section 8.4. Each body has an <mscivr> element (Section 4.1) with either a dialog management request or an audit request as its child element 🌸
These dialog management request elements come in CONTROL message bodies to the MS: <dialogprepare> (Section 4.2.1), <dialogstart> (Section 4.2.2), and <dialogterminate> (Section 4.2.3) ✨
The <audit> request element (Section 4.4.1) also rides in CONTROL message bodies 🔍
When the MS is acting as the Control Client, it sends CONTROL messages with the MIME media type from Section 8.4. The body has an <mscivr> element (Section 4.1) with a notification <event> child element (Section 4.2.5) inside 🔔
3.5. REPORT Message Body
the Control Framework needs each Control Package to define the REPORT body that can go inside a REPORT command request, or to say that no report package body is needed. This section just points to where the detailed syntax and semantics for those body types live 📚
When the MS is the Control Server, it sends REPORT bodies with the MIME media type from Section 8.4. Each one contains an <mscivr> element (Section 4.1) with a response child element. For dialog management requests, that response element is <response> (Section 4.2.4). For an audit request, it's <auditresponse> (Section 4.4.2) 🎯
3.6. Audit
the Control Framework encourages Control Packages to say whether auditing is available, how it gets triggered, and what the query and response formats look like 🔎
This Control Package supports auditing of package capabilities and of dialogs on the MS 🕵️♀️ An audit request rides in a CONTROL message (see Section 3.4). The audit response comes back in a REPORT message (see Section 3.5), or as a 200 response to the CONTROL if the MS can finish the audit in time ⏱️
The syntax and semantics for audit request and response elements are in Section 4.4 🧁
3.7. Examples
the Control Framework recommends that Control Packages give a range of message flows showing common uses of the package together with the framework document 🌈
And this package does exactly that: its example message flows are in Section 6 💖
4. Element Definitions
okay this section is where the actual XML elements get defined 🧚♀️ Every element lives in the XML namespace from Section 8.2.
The root element is <mscivr> (Section 4.1), and every other element (requests, responses, and notification elements) lives inside it. The child elements cover dialog management (Section 4.2) and audit (Section 4.4). The IVR dialog element, which sits inside the dialog management elements, is defined in Section 4.3. Response status codes are in Section 4.5, and type definitions are in Section 4.6 🎀
Implementing this Control Package MUST address the Security Considerations in Section 7. Bestie, this part is serious, so don't skip it 🔐
Implementing this Control Package MUST also follow the syntax and semantics of the XML elements defined in this section and in the schema (Section 5) 📐 XML schema can't express some kinds of syntactic rules (like attribute and element co-occurrence), so some elements add extra syntactic constraints in their text descriptions. If the XML schema and the textual description of an element in this section ever disagree, the textual definition takes priority 👑
The XML schema allows extensibility by permitting attributes and elements from other namespaces. Implementations MAY add extra capabilities through attributes and elements from other (foreign) namespaces 🦋 Foreign namespace attributes and elements aren't described in this section, so that's on them, iykyk ✨
Some elements carry attributes whose values are URIs 🔗 Those elements are: <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] for fetching and uploading resources, and the MS MAY support other schemes too 🌐 The implementation SHOULD support storing authentication information as part of its configuration, including security certificates for use with HTTPS 🔐
If the implementation wants to support user authentication, it can store user certificates and passwords as part of its configuration. Or it can extend the schema (for example, by adding an http-password attribute in its own namespace) and then map the user authentication information onto the right headers following the HTTP authentication model [RFC2616]. Choose your fighter 🥊
Some elements carry attributes whose values are descriptive text meant mainly for diagnostics 🩺 The implementation can say what language that text is in by using a desclang attribute ([RFC2277], [RFC5646]) ✨ The desclang attribute can appear on the root element and on selected subordinate elements (see Section 4.1). A desclang value on the root element applies to every desclang attribute in subordinate elements, unless a subordinate element has its own explicit desclang that overrides it 💜
Usage examples are in Section 6 🌸
4.1. <mscivr>
the <mscivr> element has these attributes (on top of the standard XML namespace attributes, like 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 the descriptive text attributes of subordinate elements (unless the subordinate element has adesclangattribute that overrides the value for its descriptive text attributes). The descriptive text attributes on subordinate elements include: thereasonattribute on<response>(Section 4.2.4),<dialogexit>(Section 4.2.5.1), and<auditresponse>(Section 4.4.2); thedescattribute 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, and only one of them can occur 👑
- 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.
- 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, here's a request to the MS to start an IVR dialog that plays 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 here's the MS's response saying 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 saying the dialog exited once the prompt finished playing 🔔
<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 set explicitly by the desclang attribute on the <mscivr> root element. 💖
4.2. Dialog Management Elements 🎀
okay so this section is where the dialog management XML elements for this Control Package live 💅 They come in three flavours: requests, responses, and notifications ✨
Requests are what you send to the MS when you want it to run a specific dialog operation 🫶 There are three:
<dialogprepare>: prepare a dialog for later execution<dialogstart>: start a (prepared) dialog on a connection or conference<dialogterminate>: terminate a dialog
Responses are how the MS tells you what happened to your request 🦋 Each one is a <response> element (Section 4.2.4) with a mandatory attribute holding a numeric status code, and those codes are defined in Section 4.5. The MS MUST respond to a request message with a response message. If the MS can't 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 for picking the right status code for the response 💜
Notifications are the MS being chatty 🌸 It sends them to give you updates on a dialog's status, or on operations happening inside the dialog. They're 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 responseFigure 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. It gets a valid dialog identifier (see below). If an error occurs, the dialog moves 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 moves 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 moves to the TERMINATED state, and the MS MUST send a
dialogexitnotification event (see Section 4.2.5.1). If the dialog stays in the PREPARED state for longer than the maximum preparation duration, the dialog moves to the TERMINATED state, and the MS MUST send adialogexitnotification 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 it hasn't been prepared yet, it gets prepared first and is assigned a valid dialog identifier (see below). If an error occurs, the dialog moves to the TERMINATED state and the MS MUST send a response indicating the error. If the dialog is terminated, the dialog moves to the TERMINATED state and the MS MUST send a 410 response (Section 4.5) for the start request.
- STARTED: the dialog has started successfully and is now active 🔥 The MS MUST send a 200 response indicating the start operation was successful. If any subscribed dialog events occur, the MS MUST send a notification when each one happens. When the dialog exits (through normal termination, an error, or a terminate request), the MS MUST send a
dialogexitnotification event (see Section 4.2.5.1), and the dialog moves to the TERMINATED state. - TERMINATED: the dialog is done, 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 moves to a TERMINATED state. The MS assigns the dialog identifier unless the <dialogprepare> or <dialogstart> request already specifies an identifier (dialogid) that isn't 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 how everyone refers to the dialog in later requests, responses, and notifications 🦋 In a <dialogstart> request, the dialog identifier can go in the prepareddialogid attribute to say which prepared dialog to start. In <dialogterminate> and <audit> requests, the dialog identifier goes in the dialogid attribute, telling the MS which dialog to terminate or audit. If these requests use a dialog identifier that's 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 the response is to a syntactically invalid request. 💜
For a given dialog, the <dialogprepare> or <dialogstart> request elements say what dialog content to run, either by including a <dialog> element inline (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 that holds the dialog definition and, optionally, a type attribute with the MIME media type of that dialog document. So the dialog language for a dialog on the MS is identified either inline by a <dialog> child element, or by a src attribute pointing at a document that contains 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> 🎀
okay so the <dialogprepare> request is how you ask the MS to get a dialog ready to go 💖 preparing means (a) fetching an external dialog document and/or any external resources referenced inside an inline <dialog> element, and (b) checking the dialog document for syntax AND semantics ✨
once a dialog is prepared, it gets executed when the MS receives a <dialogstart> request that references the prepared dialog identifier (see Section 4.2.2) 🦋
the <dialogprepare> element has these attributes:
src: this is where you point to an external dialog document you want prepared 🌸 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 isn't supported, the MS sends a<response>with a 420 status code (Section 4.5). if the document can't 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 the MS doesn't support, the MS sends a<response>with a 421 status code. this attribute is optional, and there's no default value.type: tells the MS what kind of external dialog document thesrcattribute is pointing at 🧚 a valid value is a MIME media type (see Section 4.6.10). if the URI scheme used insrcdefines its own way of establishing the authoritative MIME media type of the media resource, the value that mechanism returns takes precedence over this attribute 👑 this one is optional, with no default value.maxage: used to set the max-age value of theCache-Controlheader when an external dialog document is fetched over HTTP, as per [RFC2616] 💜 a valid value is a non-negative integer (see Section 4.6.4). optional, no default value.maxstale: same vibe asmaxage, but it sets the max-stale value of theCache-Controlheader for an external dialog document fetched over HTTP, as per [RFC2616] 🫶 a valid value is a non-negative integer (see Section 4.6.4). optional, 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). this one is optional, and the default value is30s🍓dialogid: a string that gives the dialog a unique name 🎀 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 isn't specified, the MS MUST create a unique name for the dialog (see Section 4.2 for dialog identifier assignment) 🙈 optional, no default value.
the <dialogprepare> element has the following child elements, in this sequence:
<dialog>: an IVR dialog (Section 4.3) to prepare 💖 this one is optional.<params>: input parameters (Section 4.2.6) for dialog languages defined outside this specification ✨ optional too. if the MS doesn't support a parameter for the external dialog language, the MS sends a<response>with a 427 status code (Section 4.5).
so the dialog you want prepared can go in two places: inline, using a <dialog> child element, or externally (for dialog languages defined outside this specification) using the src attribute 🦋 it's a syntax error if you specify BOTH an inline <dialog> element AND a src attribute, and the MS sends a <response> with a 400 status code (see Section 4.5). the type, maxage, maxstale, and fetchtimeout attributes only matter when the dialog is an external document 🌈
here's a <dialogprepare> request preparing 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>and in this one, we've got a request with a specified dialogid preparing a VoiceXML dialog document that lives 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>bestie, quick heads up: support for dialog languages OTHER than the IVR dialog language defined in this package is optional. so if the MS doesn't support the dialog language, it would send a response with the status code 421 (Section 4.5) 💀 more on using VoiceXML can be found in Section 9 🌸
4.2.2. <dialogstart> 🎬
okay so <dialogstart> is the element the AS sends to the MS to kick off a dialog 🦋. If the dialog hasn't been prepared yet, the MS prepares it right then. That means fetching any external document and/or external resources referenced inside the <dialog> element, and checking the dialog document for syntax and semantics. Then the media processors (like DTMF and the prompt queue) get activated and tied to the specified connection or conference 🎀.
The <dialogstart> element has these attributes:
src: where to find 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 isn't supported, the MS sends a<response>with a 420 status code (Section 4.5). If the document can't be retrieved within the timeout interval, the MS sends a<response>with a 409 status code. If the document uses a type of dialog language the MS doesn't support, the MS sends a<response>with a 421 status code. This attribute is optional, and there's no default value.type: the type of the external dialog document named in thesrcattribute. A valid value is a MIME media type (see Section 4.6.10). If the URI scheme insrchas a way of establishing the authoritative MIME media type of the media resource, the value that mechanism returns wins over this attribute 💅. This attribute is optional, and there's no default value.maxage: sets the max-age value of theCache-Controlheader when an external dialog document is fetched over HTTP, as per [RFC2616]. A valid value is a non-negative integer (see Section 4.6.4). This attribute is optional, and there's no default value.maxstale: sets the max-stale value of theCache-Controlheader when an external dialog document is fetched over HTTP, as per [RFC2616]. A valid value is a non-negative integer (see Section 4.6.4). This attribute is optional, and there's no default value.fetchtimeout: the longest time to wait when fetching an external dialog document. A valid value is a Time Designation (see Section 4.6.7). This attribute is optional, and the default value is30s⏰.dialogid: a string giving 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 neitherdialogidnorprepareddialogidis specified, the MS MUST create a unique name for the dialog (see Section 4.2 for dialog identifier assignment) 🧚. This attribute is optional, and there's no default value.prepareddialogid: a string identifying a dialog that was earlier prepared with a<dialogprepare>(Section 4.2.1) request. If neitherdialogidnorprepareddialogidis specified, the MS MUST create a unique name for the dialog (see Section 4.2 for dialog identifier assignment). This attribute is optional, and there's no default value.connectionid: a string identifying the SIP dialog connection this dialog should start on (see Appendix A.1 of [RFC6230]). This attribute is optional, and there's no default value.conferenceid: a string identifying the conference this dialog should start on (see Appendix A.1 of [RFC6230]). This attribute is optional, and there's no default value.
Exactly one of connectionid or conferenceid MUST be specified. If both are specified, or neither is, that's a syntax error and the MS sends a <response> with a 400 status code (Section 4.5) 🙈.
It's an error if the connection or conference named by connectionid or conferenceid isn't available on the MS when the <dialogstart> request runs. An invalid connectionid gets a <response> with a 407 status code (Section 4.5), and an invalid conferenceid gets a <response> with a 408 status code.
The <dialogstart> element has the following sequence of child elements:
<dialog>: the IVR dialog (Section 4.3) to run. This element is optional.<subscribe>: subscriptions to dialog events (Section 4.2.2.1). This element is optional.<params>: input parameters (Section 4.2.6) for dialog languages defined outside this specification. This element is optional. If the MS doesn't support a parameter for the external dialog language, the MS sends a<response>with a 427 status code (Section 4.5).<stream>: decides which media stream(s) are used by the connection or conference the dialog runs on (Section 4.2.2.2). This element is optional, and you can specify multiple<stream>elements.
There are three ways to say which dialog to start: (a) inline with a <dialog> child element, (b) externally using the src attribute (for dialog languages defined outside this specification), or (c) by pointing at a previously prepared dialog with the prepareddialogid attribute 🎯. If exactly one of the src attribute, the prepareddialogid attribute, or a <dialog> child element isn't specified, that's a syntax error and the MS sends a <response> with a 400 status code (Section 4.5). If both prepareddialogid and dialogid are specified, that's also a syntax error, and the MS sends a <response> with a 400 status code. The type, maxage, maxstale, and fetchtimeout attributes only matter when the dialog is an external document.
The <stream> element gives you explicit control over which media streams on the connection or conference get used while the dialog runs. For example, if a connection supports both audio and video, a <stream> element can say only the audio stream is used in receive mode 🎧. When a dialog has multiple media streams of the same type, the AS MUST use <stream> elements to spell out the configuration. If there are no <stream> elements, the default media configuration is whatever's defined for the connection or conference ✨.
If a <stream> element conflicts (a) with another <stream> element, (b) with the connection's or conference's media capabilities, or (c) with a Session Description Protocol (SDP) label value that's part of the connectionid (see Appendix A.1 of [RFC6230]), the MS sends a <response> with a 411 status code (Section 4.5). If the MS doesn't support the media stream configuration, the MS sends a <response> with a 428 status code (Section 4.5) 😭.
The MS MAY support multiple, simultaneous dialogs started on the same connection or conference 👯. For example, the same connection can receive different media streams (say audio and video) from different dialogs, or it can receive the same type of media stream from different dialogs and mix them where that makes sense. If the MS doesn't support starting another dialog on the same connection or conference, it sends a <response> with a 432 status code (Section 4.5) when it gets the second (or any later) dialog request.
Here's a request to start an ivr dialog on a connection that's subscribed 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 one, the dialog starts on a conference that 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 lets the AS subscribe to specific events that happen while the dialog is running, and get notified about them 💌. Dialog event notifications get delivered in 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>: a subscription to DTMF input during the dialog (Section 4.2.2.1.1). This element is optional.
If a request has a <subscribe> with no child elements, the MS treats the request as if there were no <subscribe> element at all 🫶.
The MS MUST support the <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 doesn't support a subscription that's 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 these attributes:
matchmode: controls which DTMF input gets subscribed to. Valid values are "all", which notifies on every DTMF key press received during the dialog; "collect", which notifies only on DTMF input matched by the collect operation (Section 4.3.1.3); and "control", which notifies only on DTMF input matched by the runtime control operation (Section 4.3.1.2). This attribute is optional, and the default value is "all" 💖.
The <dtmfsub> element has no child elements.
DTMF notifications get delivered in the <dtmfnotify> element (Section 4.2.5.2).
Here's an example where the AS wants to subscribe to DTMF key presses that match 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>Every time a '2' or '3' DTMF input comes in, 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> ✨
okay so the <stream> element is where the media settings live 🎀 it has three attributes:
media: a string for the type of media on 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 for the SDP label linked to a media stream [RFC4574]. The attribute is optional.direction: a string for which way the media flows, relative to the conference or connection. The defined values are "sendrecv" (the endpoint can send media to the dialog and receive media from it), "sendonly" (the endpoint can only send media to the dialog), "recvonly" (the endpoint can only receive media from the dialog), and "inactive" (the stream is not to be used). The default value is "sendrecv". The attribute is optional.
The <stream> element has this sequence of child elements:
<region>: an element that specifies the area in a mixer video layout where a media stream is displayed (Section 4.2.2.2.1). It's optional 🦋<priority>: an element that sets the priority of the stream in the conference mix (Section 4.2.2.2.2). It's also optional.
If conferenceid is not specified, or if the media attribute is not "video", then the MS ignores the <region> and <priority> elements. 🙈
Here's an example. Imagine a User Agent connection with several audio and video streams for the user, plus a separate web camera. The dialog could be started to record only the user's audio and video streams:
<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 <region>, a dialog can be started on a conference mixer so that its video output goes to a specific spot in 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 names a spot inside a presentation layout where a video media stream is shown. The MS could, for example, play video into an area of a video layout, where the layout and its named regions are set up using the Mixer Control Package [MIXER-CP].
The <region> element has no attributes. Its content model is 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 that contains the <region> element. 💀
4.2.2.2.2. <priority> 👑
The <priority> element explicitly sets the priority of the dialog when it's presented in a conference mix.
The <priority> element has no attributes. Its content model is a positive integer (see Section 4.6.5). The lower the value, the higher the priority. 🔥
4.2.3. <dialogterminate> 🍓
A dialog can be ended by sending a <dialogterminate> request element to the MS.
The <dialogterminate> element has these attributes:
dialogid: a string that identifies the dialog to terminate. If the dialog identifier is invalid, the MS sends a response with a 405 status code (Section 4.5). The attribute is mandatory.immediate: indicates whether a dialog in the STARTED state is terminated right away. In other states, termination is always immediate. A valid value is a boolean (see Section 4.6.1). A value of true means 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 means the dialog ends 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), saying whether the dialog was terminated successfully. 🫶
For example, here's an immediate termination of 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 terminates successfully, 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 come back in a <response> element.
The <response> element has these attributes:
status: a numeric code for the response status. Valid values are defined in Section 4.5. The attribute is mandatory.reason: a string giving a reason for the response status. The attribute is optional. There is no default value.desclang: the language used in the value of thereasonattribute. A valid value is a language identifier (Section 4.6.11). The attribute is optional. If it's not specified, the value of thedesclangattribute on<mscivr>(Section 4.1) applies.dialogid: a string identifying the dialog. If the request specifies a dialogid, that value is used. Otherwise, for<dialogprepare>and<dialogstart>requests, the dialogid generated by the MS is used. If no dialogid is available because the request is syntactically invalid (for example, a<dialogterminate>request with no dialogid attribute), the value is the empty string. The attribute is mandatory.connectionid: a 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: a string identifying the conference associated with the dialog (see Appendix A.1 of [RFC6230]). The attribute is optional. There is no default value.
Here's 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>And here's the response when dialog preparation fails because the dialog language isn't supported:
<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 doesn't specify a dialogid:
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogterminate/>
</mscivr>The response status is 400 (Syntax error), 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 it in an <event> element.
The <event> element has this attribute:
dialogid: a string identifying the dialog that generated the event. The attribute is mandatory.
The <event> element has the following child elements, and only one of them 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 says that a prepared or active dialog has exited, because it completed, was terminated, or hit an error during execution (for example, a media resource couldn't be played). The MS MUST send this event when the dialog exits. ✨
The <dialogexit> element has these attributes:
status: a status code showing 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 these values:0: the dialog was terminated by a<dialogterminate>request.1: the dialog completed successfully.2: the dialog terminated because the connection or conference associated with it terminated.3: the dialog terminated because it exceeded its maximum duration.4: the dialog terminated due to an execution error.
All other valid but undefined values are reserved for future use. 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 equivalent to 4 (dialog execution error). The attribute is mandatory.
reason: a textual description that the MS SHOULD use to give a reason for the status code, such as 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: the language used in the value of thereasonattribute. A valid value is a language identifier (Section 4.6.11). The attribute is optional. If it's not specified, the value of thedesclangattribute on<mscivr>(Section 4.1) applies.
The <dialogexit> element has this sequence of child elements:
<promptinfo>: report information (Section 4.3.2.1) about prompt execution in an IVR<dialog>. It's optional.<controlinfo>: reports information (Section 4.3.2.2) about control execution in an IVR<dialog>. It's optional.<collectinfo>: reports information (Section 4.3.2.3) about collect execution in an IVR<dialog>. It's optional.<recordinfo>: reports information (Section 4.3.2.4) about record execution in an IVR<dialog>. It's optional.<params>: reports exit parameters (Section 4.2.6) for a dialog language defined outside this specification. It's optional.
For example, when an active <dialog> exits normally, the MS sends a dialogexit <event> with report 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> 📞✨
okay bestie, the <dtmfnotify> element is how the MS tells you about DTMF input it picked up during the active dialog. 🎹 But it ONLY shows up when you asked for it with a <dtmfsub> subscription (Section 4.2.2.1). no cap, it's the receipts 🧾💅
The <dtmfnotify> element has the following attributes:
matchmode: tells you which matching mode was asked for in the subscription request. Valid values are:"all"- all DTMF key presses notified individually"collect"- only DTMF input matched by the collect operation notified"control"- only DTMF input matched by the control operation notified
dtmf: the DTMF key presses received, filtered by the matchmode. A valid value is a DTMF string (see Section 4.6.3) with no space between characters. The attribute is mandatory. 🔢timestamp: the time (on the MS) when the last key press happened, according to the matchmode. A valid value is a dateTime expression (Section 4.6.12). The attribute is mandatory. ⏰
For matchmode, the attribute is optional, and the default value is "all" 🦋
For example, here's a notification for 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> 🧺
okay so the <params> element is basically a container that holds <param> elements (Section 4.2.6.1). it's the little purse of extras 👛💖
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, here's usage with a dialog language defined outside this specification, sending extra 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. it's giving key-value energy 🔑✨
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 thetypeattribute. 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 containing XML characters (e.g., "<") needs to be escaped following standard XML conventions. ⚠️ bestie, don't skip the escaping, that's the main character mistake 💀
For example, here's usage with a dialog language defined outside this specification, receiving 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>4.3. IVR Dialog Elements 🎙️👑
this section is about the IVR dialog language that this specification defines. The MS MUST support this dialog language. no skipping, it's non-negotiable 🫶
The <dialog> element is the execution container for operations like playing prompts (Section 4.3.1.1), runtime controls (Section 4.3.1.2), collecting DTMF (Section 4.3.1.3), and recording user input (Section 4.3.1.4). The results of the dialog execution (Section 4.3.2) get reported in a dialogexit notification event 📣
Using these elements, three common dialog models are supported:
playannouncements: only a<prompt>element is specified in the container. The prompt media resources are played in sequence. 🎶promptandcollect: a<collect>element is specified and, optionally, a<prompt>element. If a<prompt>element is specified and bargein is enabled, playing of the prompt is terminated when bargein occurs, and DTMF collection is initiated. Otherwise, the prompt is played to completion before DTMF collection is initiated. If no prompt element is specified, DTMF collection is initiated immediately. ⌨️promptandrecord: a<record>element is specified and, optionally, a<prompt>element. If a<prompt>element is specified and bargein is enabled, playing of the prompt is terminated when bargein occurs, and recording is initiated. Otherwise, the prompt is played to completion before recording is initiated. If no prompt element is specified, recording is initiated immediately. 🔴
In addition, this dialog language supports runtime ('VCR') controls, which let a user control prompt playback using DTMF. it's the rewind-and-pause energy we all need 📼💜
Each of the core elements -- <prompt>, <control>, <collect>, and <record> -- is specified so that its execution and reporting is largely self-contained. This makes them easy to reuse in other dialog container elements. Note that DTMF and bargein behavior affects multiple elements, so it's addressed in the relevant element definitions 🧩
Execution results are reported in the <dialogexit> notification event, with child elements defined in Section 4.3.2. If the dialog terminated normally (i.e., not due to an error or to a <dialogterminate> request), then the MS MUST report the results for the operations specified in the dialog:
<prompt>:<promptinfo>(see Section 4.3.2.1) with at least thetermmodeattribute specified.<control>:<controlinfo>(see Section 4.3.2.2) if any runtime controls are matched.<collect>:<collectinfo>(see Section 4.3.2.3) with thedtmfandtermmodeattributes specified.<record>:<recordinfo>(see Section 4.3.2.4) with at least thetermmodeattribute and one<mediainfo>element specified. 🎬
The media format requirements for IVR dialogs are undefined. This package is agnostic to the media types and codecs for media resources and recording that an implementation needs to support. For example, an MS implementation might only support audio, and in particular the 'audio/basic' codec for media playback and recording. 🎧 However, when executing a dialog, if an MS encounters a media type or codec that it cannot process, the MS MUST stop further processing and report the error using the dialogexit notification. 🚨 that's a hard stop, bestie, no vibes-based workarounds 😭
4.3.1. <dialog> 💖
okay bestie, the <dialog> element is the main event 🎀 It's an IVR dialog that can play prompts to the user, allow runtime controls, collect DTMF, or record input. You write it with a <dialog> element.
A <dialog> element has these attributes:
repeatCount: the number of times the dialog gets executed. A valid value is a non-negative integer (see Section 4.6.4). A value of0means the dialog keeps repeating until something else halts it. The attribute is optional. The default value is1.repeatDur: the maximum duration for dialog execution. A valid value is a time designation (see Section 4.6.7). If you don't give it a value, the dialog has no duration limit at all. The attribute is optional. There is no default value.repeatUntilComplete: tells you whether the MS ends dialog execution when an input operation finishes successfully. A valid value is a boolean (see Section 4.6.1). A value oftruemeans dialog execution ends when an input operation tied to its child elements finishes successfully (check the execution model below for the exact conditions). A value offalsemeans dialog execution ends by other means. The attribute is optional. The default value isfalse.
The repeatDur attribute beats repeatCount when it comes to figuring out the maximum duration of the dialog 👑 For more info, look up repeatCount and repeatDur in the Synchronized Multimedia Integration Language (SMIL) [W3C.REC-SMIL2-20051213]. If a dialog gets repeated more than once, only the results from the operations in the last dialog iteration get reported. 🦋
The <dialog> element has the following sequence of child elements (at least one, any order):
<prompt>: defines the media resources to play in sequence (see Section 4.3.1.1). The element is optional.<control>: defines how DTMF gets used for runtime controls (see Section 4.3.1.2). The element is optional.<collect>: defines how DTMF gets collected (see Section 4.3.1.3). The element is optional.<record>: defines how recording happens (see Section 4.3.1.4). The element is optional.
This Control Package doesn't define what happens when a request has both <collect> and <record> elements. Still, the MS MAY support this configuration. If the MS doesn't support it, the MS sends a <response> with a 433 status code. 🙈
After initialization, the MS follows this execution model for the IVR dialog (the MS reports any initialization errors in the response):
- If an error happens during execution, the MS ends the dialog and reports the error in the
<dialogexit>event by setting thestatusattribute (see Section 4.3.2). The details of the error go in thereasonattribute. - The MS sets a counter to
0. - The MS starts a duration timer for the value of the
repeatDurattribute. If the timer runs out before the dialog is complete, the MS ends the dialog and sends adialogexitwhosestatusattribute is set to3(see Section 4.2.5.1). The MS MAY report information in thedialogexitthat was gathered in the last execution cycle (if there was one). - The MS kicks off a dialog execution cycle. Each cycle runs the operations tied to the dialog's child elements. If a
<prompt>element is specified, the MS runs that element's prompt playing operation and activates any controls (if the<control>element is specified). If no<prompt>is specified, or once a specified<prompt>ends, the MS starts the collect operation or the record operation, if the<collect>or<record>elements are specified. If subscriptions are specified for the dialog, the MS sends a notification event when the specified event happens. If running a child element causes an error, the MS ends dialog execution (and stops the other child element operations), then sends adialogexitstatus event that reports whatever info it gathered. - If the dialog execution cycle finishes successfully, the MS adds one to the counter. The MS ends dialog execution if either of these conditions is true:
- the value of the
repeatCountattribute is greater than zero, and the counter is equal to the value of therepeatCountattribute. - the value of the
repeatUntilCompleteattribute istrueand one of these conditions is true:<collect>reports a termination status of'match'or'stopped'.<record>reports a termination status of'stopped','dtmf','maxtime', or'finalsilence'.
- the value of the
When the MS ends dialog execution, it sends a dialogexit (with a status of 1) that reports the operation info collected in the last dialog execution cycle only. Otherwise, another dialog execution cycle starts.
4.3.1.1. <prompt>
The <prompt> element specifies a sequence of media resources to play back in document order. 🎶
A <prompt> element has these attributes:
xml:base: a string that declares the base URI that relative URIs in child elements get resolved against before fetching. A valid value is a URI (see Section 4.6.9). The attribute is optional. There is no default value.bargein: tells you whether user input stops prompt playback, unless the input is tied to a specified runtime<control>operation (input matching control operations never interrupts prompt playback). A valid value is a boolean (see Section 4.6.1). A value oftruemeans barge-in is allowed and prompt playback stops. A value offalsemeans barge-in isn't allowed: user input does not end prompt playback. The attribute is optional. The default value istrue.
The <prompt> element has these child elements (at least one, any order, and you can have multiple occurrences of elements):
<media>: specifies a media resource (see Section 4.3.1.5) to play. The element is optional.<variable>: specifies a variable media announcement (see Section 4.3.1.1.1) to play. The element is optional.<dtmf>: generates one or more DTMF tones (see Section 4.3.1.1.2) to play. The element is optional.<par>: specifies media resources to play in parallel (see Section 4.3.1.1.3). The element is optional.
If the MS doesn't support the configuration that prompt playback needs for the output media streams, and there's no more specific error code defined for its child elements, the MS sends a <response> with a 429 status code (Section 4.5). The MS MAY support transcoding between the media resource format and the output stream format. 🔄
After initialization, the MS follows this execution model for prompt playing:
- The MS starts prompt playback, playing its child elements (
<media>,<variable>,<dtmf>, and<par>) one after another in document order. - If any error happens during prompt execution (including fetching and rendering errors), the MS ends playback and reports its error status to the dialog container (see Section 4.3) with a
<promptinfo>(see Section 4.3.2.1), where thetermmodeattribute is set tostoppedand any additional information is set. - If DTMF input is received and the value of the
bargeinattribute istrue, the MS ends prompt playback and reports its execution status to the dialog container (see Section 4.3) with a<promptinfo>(see Section 4.3.2.1), where thetermmodeattribute is set tobargeinand any additional information is set. - If the dialog container stops prompt playback, the MS reports its execution status to the dialog container (see Section 4.3) with a
<promptinfo>(see Section 4.3.2.1), where thetermmodeattribute is set tostoppedand any additional information is set. - If prompt playback finishes successfully, the MS reports its execution status to the dialog container (see Section 4.3) with a
<promptinfo>(see Section 4.3.2.1), where thetermmodeattribute is set tocompletedand any additional information is set.
4.3.1.1.1. <variable>
The <variable> element specifies variable announcements using predefined media resources. 🧠 Each variable has at least a type (for example, date) and a value (for example, 2008-02-25). The value gets rendered according to the prompt variable type (for example, 2008-02-25 gets rendered as the date 25th February 2008). The exact mechanism for generating variable announcements (including where the associated media resources live) is implementation specific.
A <variable> element has these attributes:
type: specifies the type of prompt variable to render. This specification defines three values:date(Section 4.3.1.1.1.1),time(Section 4.3.1.1.1.2), anddigits(Section 4.3.1.1.1.3). All other valid but undefined values are reserved for future use, and new values get assigned as described in Section 8.5. A valid value is a string (see Section 4.6.6). The attribute is mandatory.value: specifies a string to be rendered according to the prompt variable type. A valid value is a string (see Section 4.6.6). The attribute is mandatory.format: specifies format information that the prompt variable type uses to render thevalueattribute. A valid value is a string (see Section 4.6.6). The attribute is optional. There is no default value.gender: specifies the gender that the prompt variable type uses to render thevalueattribute. Valid values are"male"or"female". The attribute is optional. There is no default value.xml:lang: specifies the language that the prompt variable type uses to render thevalueattribute. A valid value is a language identifier (see Section 4.6.11). The attribute is optional. There is no default value.
The <variable> element has no children.
This specification doesn't care about the type or codec of the media resources the variables get rendered into, or about the rendering mechanism itself. For example, an MS implementation that supports audio rendering could map the <variable> into one or more audio media resources. 🎧
This package doesn't care which <variable> types an implementation supports. If the MS doesn't support a <variable> element configuration that a request specified, the MS sends a <response> with a 425 status code (Section 4.5). 💅
4.3.1.1.1.1. Date Type 📅
The date variable type is your go-to for dynamically rendering a date prompt. It's giving calendar energy 🗓️✨
The type attribute on <variable> MUST have the value "date". No other vibes allowed, bestie 💅
The format attribute on <variable> MUST be one of the following values, and it has to comply with how it renders the value attribute:
mdy: thevalueattribute is rendered as a sequence made of month, then day, then year 🇺🇸ymd: thevalueattribute is rendered as a sequence made of year, then month, then day 🌏dym: thevalueattribute is rendered as a sequence made of day, then year, then month 🌀dm: thevalueattribute is rendered as a sequence made of day, then month 🍓
The value attribute of <variable> MUST comply with a lexical representation of date where:
yyyy '-' mm '-' ddas defined in Section 3.2.9 of [XMLSchema:Part2]. The format is giving strict but it's iconic 🫶
Here's an example:
<variable type="date" format="dmy" value="2010-11-25"
xml:lang="en" gender="male"/>This describes a variable date prompt where the date can be rendered in audio as "twenty-fifth of November two thousand and ten" using a list of <media> resources:
<media loc="nfs://voicebase/en/male/25th.wav"/>
<media loc="nfs://voicebase/en/male/of.wav"/>
<media loc="nfs://voicebase/en/male/november.wav"/>
<media loc="nfs://voicebase/en/male/2000.wav"/>
<media loc="nfs://voicebase/en/male/and.wav"/>
<media loc="nfs://voicebase/en/male/10.wav"/>4.3.1.1.1.2. Time Type ⏰
The time variable type gives you a way to dynamically render a time prompt. Clock moment, super aesthetic 🕑🦋
The type attribute on <variable> MUST have the value "time". Same energy as the date one, just with a different outfit 💖
The format attribute on <variable> MUST be one of the following values, and it has to comply with how it renders the value attribute:
t12: thevalueattribute is rendered as a time in traditional 12-hour format using am or pm. For example, "twenty-five minutes past 2 pm" for "14:25" 🌙t24: thevalueattribute is rendered as a time in 24-hour format. For example, "fourteen twenty-five" for "14:25" ☀️
The value attribute of <variable> MUST comply with a lexical representation of time where:
hh ':' mm ( ':' ss )?as defined in Section 3.2.8 of [XMLSchema:Part2]. Hours and minutes are the core, seconds are optional, and that's the tea ☕✨
4.3.1.1.1.3. Digits Type 🔢
The digits variable type provides a mechanism for dynamically rendering a digit sequence. Numbers, but make it a whole vibe 🧚
The type attribute on <variable> MUST have the value "digits". It's giving consistency 💜
The format attribute on <variable> MUST be one of the following values, and it has to comply with how it renders the value attribute:
gen: thevalueattribute is rendered as a general digit string. For example, "one two three" for "123" 🔡crn: thevalueattribute is rendered as a cardinal number. For example, "one hundred and twenty-three" for "123" 🎂ord: thevalueattribute is rendered as an ordinal number. For example, "one hundred and twenty-third" for "123" 🥇
The value attribute of <variable> MUST comply with the lexical representation:
d+i.e., one or more digits. Simple, clean, no drama 🌸
4.3.1.1.2. <dtmf> 🎹
The <dtmf> element specifies a sequence of DTMF tones for output. Beep boop, but cute 🎀
DTMF tones could be generated using <media> resources where the output is transported as RTP audio packets. However, <media> resources are not sufficient for cases where DTMF tones are to be transported as DTMF RTP [RFC4733] or in event packages. So <media> isn't always the move, iykyk 👀
A <dtmf> element has the following attributes:
digits: specifies the DTMF sequence to output. A valid value is a DTMF string (see Section 4.6.3). The attribute is mandatory. This one is non-negotiable 🫡level: used to define the power level for which the DTMF tones will be generated. Values are expressed in dBm0. A valid value is an integer in the range of 0 to -96 (dBm0). Larger negative values express lower power levels. Note that values lower than -55 dBm0 will be rejected by most receivers (TR-TSY-000181, ITU-T Q.24A). The attribute is optional. The default value is -6 (dBm0). Lowkey a power-level glow-up 🔋duration: specifies the duration for which each DTMF tone is generated. A valid value is a time designation (see Section 4.6.7). The MS MAY round the value if it only supports discrete durations. The attribute is optional. The default value is 100 ms. ⏱️interval: specifies the duration of a silence interval following each generated DTMF tone. A valid value is a time designation (see Section 4.6.7). The MS MAY round the value if it only supports discrete durations. The attribute is optional. The default value is 100 ms. 🤫
The <dtmf> element has no children. Solo queen energy 👑
If a <dtmf> element configuration is not supported, the MS sends a <response> with a 426 status code (Section 4.5). Not supported? The MS sends a <response> with a 426 status code (Section 4.5). Bestie, that's the whole plot 💀
4.3.1.1.3. <par> 🎶
The <par> element allows media resources to be played in parallel. Multitasking, but make it iconic 🦋 Each of its child elements specifies a media resource (or a sequence of media resources using the <seq> element). When playback of the <par> element is initiated, the MS begins playback of all its child elements at the same time. This element is modeled after the <par> element in SMIL [W3C.REC-SMIL2-20051213]. It's literally the same vibe as SMIL 🌈
The <par> element has the following attributes:
endsync: indicates when playback of the element is complete. Valid values are"first"(indicates that the element is complete when any child element reports that it is complete) and"last"(indicates it is complete when every child elements are complete). The attribute is optional. The default value is"last". The default is giving "wait for everyone" 🫶
If the value is "first", then playback of other child elements is stopped when one child element reports it is complete. First one done, everybody else gets cut off 💅
The <par> element has the following child elements (at least one, any order, multiple occurrences of each element permitted):
<seq>: specifies a sequence of media resources to play in parallel with other<par>child elements (see Section 4.3.1.1.3.1). The element is optional. 🧵<media>: specifies a media resource (see Section 4.3.1.5) to play. The MS is responsible for assigning the appropriate media stream(s) when more than one is available. The element is optional. 🎞️<variable>: specifies a variable media announcement (see Section 4.3.1.1.1) to play. The element is optional. 🗣️<dtmf>: generates one or more DTMF tones (see Section 4.3.1.1.2) to play. The element is optional. 🎹
It is RECOMMENDED that a <par> element contains only one <media> element of the same media type (i.e., same type-name as defined in Section 4.6.10). If a <par> element configuration is not supported, the MS sends a <response> with a 435 status code (Section 4.5). Keep it to one <media> per type, that's the recommended slay 💖
Runtime <control>s (Section 4.3.1.2) apply to each child element playing in parallel. For example, pause and resume controls cause all child elements to be paused and resumed, respectively. Pause means everybody pauses, resume means everybody comes back, no one gets left out 🫂
If the <par> element is stopped by the prompt container (e.g., bargein or dialog termination), then playback of all child elements is stopped. The playback duration (Section 4.3.2.1) reported for the <par> element is the duration of parallel playback, not the cumulative duration of each child element played in parallel. Parallel means parallel, not "add everything up" 🙅♀️
For example, a request to playback audio and video media in parallel:
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="c1">
<dialog>
<prompt>
<par>
<media type="audio/x-wav"
loc="http://www.example.com/media/comments.wav"/>
<media type="video/3gpp;codecs='s263'"
loc="http://www.example.com/media/camera.3gp"/>
</par>
</prompt>
</dialog>
</dialogstart>
</mscivr>When the <prompt> element is executed, it begins playback of its child element in document-order sequence. In this case, there is only one child element, a <par> element itself containing audio and video <media> child elements. Consequently, playback of both audio and video media resources is initiated at the same time. Since the endsync attribute is not specified, the default value "last" applies. The <par> element playback is complete when the media resource with the longest duration is complete. Both start together, and the longest one gets the final word 🎬✨
4.3.1.1.3.1. <seq> 🎞️
The <seq> element specifies media resources to be played back in sequence. This allows a sequence of media resources to be played at the same time as other children of a <par> element are played in parallel, for example, a sequence of audio resources while a video resource is played in parallel. This element is modeled after the <seq> element in SMIL [W3C.REC-SMIL2-20051213]. One after another, but make it a parallel-universe moment 🌌
The <seq> element has no attributes. Zero attributes, zero stress 🧘♀️
The <seq> element has the following child elements (at least one, any order, multiple occurrences of each element permitted):
<media>: specifies a media resource (see Section 4.3.1.5) to play. The element is optional. 🎥<variable>: specifies a variable media announcement (see Section 4.3.1.1.1) to play. The element is optional. 📣<dtmf>: generates one or more DTMF tones (see Section 4.3.1.1.2) to play. The element is optional. 🔔
Playback of a <seq> element is complete when all child elements in the sequence are complete. If the <seq> element is stopped by the <par> container, then playback of the current child element is stopped (remaining child elements in the sequence are not played). Stopped mid-song means the rest of the playlist gets ghosted 👻
For example, a request to play a sequence of audio resources in parallel with a video media:
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="c1">
<dialog>
<prompt>
<par endsync="first">
<seq>
<media type="audio/x-wav"
loc="http://www.example.com/media/date.wav"/>
<media type="audio/x-wav"
loc="http://www.example.com/media/intro.wav"/>
<media type="audio/x-wav"
loc="http://www.example.com/media/main.wav"/>
<media type="audio/x-wav"
loc="http://www.example.com/media/end.wav"/>
</seq>
<media type="video/3gpp;codecs='s263'"
loc="rtsp://www.example.com/media/camera.3gp"/>
</par>
</prompt>
</dialog>
</dialogstart>
</mscivr>When the <prompt> element is executed, it begins playback of the <par> element containing a <seq> element and a video <media> element. The <seq> element itself contains a sequence of audio <media> elements. Consequently, playback of the video media resource is initiated at the same time as playback of the sequence of the audio media resources is initiated. Each audio resource is played back after the previous one completes. Since the endsync attribute is set to "first", the <par> element playback is complete when either all the audio resources in <seq> have been played to completion or the video <media> is complete, whichever occurs first. Whichever finishes first wins the whole vibe 🏆
4.3.1.2. <control> 🎮
okay bestie, <control> is the element that decides how DTMF input (aka keypad presses 📞) gets mapped to runtime controls, including the controls for prompt playback. it's giving remote control energy 📺✨
DTMF input matching these controls MUST NOT cause prompt playback to be interrupted (i.e., no prompt bargein) 🙅♀️, but it still triggers the right operation, like speeding up the prompt 🏎️💨.
DTMF input matching these controls has priority over <collect> input for the duration of prompt playback 👑. If an incoming DTMF character matches a specified runtime control, that character gets consumed. it's not added to the digit buffer, so the <collect> operation never sees it 🫣. Once prompt playback is complete, runtime controls are no longer active 💅.
The <control> element has the following attributes:
gotostartkey: maps a DTMF key to skip straight to the start of the prompt ⏮️. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.gotoendkey: maps a DTMF key to skip straight to the end of the prompt ⏭️. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.skipinterval: indicates how far an MS skips backwards or forwards through prompt playback when the rewind (rwkey) of fast forward key (ffkey) is pressed. A valid value is a Time Designation (see Section 4.6.7). The attribute is optional. The default value is6s.ffkey: maps a DTMF key to a fast forward operation equal to the value ofskipinterval. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.rwkey: maps a DTMF key to a rewind operation equal to the value ofskipinterval. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.pauseinterval: indicates how long an MS pauses prompt playback when the pausekey is pressed. A valid value is a Time Designation (see Section 4.6.7). The attribute is optional. The default value is10s.pausekey: maps a DTMF key to a pause operation equal to the value ofpauseinterval. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.resumekey: maps a DTMF key to a resume operation. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.volumeinterval: indicates the increase or decrease in playback volume (relative to the current volume) when thevolupkeyorvoldnkeyis pressed. A valid value is a percentage (see Section 4.6.8). The attribute is optional. The default value is10%.volupkey: maps a DTMF key to a volume increase operation equal to the value ofvolumeinterval. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.voldnkey: maps a DTMF key to a volume decrease operation equal to the value ofvolumeinterval. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.speedinterval: indicates the increase or decrease in playback speed (relative to the current speed) when thespeedupkeyorspeeddnkeyis pressed. A valid value is a percentage (see Section 4.6.8). The attribute is optional. The default value is10%.speedupkey: maps a DTMF key to a speed increase operation equal to the value of thespeedintervalattribute. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.speeddnkey: maps a DTMF key to a speed decrease operation equal to the value of thespeedintervalattribute. A valid value is a DTMF character (see Section 4.6.2). The attribute is optional. There is no default value.external: lets one or more DTMF keys be declared as external controls (think video camera controls 🎥); the MS can send notifications when a matching key is activated using<dtmfnotify>(Section 4.2.5.2). A valid value is a DTMF string (see Section 4.6.3). The attribute is optional. There is no default value.
⚠️ if the same DTMF is specified in more than one DTMF key control attribute, the MS sends a<response>with a413status code (Section 4.5). The exceptions arepausekeyandresumekey, which are allowed to share a key. Don't double-book your keys, bestie 🙈
The MS has the following execution model for runtime control after initialization 🧠:
- If an error occurs during execution, then the MS terminates runtime control and the error is reported to the dialog container. The MS MAY report controls executed successfully before the error in
<controlinfo>(see Section 4.3.2.2) 📝. - Runtime controls are active only during prompt playback. If no
<prompt>element is specified, then runtime controls are ignored 🙃. If DTMF input matches any specified keys (for example, theffkey), then the MS applies the appropriate operation immediately ⚡. If a seek operation (ffkey,rwkey) attempts to go beyond the beginning or end of the prompt queue, then the MS automatically truncates it to the prompt queue beginning or end, respectively ✂️. If a volume operation (voldnkey,volupkey) attempts to go beyond the minimum or maximum volume supported by the platform, then the MS automatically limits the operation to minimum or maximum supported volume, respectively 🔊. If a speed operation (speeddnkey,speedupkey) attempts to go beyond the minimum or maximum playback speed supported by the platform, then the MS automatically limits the operation to minimum or maximum supported speed, respectively 🐢🐇. If the pause operation attempts to pause output when it is already paused, then the operation is ignored. If the resume operation attempts to resume when the prompts are not paused, then the operation is ignored. If a seek, volume, or speed operation is applied when output is paused, then the MS also resumes output automatically ▶️. - If DTMF control subscription has been specified for the dialog, then each DTMF match of a control operation is reported in a
<dtmfnotify>notification event (Section 4.2.5.2) 🔔. - When the dialog exits, all control matches are reported in a
<controlinfo>element (Section 4.3.2.2) 🗂️.
4.3.1.3. <collect> ✨
okay bestie, <collect> is the element that handles how DTMF input gets collected (aka those keypad button presses 📞). it's giving main character energy 💅 and it has a bunch of attributes, so let's go 🎀
cleardigitbuffer🧹: tells us whether the digit buffer gets cleared. The valid value is a boolean (see Section 4.6.1). true means clear it, false means don't. It's optional, and the default is true.timeout⏰: the max time to wait for the user to start punching in digits. The valid value is a Time Designation (see Section 4.6.7). It's optional, and the default is 5s.interdigittimeout🫧: the max time to wait for another DTMF when what's been collected isn't complete yet, grammar-wise. The valid value is a Time Designation (see Section 4.6.7). It's optional, and the default is 2s.termtimeout🛑: the max time to wait for the termchar when what's been collected is already complete, grammar-wise. The valid value is a Time Designation (see Section 4.6.7). It's optional, and the default is 0s (no delay).escapekey🚪: a DTMF key that says "toss the grammar matches and restart collection, bestie." The valid value is a DTMF character (see Section 4.6.2). It's optional, and there's no default value.termchar🍓: a DTMF character that ends collection when we're using the internal grammar. It gets ignored when a custom grammar is specified. The valid value is a DTMF character (see Section 4.6.2). If you want to turn off the conventional terminator, set it to something unconventional like 'A'. It's optional, and the default is '#'.maxdigits🔢: the max number of digits to collect when we're using the internal digits (0-9 only) grammar. It gets ignored when a custom grammar is specified. The valid value is a positive integer (see Section 4.6.5). It's optional, and the default is 5.
There's a matching priority for incoming DTMF, and it goes termchar attribute first, then escapekey attribute, then as part of a grammar. So if "1" is defined as the escapekey attribute AND as part of a grammar, the escapekey wins 👑 ngl that's a very clear hierarchy.
The <collect> element has one child element:
- <grammar> 🧩: indicates a custom grammar format (see Section 4.3.1.3.1). It's optional.
The custom grammar takes priority over the internal grammar. If a <grammar> element is specified, the MS MUST use it for DTMF collection. no exceptions, periodt 💖
Here's the execution model the MS follows for DTMF collection after initialization 🦋
- The DTMF collection buffer MUST NOT receive DTMF input matching <control> operations (see Section 4.3.1.2). the control stuff stays out of the buffer, no cap 🙈
- If an error happens during execution, the MS terminates collection and reports the error to the dialog container (see Section 4.3). The MS MAY report DTMF collected before the error in <collectinfo> (see Section 4.3.2.3). 💀
- The MS clears the digit buffer if the cleardigitbuffer attribute is true. 🧹
- The MS starts an initial timer with the duration of the timeout attribute value. If that timer expires before any DTMF input shows up, collection execution terminates, the <collectinfo> (see Section 4.3.2.3) has the termmode attribute set to noinput, and the execution status gets reported to the dialog container. it's giving "nobody showed up" energy 😭
- When the first DTMF collect input arrives, the initial timer gets canceled and DTMF collection begins. Each DTMF input is collected unless it matches the escapekey attribute value or the termchar attribute value when the internal grammar is used. The collected input gets matched against the grammar to see if it's valid and, if it's valid, whether collection is complete. Valid DTMF patterns are either a simple digit string (max length set by the maxdigits attribute, which can optionally end with the character in the termchar attribute), or a custom DTMF grammar specified with the <grammar> element. ✨
- After escapekey input, or after a valid input that doesn't complete the grammar, the MS starts a timer for the value of the interdigittimeout attribute or the termtimeout attribute. The MS only uses the termtimeout value when the grammar doesn't allow any additional input. Otherwise, the MS uses the interdigittimeout. ⏳
- If DTMF collect input matches the escapekey attribute value, the MS re-initializes DTMF collection. i.e., the MS discards the collected DTMFs already matched against the grammar, and the MS tries to match the incoming DTMF (including anything pending in the digit buffer) like we did in Step 5 above. 🔄
- If the collect input isn't valid with respect to the grammar, or an interdigittimeout timer expires, the MS terminates collection execution and reports the execution status to the dialog container with a <collectinfo> (see Section 4.3.2.3) where the termmode attribute is set to nomatch. 🙅♀️
- If the collect input completes the grammar, or if a termtimeout timer expires, the MS terminates collection execution and reports the execution status to the dialog container with <collectinfo> (see Section 4.3.2.3) where the termmode attribute is set to match. 🎉
4.3.1.3.1. <grammar>
okay so the <grammar> element lets you specify a custom grammar, either inline or external 🎀 Custom grammars can cover the full range of DTMF characters, including '*' and '#', for DTMF pattern matching. literally the whole keypad, slay 🌈
The <grammar> element has these attributes:
src🌐: specifies where an external grammar document lives. The 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 isn't supported, the MS sends a <response> with a 420 status code (Section 4.5). If the resource can't be retrieved within the timeout interval, the MS sends a <response> with a 409 status code. If the grammar format isn't supported, the MS sends a <response> with a 424 status code. It's optional, and there's no default value.type🏷️: identifies the preferred type of the grammar document identified by the src attribute. The 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. It's optional, and there's no default value.fetchtimeout⏱️: the max interval to wait when fetching a grammar resource. The valid value is a Time Designation (see Section 4.6.7). It's optional, and the default is 30s.
The <grammar> element also lets you specify inline grammars. XML grammar formats MUST use a namespace other than the one used in this specification. Non-XML grammar formats MAY use a CDATA section. 🧁
The MS MUST support the Speech Recognition Grammar Specification [SRGS] XML grammar format ("application/srgs+xml"). The MS MAY support the Key Press Markup Language (KPML) [RFC4730] or other grammar formats. If the MS doesn't support the grammar format, it sends a <response> with a 424 status code (Section 4.5). 💅
Here's an example of DTMF collection with an inline SRGS grammar 🦋
<collect cleardigitbuffer="false" timeout="20s"
interdigittimeout="1s">
<grammar>
<grammar xmlns="http://www.w3.org/2001/06/grammar"
version="1.0" mode="dtmf">
<rule id="digit">
<one-of>
<item>0</item>
<item>1</item>
<item>2</item>
<item>3</item>
<item>4</item>
<item>5</item>
<item>6</item>
<item>7</item>
<item>8</item>
<item>9</item>
</one-of>
</rule>
<rule id="pin" scope="public">
<one-of>
<item>
<item repeat="4">
<ruleref uri="#digit"/>
</item>#</item>
<item>* 9</item>
</one-of>
</rule>
</grammar>
</grammar>
</collect>The same grammar can also be referenced externally (and take advantage of HTTP caching) 🌸
<collect cleardigitbuffer="false" timeout="20s">
<grammar type="application/srgs+xml"
src="http://example.org/pin.grxml"/>
</collect>4.3.1.4. <record> 🎙️
okay so <record> is the element that handles recording media input, and it is giving main character energy 💅 It has the following attributes:
timeout: this is how long the MS waits for user input to begin 🕰️ A valid value is a Time Designation (see Section 4.6.7). The attribute is optional. The default value is5s.vadinitial: this one controls whether Voice Activity Detection (VAD) is used to kick off the recording 🎤 A valid value is a boolean (see Section 4.6.1). If it'strue, the MS MUST initiate recording if the VAD detects voice on the configured inbound audio streams. If it'sfalse, the MS MUST NOT initiate recording using VAD. The attribute is optional. The default value isfalse.vadfinal: this controls whether VAD is used to end the recording 🛑 A valid value is a boolean (see Section 4.6.1). If it'strue, the MS MUST terminate recording if the VAD detects a period of silence (whose duration is set by thefinalsilenceattribute) on configured inbound audio streams. If it'sfalse, the MS MUST NOT terminate recording using VAD. The attribute is optional. The default value isfalse.dtmfterm: this tells you whether the recording gets ended by DTMF input 🔢 A valid value is a boolean (see Section 4.6.1). A value oftruemeans recording is terminated by DTMF input. A value offalsemeans recording is not terminated by DTMF input. The attribute is optional. The default value istrue.maxtime: the maximum duration of the recording ⏱️ A valid value is a Time Designation (see Section 4.6.7). The attribute is optional. The default value is15s.beep: decides whether a 'beep' plays right before the recording starts 🔊 A valid value is a boolean (see Section 4.6.1). The attribute is optional. The default value isfalse.finalsilence: the stretch of silence that signals the end of voice input 🤫 That silence is not part of the recording itself. This parameter is ignored if thevadfinalattribute has the valuefalse. A valid value is a Time Designation (see Section 4.6.7). The attribute is optional. The default value is5s.append: decides whether recorded data gets added onto a recording location that already has a resource 📎 A valid value is a boolean (see Section 4.6.1). A value oftruemeans the recorded data is appended to the existing resource at the recording location. A value offalsemeans the recorded data overwrites the existing resource. The attribute is optional. The default value isfalse.
When a recording location is specified using the HTTP or HTTPS protocol, the recording operation SHOULD be performed using the HTTP GET and PUT methods, unless the HTTP server provides a special interface for recording uploads and appends (e.g., using POST). When the append attribute has the value false, the recording data is uploaded to the specified location using HTTP PUT and replaces any data at that location on the HTTP origin server. When append has the value true, the existing data (if any) is first downloaded from the specified location using HTTP GET. Then the recording data is appended to the existing recording (note that this might require codec conversion and modification to the existing data), and the combined recording is uploaded to the specified location using HTTP PUT. HTTP errors are handled as described in [RFC2616].
When the recording location is specified using protocols other than HTTP or HTTPS, the mapping of the append operation onto the upload protocol scheme is implementation specific.
If either the vadinitial or vadfinal attribute is set to true and the MS does not support VAD, the MS sends a <response> with a 434 status code (Section 4.5).
The <record> element has the following child element (0 or more occurrences):
<media>: this specifies the location and type of the media resource for uploading recorded data (see Section 4.3.1.5) 📤 The MS MUST support both HTTP [RFC2616] and HTTPS [RFC2818] schemes for uploading recorded data, and the MS MAY support other schemes. The MS uploads recorded data to this resource as soon as possible after recording is complete. The element is optional.
If multiple <media> elements are specified, then media input is to be recorded in parallel to multiple resource locations 👯
If no <media> child element is specified, the MS MUST record media input. The recording location and the recording format are implementation specific (e.g., the MS records audio in the WAV format to a local disk accessible by HTTP) 💾 The recording location and format are reported in <recordinfo> (Section 4.3.2.4) when the dialog terminates. The recording MUST be available from this location until the connection or conference associated with the dialog on the MS terminates.
If the MS does not support the configuration required for recording from the input media streams to one or more <media> elements, and a more specific error code is not defined for its child elements, the MS sends a <response> with a 423 status code (Section 4.5) 🙅
Note that an MS MAY support uploading recorded data to recording locations at the same time the recording operation takes place. Such implementations need to be aware of the requirements of certain recording formats (e.g., WAV) for metadata at the beginning of the uploaded file, that the finalsilence interval is not part of the recording, and how these requirements interact with the URI scheme. 🧠
The MS has the following execution model for recording after initialization ✨
- If an error occurs during execution (e.g., an authentication or communication error when trying to upload to a recording location), the MS terminates record execution and reports the error to the dialog container (see Section 4.3). The MS MAY report data recorded before the error in
<recordinfo>(see Section 4.3.2.4). - If DTMF input (not matching a
<control>operation) is received during prompt playback and thepromptbargeinattribute is set totrue, the MS activates the record execution. Otherwise, the MS activates it after the completion of prompt playback. - If a
beepattribute with the value oftrueis specified, the MS plays a beep tone 🎶 - The MS activates a timer with the duration of the value of the
timeoutattribute. If the timer expires before the recording operation begins, the MS terminates the recording execution and reports the status to the dialog container with<recordinfo>(see Section 4.3.2.4), where thetermmodeattribute is set tonoinput. 😬 - Initiation of the recording operation depends on the value of the
vadinitialattribute. Ifvadinitialhas the valuefalse, the recording operation is initiated immediately. Otherwise, it is initiated when voice activity is detected. - When the recording operation is initiated, a timer is started for the value of the
maxtimeattribute (the maximum duration of the recording). If the timer expires before the recording operation is complete, the MS terminates recording execution and reports the execution status to the dialog container with<recordinfo>(see Section 4.3.2.4), where thetermmodeattribute is set tomaxtime. ⏰ - During the record operation, input media streams are recorded to a location and format specified in one or more
<media>child elements. If no<media>child element is specified, the MS records input to an implementation-specific location and format. - If the
dtmftermattribute has the valuetrueand DTMF input is detected during the record operation, the MS terminates recording, and its status is reported to the dialog container with a<recordinfo>(see Section 4.3.2.4), where thetermmodeattribute is set todtmf. 📟 - If the
vadfinalattribute has the valuetrue, the MS terminates the recording operation when a period of silence, with the duration specified by the value of thefinalsilenceattribute, is detected. This period of silence is not part of the final recording. The status is reported to the dialog container with a<recordinfo>(see Section 4.3.2.4), where thetermmodeattribute is set tofinalsilence. 🫶
For example, here's a request to record audio and video input to separate locations 🎬
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="c1">
<dialog>
<record maxtime="30s" vadinitial="false" vadfinal="false">
<media type="audio/x-wav"
loc="http://www.example.com/upload/audio.wav"/>
<media type="video/3gpp;codecs='s263'"
loc="http://www.example.com/upload/video.3gp"/>
</record>
</dialog>
</dialogstart>
</mscivr>When the <record> element is executed, it immediately begins recording the audio and video (since vadinitial is false), and the destination locations are specified in the <media> child elements. Recording is completed when the duration reaches 30s or the connection is terminated 🌸
4.3.1.5. <media> 🎀
okay bestie, so <media> is the element that says which media file to play (see Section 4.3.1.1) or where to record to (see Section 4.3.1.4) 🎧. For playback, the resource gets retrieved. For recording, the recording data gets uploaded to that location 🦋.
A <media> element has the following attributes ✨:
loc: this is where the media lives 📍. 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 isn't supported by the MS, it sends a <response> with a 420 status code (Section 4.5) 💀. If the resource is supposed to be retrieved but the MS can't get it within the timeout interval, it sends a <response> with a 409 status code. If the format of the media resource isn't supported, the MS sends a <response> with a 429 status code. This attribute is mandatory 🫶.
type: this is the MIME media type of the resource named in the loc attribute 🎬. A valid value is a MIME media type (see Section 4.6.10) that, depending on its definition, can include additional parameters (e.g., [RFC4281]). If the URI scheme used in the loc 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. If additional media parameters are specified, the MS MUST use them to determine media processing. For example, [RFC4281] defines a 'codec' parameter for media types like video/3gpp that would determine which media streams are played or recorded. This attribute is optional, and there is no default value 🌸.
fetchtimeout: the longest the MS will wait when fetching a media resource ⏳. A valid value is a Time Designation (see Section 4.6.7). This attribute is optional, and the default value is 30s.
soundLevel: the playback volume for the media resource 🔊. A valid value is a percentage (see Section 4.6.8). The value is an increase or decrease relative to the original recorded volume of the media. 100% (the default) plays the media at its recorded volume, 200% plays it at twice the recorded volume, 50% plays it at half, and 0% plays it silently, and so on. See 'soundLevel' in SMIL [W3C.REC-SMIL2-20051213] for further information. This attribute is optional, and the default value is 100%.
clipBegin: where playback starts, measured as an offset from the start of the media resource ✂️. A valid value is a Time Designation (see Section 4.6.7). The offset is measured in normal media playback time from the beginning of the media resource. If the clipBegin offset is after the end of the media (or the clipEnd offset), no media is played. See 'clipBegin' in SMIL [W3C.REC-SMIL2-20051213] for further information. This attribute is optional, and the default value is 0s.
clipEnd: where playback stops, also an offset from the start of the media resource 🛑. A valid value is a Time Designation (see Section 4.6.7). The offset is measured in normal media playback time from the beginning of the media resource. If the clipEnd offset is after the end of the media, then the media is played to the end. If clipBegin is after clipEnd, then no media is played. See 'clipEnd' in SMIL [W3C.REC-SMIL2-20051213] for further information. This attribute is optional, and there is no default value.
fetchtimeout, soundLevel, clipBegin, and clipEnd only matter for playback. When the <media> is used for recording, the MS ignores all of them 🙈.
The <media> element has no children 💅.
4.3.2. Exit Information 🚪
When the dialog exits, the info about the operations you specified gets reported in a <dialogexit> notification event (Section 4.2.5.1) 🦋.
4.3.2.1. <promptinfo> 📢
The <promptinfo> element reports the info about how prompt execution went ✨. It has the following attributes:
duration: how long the prompt played, in milliseconds ⏱️. A valid value is a non-negative integer (see Section 4.6.4). This attribute is optional, and there is no default value.
termmode: how playback ended 🏁. Valid values are 'stopped', 'completed', or 'bargein'. This attribute is mandatory.
The <promptinfo> element has no child elements.
4.3.2.2. <controlinfo> 🎮
The <controlinfo> element reports info about control execution 🕹️.
The <controlinfo> element has no attributes, and it has 0 or more <controlmatch> child elements, each describing one individual runtime control match 💜.
4.3.2.2.1. <controlmatch> 🎯
The <controlmatch> element has the following attributes:
dtmf: the DTMF input that triggered the runtime control 🔢. A valid value is a DTMF string (see Section 4.6.3) with no space between characters. This attribute is mandatory.
timestamp: when the control got triggered, from the MS's point of view ⏰. A valid value is a dateTime expression (Section 4.6.12). This attribute is mandatory.
The <controlmatch> element has no child elements.
4.3.2.3. <collectinfo> 🧺
The <collectinfo> element reports info about collect execution 📥.
The <collectinfo> element has the following attributes:
dtmf: the DTMF input collected from the user 🔢. A valid value is a DTMF string (see Section 4.6.3) with no space between characters. This attribute is optional, and there is no default value.
termmode: how collection ended 🏁. Valid values are 'stopped', 'match', 'noinput', or 'nomatch'. This attribute is mandatory.
The <collectinfo> element has no child elements.
4.3.2.4. <recordinfo> 🎙️
The <recordinfo> element reports info about record execution (Section 4.3.1.4) 🎤.
The <recordinfo> element has the following attributes:
termmode: how recording ended 🏁. Valid values are 'stopped', 'noinput', 'dtmf', 'maxtime', and 'finalsilence'. This attribute is mandatory.
duration: how long the recording was, in milliseconds ⏱️. A valid value is a non-negative integer (see Section 4.6.4). This attribute is optional, and there is no default value.
The <recordinfo> element has the following child element (0 or more occurrences) 👯:
<mediainfo>: info about a recorded media resource (see Section 4.3.2.4.1). This element is optional.
When the record operation succeeds, the MS MUST specify a <mediainfo> element for each recording location. For example, if the <record> element had three <media> child elements, then the <recordinfo> would have three <mediainfo> child elements 🍓.
4.3.2.4.1. <mediainfo> 🗂️
The <mediainfo> element reports info about a recorded media resource.
The <mediainfo> element has the following attributes:
loc: where the media resource is located 📍. A valid value is a URI (see Section 4.6.9). This attribute is mandatory.
type: the format of the media resource 🎞️. A valid value is a MIME media type (see Section 4.6.10). This attribute is mandatory.
size: how big the media resource is, in bytes 📦. A valid value is a non-negative integer (see Section 4.6.4). This attribute is optional, and there is no default value.
4.4. Audit Elements 🔍
The audit elements in this section let the MS be audited for package capabilities, as well as for dialogs the package manages 💖. Auditing matters for two main use cases. First, it lets you discover which package capabilities an MS supports before an AS starts a dialog on a connection or conference. The AS can then use that info to build request elements with supported capabilities and, for codecs, negotiate an appropriate SDP for a User Agent's connection. Second, auditing lets you discover whether dialogs are currently managed by the package on the MS, and what state they're in. This could come in handy when one AS takes over managing the dialogs because the AS that started them failed or is no longer around (see Security Considerations described in Section 7) 👑.
4.4.1. <audit> 🕵️♀️
The <audit> request element gets sent to the MS to ask for info about the capabilities of this Control Package, and about dialogs currently managed with it 💅. Capabilities include supported dialog languages, grammar formats, record and media types, and codecs. Dialog info includes the status of managed dialogs, as well as codecs.
The <audit> element has the following attributes:
capabilities: whether package capabilities should be audited 🧠. A valid value is a boolean (see Section 4.6.1). A value of true means capability info should be reported. A value of false means it shouldn't. This attribute is optional, and the default value is true.
dialogs: whether dialogs currently managed by the package should be audited 📋. A valid value is a boolean (see Section 4.6.1). A value of true means dialog info should be reported. A value of false means it shouldn't. This attribute is optional, and the default value is true.
dialogid: a string identifying one specific dialog to audit 🆔. The MS sends a response with a 406 status code (Section 4.5) if the dialog identifier you gave is invalid. This attribute is optional, and there is no default value.
If the dialogs attribute is true and the dialogid attribute is specified, then only the audit info for that specified dialog gets reported. If the dialogs attribute is false, then no dialog audit info gets reported, even if a dialogid attribute is specified 🙃.
The <audit> element has no child elements.
When the MS gets an <audit> request, it MUST reply with an <auditresponse> element (Section 4.4.2). That reply includes a mandatory attribute describing the status with a numeric code. Response status codes are defined in Section 4.5. If the request succeeds, the <auditresponse> contains (depending on the attribute values) a <capabilities> element (Section 4.4.2.2) reporting package capabilities, and a <dialogs> element (Section 4.4.2.3) reporting managed dialog info. If the MS can't process the request and carry out the audit operation, the audit 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 when deciding the appropriate status code for the response 🧁.
For example, here's a request to audit capabilities and managed dialogs for the package:
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<audit/>
</mscivr>In this example, only capabilities get audited:
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<audit dialogs="false"/>
</mscivr>And with this example, only one specific dialog gets audited 🦋:
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<audit capabilities="false" dialogid="d4"/>
</mscivr>4.4.2. <auditresponse> 💖
The <auditresponse> element is the answer to an <audit> request, so it's basically the receipt that says what the MS is working with 🧾✨
The <auditresponse> element has these attributes:
- status: a numeric code that shows the audit response status. This one is mandatory 🫶 Valid values are defined in Section 4.5.
- reason: a string that explains the status. Optional.
- desclang: says which language is used in the value of the reason attribute. A valid value is a language identifier (Section 4.6.11). Optional. If you don't set it, the desclang attribute on
<mscivr>(Section 4.1) applies, so it just inherits the parent's language 💅
The <auditresponse> element has these child elements, in this order:
<capabilities>(Section 4.4.2.2) describes the package's capabilities. Optional.<dialogs>(Section 4.4.2.3) describes info about managed dialogs. Optional.
Here's a successful response to an <audit> request asking for capabilities and dialogs info. It's giving full spec sheet energy 🎀
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<auditresponse status="200">
<capabilities>
<dialoglanguages>
<mimetype>application/voicexml+xml</mimetype>
</dialoglanguages>
<grammartypes/>
<recordtypes>
<mimetype>audio/x-wav</mimetype>
<mimetype>video/3gpp</mimetype>
</recordtypes>
<prompttypes>
<mimetype>audio/x-wav</mimetype>
<mimetype>video/3gpp</mimetype>
</prompttypes>
<variables>
<variabletype type="date" desc="value formatted as YYYYMMDD">
<format desc="month year day">mdy</format>
<format desc="year month day">ymd</format>
<format desc="day month year">dmy</format>
<format desc="day month">dm</format>
</variabletype>
</variables>
<maxpreparedduration>600s</maxpreparedduration>
<maxrecordduration>1800s</maxrecordduration>
<codecs>
<codec name="video">
<subtype>H263</subtype>
</codec>
<codec name="video">
<subtype>H264</subtype>
</codec>
<codec name="audio">
<subtype>PCMU</subtype>
</codec>
<codec name="audio">
<subtype>PCMA</subtype>
</codec>
<codec name="audio">
<subtype>telephone-event</subtype>
</codec>
</codecs>
</capabilities>
<dialogs>
<dialogaudit dialogid="4532" state="preparing"/>
<dialogaudit dialogid="4599" state="prepared"/>
<dialogaudit dialogid="1234" state="started" conferenceid="conf1">
<codecs>
<codec name="audio">
<subtype>PCMA</subtype>
</codec>
<codec name="audio">
<subtype>telephone-event</subtype>
</codec>
</codecs>
</dialogaudit>
</dialogs>
</auditresponse>
</mscivr>4.4.2.1. <codecs> 🎶
The <codecs> element gives you audit info about codecs. It's basically the codec roster 🦋
The <codecs> element has no attributes.
The <codecs> element has this sequence of child elements (0 or more occurrences):
<codec>: audit info for a single codec (Section 4.4.2.1.1). Optional.
Here's a quick fragment describing two codecs:
<codecs>
<codec name="audio">
<subtype>PCMA</subtype>
</codec>
<codec name="audio">
<subtype>telephone-event</subtype>
</codec>
</codecs>4.4.2.1.1. <codec> 🌸
The <codec> element describes a codec on the MS. It's modeled on the <codec> element in the XCON conference information data model [XCON-DATA-MODEL], but it's extra flexible because it lets you add more info (e.g., rate, speed, etc.) 🤩
The <codec> element has this attribute:
- name: the type name of the codec's media format, as defined in [IANA]. A valid value is a "type-name" as defined in Section 4.2 of [RFC4288]. This one is mandatory ✨
The <codec> element has this sequence of child elements:
<subtype>: an element whose content model describes the subtype of the codec's media format, as defined in [IANA]. A valid value is a "subtype-name" as defined in Section 4.2 of [RFC4288]. This one is mandatory 💅<params>: an element (Section 4.2.6) describing extra info about the codec. This package doesn't care about the names and values of the codec parameters an implementation supports, so it's totally agnostic on that front 🙈 This element is optional.
Here's a fragment with a <codec> element describing the H263 video codec:
<codec name="video">
<subtype>H263</subtype>
</codec>4.4.2.2. <capabilities> 🧁
The <capabilities> element gives you audit info about package capabilities. Think of it as the menu of everything the package can do 🍓
The <capabilities> element has no attributes.
The <capabilities> element has this sequence of child elements:
<dialoglanguages>: an element (Section 4.4.2.2.1) describing extra dialog languages the MS supports. This one is mandatory.<grammartypes>: an element (Section 4.4.2.2.2) describing the supported<grammar>(Section 4.3.1.3.1) format types. This one is mandatory.<recordtypes>: an element (Section 4.4.2.2.3) describing the<media>(Section 4.3.1.5) format types supported for<record>(Section 4.3.1.4). This one is mandatory.<prompttypes>: an element (Section 4.4.2.2.4) describing the supported<media>(Section 4.3.1.5) format types for playback within a<prompt>(Section 4.3.1.1). This one is mandatory.<variables>: an element (Section 4.4.2.2.5) describing the supported types and formats for the<variable>element (Section 4.3.1.1.1). This one is mandatory.<maxpreparedduration>: an element (Section 4.4.2.2.6) describing the supported maximum duration for a prepared dialog following a<dialogprepare>(Section 4.2.1) request. This one is mandatory.<maxrecordduration>: an element (Section 4.4.2.2.7) describing the supported maximum duration for a recording<record>(Section 4.3.1.4) request. This one is mandatory.<codecs>: an element (Section 4.4.2.1) describing the codecs available to the package. This one is mandatory.
Here's a fragment describing capabilities:
<capabilities>
<dialoglanguages>
<mimetype>application/voicexml+xml</mimetype>
</dialoglanguages>
<grammartypes/>
<recordtypes>
<mimetype>audio/x-wav</mimetype>
<mimetype>video/3gpp</mimetype>
</recordtypes>
<prompttypes>
<mimetype>audio/x-wav</mimetype>
<mimetype>video/3gpp</mimetype>
</prompttypes>
<variables/>
<maxpreparedduration>30s</maxpreparedduration>
<maxrecordduration>60s</maxrecordduration>
<codecs>
<codec name="video">
<subtype>H263</subtype>
</codec>
<codec name="video">
<subtype>H264</subtype>
</codec>
<codec name="audio">
<subtype>PCMU</subtype>
</codec>
<codec name="audio">
<subtype>PCMA</subtype>
</codec>
<codec name="audio">
<subtype>telephone-event</subtype>
</codec>
</codecs>
</capabilities>4.4.2.2.1. <dialoglanguages> 🌍
The <dialoglanguages> element gives info about extra dialog languages the package supports. Dialog languages are identified by their associated MIME media types 🫶 The MS MUST NOT include the mandatory dialog language for this package (Section 4.3). Don't double up on the required one, bestie 🙅♀️
The <dialoglanguages> element has no attributes.
The <dialoglanguages> element has this sequence of child elements (0 or more occurrences):
<mimetype>: an element whose content model describes a MIME media type (Section 4.6.10) associated with a supported dialog language. Optional.
4.4.2.2.2. <grammartypes> 🧩
The <grammartypes> element gives info about <grammar> format types the package supports. The MS MUST NOT include the mandatory SRGS format type, "application/srgs+xml" (Section 4.3.1.3.1). That one's already built in, so no repeats 💖
The <grammartypes> element has no attributes.
The <grammartypes> element has this sequence of child elements (0 or more occurrences):
<mimetype>: an element whose content model describes a MIME type (Section 4.6.10). Optional.
4.4.2.2.3. <recordtypes> 🎙️
The <recordtypes> element gives info about the media resource format types of <record> that the package supports (Section 4.3.1.4). It's the list of formats you can actually record in 🎬
The <recordtypes> element has no attributes.
The <recordtypes> element has this sequence of child elements (0 or more occurrences):
<mimetype>: an element whose content model describes a MIME type (Section 4.6.10). Optional.
4.4.2.2.4. <prompttypes> 🔊
The <prompttypes> element gives info about the media resource format types of <prompt> that the package supports (Section 4.3.1.1). This is the playback menu 🎧
The <prompttypes> element has no attributes.
The <prompttypes> element has this sequence of child elements (0 or more occurrences):
<mimetype>: an element whose content model describes a MIME type (Section 4.6.10). Optional.
4.4.2.2.5. <variables> 🔢
The <variables> element gives info about the types and formats for the <variable> element (Section 4.3.1.1.1) that the package supports. It's giving "what can I put in here" vibes ✨
The <variables> element has no attributes.
The <variables> element has this sequence of child elements (0 or more occurrences):
<variabletype>: an element describing the formats supported for a given type (Section 4.4.2.2.5.1). Optional.
Here's an example fragment showing support for <variable> with a "date" type, following the formats in Section 4.3.1.1.1.1:
<variables>
<variabletype type="date" desc="value formatted as YYYYMMDD">
<format desc="month year day">mdy</format>
<format desc="year month day">ymd</format>
<format desc="day month year">dmy</format>
<format desc="day month">dm</format>
</variabletype>
</variables>4.4.2.2.5.1. <variabletype> 📅
The <variabletype> element describes the formats supported for a <variable> type that's supported 🧁
The <variabletype> element has these attributes:
- type: a supported value associated with the type attribute of the
<variable>element. This one is mandatory. - desc: a string with some textual description of the type and format. Optional.
- desclang: says which language is used in the value of the desc attribute. A valid value is a language identifier (Section 4.6.11). Optional. If you don't set it, the desclang attribute on
<mscivr>(Section 4.1) applies 💅
The <variabletype> element has this sequence of child elements (0 or more occurrences):
<format>: an element with a desc attribute (optional description), a desclang attribute (optional language identifier for the description), and a content model describing a supported format in the<variable>format attribute. Optional.
4.4.2.2.6. <maxpreparedduration> ⏳
The <maxpreparedduration> element describes the maximum time a dialog can stay in the prepared state (Section 4.2) after a <dialogprepare> (Section 4.2.1) request. It's the "don't leave me waiting forever" limit 🙈
The <maxpreparedduration> element has no attributes.
The <maxpreparedduration> element has a content model describing the maximum prepared dialog duration as a time designation (Section 4.6.7). Basically, you write the time, and it's locked in 🔐
4.4.2.2.7. <maxrecordduration> 🎀
okay so <maxrecordduration> is the element that tells the AS the longest a recording can be for a <record> request (Section 4.3.1.4) that the MS supports 🎙️✨ it's giving "here's my limit, don't push it" energy 💅
the <maxrecordduration> element has no attributes 🫶
its content model describes the maximum duration of recording as a time designation (Section 4.6.7) ⏱️ so the value is a time designation, no cap 🧁
4.4.2.3. <dialogs>
the <dialogs> element is where the audit info about dialogs lives 📋💖
it has no attributes, bestie 🙈
it has the following sequence of child elements (0 or more occurrences):
<dialogaudit>: audit information for a dialog (Section 4.4.2.3.1). the element is optional 🌸
4.4.2.3.1. <dialogaudit>
the <dialogaudit> element has the following attributes 👑
dialogid: a string identifying the dialog. this one is mandatory, so you can't skip it 🔥state: a string indicating the state of the dialog. the valid values arepreparing,prepared,starting, andstarted. this one is also mandatory 🥹connectionid: a string identifying the SIP dialog connection associated with the dialog (see Appendix A.1 of [RFC6230]). this one is optional, and there is no default value 🦋conferenceid: a string identifying the conference associated with the dialog (see Appendix A.1 of [RFC6230]). also optional, and also no default value 🌈
the <dialogaudit> element has the following child element:
<codecs>: an element describing the codecs used in the dialog. see Section 4.4.2.1. it's optional 🎧
here's an example fragment describing a started dialog that's using PCMU and telephony-event audio codecs, and honestly it's so clean 🧚
<dialogaudit dialogid="1234" state="started" conferenceid="conf1">
<codecs>
<codec name="audio">
<subtype>PCMU</subtype>
</codec>
<codec name="audio">
<subtype>telephone-event</subtype>
</codec>
</codecs>
</dialogaudit>4.5. Response Status Codes ✨
this section is all about the response codes in Table 1 for the status attribute of dialog management <response> (Section 4.2.4) and audit <auditresponse> (Section 4.4.2) responses 📊 the MS MUST support the status response codes defined here 💅 every other valid but undefined value is reserved for future use, and new status codes get assigned through the Standards Action process defined in [RFC5226] 🔮 and the AS MUST treat any responses it doesn't recognize as equivalent to the x00 response code for all classes 🫣
for example, if an AS gets an unrecognized response code of 499, it can safely assume something went wrong with its request and treat the response like it got a 400 (Syntax error) response code 🙃
4xx responses are definite failure responses from a particular MS 💀 the reason attribute in the response SHOULD identify the failure in more detail, like "Mandatory attribute missing: src in media element" for a 400 (Syntax error) response code 📝
the AS SHOULD NOT retry the same request without modification (for example, fixing a syntax error or changing the connectionid to one that's available on the MS) 🛑 however, the same request sent to a different MS might succeed, for example if that MS supports a capability the request needs 🌟
4xx failure responses sort into three classes 🍓
- failure due to a syntax error in the request (
400) - failure due to an error executing the request on the MS (
405-419) - failure due to the request needing a capability the MS doesn't support (
420-439)
when more than one request code could be reported for a failure, the MS SHOULD use the most specific error code of the failure class for the error it detected 🎯 for example, if the MS detects that the dialogid in the request is invalid, it uses a 406 status code 💖 but if the MS just detects that an execution error occurred, then 419 is used 🫶
+------+---------------+-----------------------+--------------------+
| Code | Summary | Description | Informational: AS |
|---|---|---|---|
| Possible Recovery | |||
| Action |
+------+---------------+-----------------------+--------------------+
| 200 | OK | request has | |
|---|---|---|---|
| succeeded. | |||
| 400 | Syntax error | request is | Change the request |
| syntactically | so that it is | ||
| invalid: it is not | syntactically | ||
| valid with respect to | valid. | ||
| the XML schema | |||
| specified in | |||
| Section 5 or it | |||
| violates a | |||
| co-occurrence | |||
| constraint for a | |||
| request element | |||
| defined in Section 4. | |||
| 405 | dialogid | request uses a | Send a request for |
| already | dialogid identifier | a new dialog | |
| exists | for a new dialog that | without specifying | |
| is already used by | the dialogid and | ||
| another dialog on the | let the MS | ||
| MS (see Section 4.2). | generate a unique | ||
| dialogid in the | |||
| response. | |||
| 406 | dialogid does | request uses a | Send an <audit> |
| not exist | dialogid identifier | request | |
| for an dialog that | (Section 4.4.1) | ||
| does not exist on the | requesting the | ||
| MS (see Section 4.2). | list of dialog | ||
| identifiers | |||
| already used by | |||
| the MS and then | |||
| use one of the | |||
| listed dialog | |||
| identifiers. | |||
| 407 | connectionid | request uses a | Use another method |
| does not | connectionid | to determine which | |
| exist | identifier for a | connections are | |
| connection that does | available on the | ||
| not exist on the MS. | MS. | ||
| 408 | conferenceid | request uses a | Use another method |
| does not | conferenceid | to determine which | |
| exist | identifier for a | conferences are | |
| conference that does | available on the | ||
| not exist on the MS. | MS. | ||
| 409 | Resource | request uses a URI to | Check that the |
| cannot be | reference an external | resource URI is | |
| retrieved | resource (e.g., | valid, can be | |
| dialog, media, or | reached from the | ||
| grammar) that cannot | MS, and that the | ||
| be retrieved within | appropriate | ||
| the timeout interval. | authentication is | ||
| used. | |||
| 410 | Dialog | request to prepare or | |
| execution | start a dialog that | ||
| canceled | has been terminated | ||
| by a | |||
| <dialogterminate/> | |||
| request (see | |||
| Section 4.2). | |||
| 411 | Incompatible | request specifies a | Change the media |
| stream | media stream | stream | |
| configuration | configuration that is | configuration to | |
| in conflict with | match the | ||
| itself, or the | capabilities of | ||
| connection or | the connection or | ||
| conference | conference. | ||
| capabilities (see | |||
| Section 4.2.2). | |||
| 412 | Media stream | request specifies an | Check the media |
| not available | operation for which a | stream capability | |
| media stream is not | of the connection | ||
| available. For | or conference and | ||
| example, playing a | use an operation | ||
| video media resource | that only uses | ||
| on an connection or | these | ||
| conference without | capabilities. | ||
| video streams. | |||
| 413 | Control keys | request contains a | Use different keys |
| with same | <control> element | for the different | |
| value | (Section 4.3.1.2) | control | |
| where some keys have | operations. | ||
| the same value. | |||
| 419 | Other | requested operation | |
| execution | cannot be executed by | ||
| error | the MS. | ||
| 420 | Unsupported | request specifies a | Use a URI scheme |
| URI scheme | URI whose scheme is | that is supported. | |
| not supported by the | |||
| MS. | |||
| 421 | Unsupported | request references an | Send an <audit> |
| dialog | external dialog | request | |
| language | language not | (Section 4.4.1) | |
| supported by the MS. | requesting the MS | ||
| capabilities and | |||
| then use one of | |||
| the listed dialog | |||
| languages. | |||
| 422 | Unsupported | request references a | Send an <audit> |
| playback | media resource for | request | |
| format | playback whose format | (Section 4.4.1) | |
| is not supported by | requesting the MS | ||
| the MS. | capabilities and | ||
| then use one of | |||
| the listed | |||
| playback media | |||
| formats. | |||
| 423 | Unsupported | request references a | Send an <audit> |
| record format | media resource for | request | |
| recording whose | (Section 4.4.1) | ||
| format is not | requesting the MS | ||
| supported by the MS. | capabilities and | ||
| then use one of | |||
| the listed record | |||
| media formats. | |||
| 424 | Unsupported | request references a | Send an <audit> |
| grammar | grammar whose format | request | |
| format | is not supported by | (Section 4.4.1) | |
| the MS. | requesting the MS | ||
| capabilities and | |||
| then use one of | |||
| the listed grammar | |||
| types. | |||
| 425 | Unsupported | request contains a | Send an <audit> |
| variable | prompt <variable> | request | |
| configuration | element | (Section 4.4.1) | |
| (Section 4.3.1.1.1) | requesting the MS | ||
| not supported by the | capabilities and | ||
| MS. | then use one of | ||
| the listed | |||
| variable types. | |||
| 426 | Unsupported | request contains a | |
| DTMF | prompt <dtmf> element | ||
| configuration | (Section 4.3.1.1.2) | ||
| not supported by the | |||
| MS. | |||
| 427 | Unsupported | request contains a | |
| parameter | <param> element | ||
| (Section 4.2.6.1) not | |||
| supported by the MS. | |||
| 428 | Unsupported | request contains a | |
| media stream | <stream> element | ||
| configuration | (Section 4.2.2.2) | ||
| whose configuration | |||
| is not supported by | |||
| the MS. | |||
| 429 | Unsupported | request contains a | |
| playback | <prompt> element | ||
| configuration | (Section 4.3.1.1) | ||
| that the MS is unable | |||
| to play on the | |||
| available output | |||
| media streams. | |||
| 430 | Unsupported | request contains a | |
| record | <record> element | ||
| configuration | (Section 4.3.1.4) | ||
| that the MS is unable | |||
| to record with on the | |||
| available input media | |||
| streams. | |||
| 431 | Unsupported | request contains |
| | foreign | attributes or | |
| | namespace | elements from another | |
| | attribute or | namespace that the MS | |
| | element | does not support. | |
| 432 | Unsupported | request tries to | |
| | multiple | start another dialog | |
| | dialog | on the same | |
| | capability | conference or | |
| | | connection where a | |
| | | dialog is already | |
| | | running. | |
| 433 | Unsupported | request contains | |
| | collect and | <collect> and | |
| | record | <record> elements and | |
| | capability | the MS does support | |
| | | these operations | |
| | | simultaneously. | |
| 434 | Unsupported | request contains a | |
| | VAD | <record> element | |
| | capability | where Voice Activity | |
| | | Detection (VAD) is | |
| | | required, but the MS | |
| | | does not support VAD. | |
| 435 | Unsupported | request contains a | |
| | parallel | prompt <par> element | |
| | playback | whose configuration | |
| | | is not supported by | |
| | | the MS. | |
| 439 | Other | request requires | |
| | unsupported | another capability | |
| | capability | not supported by the | |
| | | MS. | |
+------+---------------+-----------------------+--------------------+
Table 1: Status CodesOkay, the status code table wraps up here, bestie 🎀 Next up is the type definitions section, where we get to decide what the building blocks of all these elements actually look like 🧚
4.6. Type Definitions ✨
This section defines the types that the attribute and element definitions refer to. Think of it as the glossary that makes everything else make sense 💅
4.6.1. Boolean 💖
The value space of boolean is the set {true, false, 1, 0} as defined in Section 3.2.2 of [XMLSchema:Part2]. Following that definition, the concept of false can be lexically represented by the strings "0" and "false", and the concept of true by the strings "1" and "true". Implementations MUST support both styles of lexical representation 🫶
4.6.2. DTMFChar 🎀
A DTMF character. Its value space is the set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *, A, B, C, D} 🔥
4.6.3. DTMFString 🍓
A string made up of one or more DTMFChars 🌸
4.6.4. Non-Negative Integer 🦋
The value space of non-negative integer is the infinite set {0,1,2,...} as defined in Section 3.3.20 of [XMLSchema:Part2] ✨
Implementation Note: It is RECOMMENDED that implementations at least support a maximum value of a 32-bit integer (2,147,483,647). 💀
4.6.5. Positive Integer 🌈
The value space of positive integer is the infinite set {1,2,...} as defined in Section 3.3.25 of [XMLSchema:Part2] 👑
Implementation Note: It is RECOMMENDED that implementations at least support a maximum value of a 32-bit integer (2,147,483,647). 😭
4.6.6. String 🌸
A string in the character encoding associated with the XML element, as defined in Section 3.2.1 of [XMLSchema:Part2] 🧚
4.6.7. Time Designation ⏰
A time designation is 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" ✨
4.6.8. Percentage 💅
A percentage is a positive integer followed by "%" 💖
Examples include: "100%", "500%", and "10%" 🎀
4.6.9. URI 🌐
Uniform Resource Indicator, as defined in [RFC3986] 🫶
4.6.10. MIME Media Type 🎶
A string formatted as an IANA MIME media type [MIME.mediatypes]. The ABNF [RFC5234] production for the string is:
type = type-name "/" subtype-name *(";" parameter)
parameter = parameter-name "=" valueWhere "type-name" and "subtype-name" are defined in Section 4.2 of [RFC4288], "parameter-name" is defined in Section 4.3 of [RFC4288], and "value" is defined in Section 5.1 of [RFC2045] 🔥
4.6.11. Language Identifier 🌍
A language identifier labels information content as being of a particular human language variant. Following the XML specification for language identification [XML], a legal language identifier is identified by a [RFC5646] code and matched according to [RFC4647] 💜
4.6.12. DateTime 📅
A string formatted according to the XML schema definition of a dateTime type [XMLSchema:Part2] 🦋
5. Formal Syntax 🧾
This section defines the XML schema for the IVR Control Package. The schema is normative 💖
The schema defines datatypes, attributes, dialog management, and IVR dialog elements in the urn:ietf:params:xml:ns:msc-ivr namespace. In most elements the order of child elements is significant. The schema is extensible: elements allow attributes and child elements from other namespaces. Elements from outside this package's namespace can occur after elements defined in this package ✨
The schema is dependent upon the schema (framework.xsd) defined in Appendix A.1 of the Control Framework [RFC6230]. It is also dependent upon the W3C (xml.xsd) schema for definitions of XML attributes (e.g., xml:base) 🎀
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="urn:ietf:params:xml:ns:msc-ivr"
elementFormDefault="qualified" blockDefault="#all"
xmlns="urn:ietf:params:xml:ns:msc-ivr"
xmlns:fw="urn:ietf:params:xml:ns:control:framework-attributes"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:annotation>
<xsd:documentation>
IETF MediaCtrl IVR 1.0 (20110104)
This is the schema of the IETF MediaCtrl IVR Control
Package.
The schema namespace is urn:ietf:params:xml:ns:msc-ivr
</xsd:documentation>
</xsd:annotation>
<!--
#############################################################
SCHEMA IMPORTS
#############################################################
-->
<xsd:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd">
<xsd:annotation>
<xsd:documentation>
This import brings in the XML attributes for
xml:base, xml:lang, etc
See http://www.w3.org/2001/xml.xsd for latest version
</xsd:documentation>
</xsd:annotation>
</xsd:import>
<xsd:import
namespace="urn:ietf:params:xml:ns:control:framework-attributes"
schemaLocation="framework.xsd">
<xsd:annotation>
<xsd:documentation>
This import brings in the framework attributes for
conferenceid and connectionid.
</xsd:documentation>
</xsd:annotation>
</xsd:import>
<!--
#####################################################
Extensible core type
#####################################################
-->
<xsd:complexType name="Tcore">
<xsd:annotation>
<xsd:documentation>
This type is extended by other (non-mixed) component types to
allow attributes from other namespaces.
</xsd:documentation>
</xsd:annotation>
<xsd:sequence/>
<xsd:anyAttribute namespace="##other" processContents="lax" />
</xsd:complexType>
<!--
#####################################################
TOP LEVEL ELEMENT: mscivr
#####################################################
-->
<xsd:complexType name="mscivrType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:choice>
<xsd:element ref="dialogprepare" />
<xsd:element ref="dialogstart" />
<xsd:element ref="dialogterminate" />
<xsd:element ref="response" />
<xsd:element ref="event" />
<xsd:element ref="audit" />
<xsd:element ref="auditresponse" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:choice>
</xsd:sequence>
<xsd:attribute name="version" type="version.datatype"
use="required" />
<xsd:attribute name="desclang" type="xsd:language"
default="i-default" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="mscivr" type="mscivrType" />
<!--
#####################################################
DIALOG MANAGEMENT TYPES
#####################################################
-->
<!-- dialogprepare -->
<xsd:complexType name="dialogprepareType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="dialog" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="params" minOccurs="0"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="src" type="xsd:anyURI" />
<xsd:attribute name="type" type="mime.datatype"/>
<xsd:attribute name="maxage" type="xsd:nonNegativeInteger"/>
<xsd:attribute name="maxstale" type="xsd:nonNegativeInteger"/>
<xsd:attribute name="fetchtimeout"
type="timedesignation.datatype" default="30s" />
<xsd:attribute name="dialogid"
type="dialogid.datatype" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dialogprepare" type="dialogprepareType" />
<!-- dialogstart -->
<xsd:complexType name="dialogstartType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="dialog" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="subscribe" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="params" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="stream" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="src" type="xsd:anyURI" />
<xsd:attribute name="type" type="mime.datatype"/>
<xsd:attribute name="maxage" type="xsd:nonNegativeInteger"/>
<xsd:attribute name="maxstale" type="xsd:nonNegativeInteger"/>
<xsd:attribute name="fetchtimeout"
type="timedesignation.datatype" default="30s" />
<xsd:attribute name="dialogid"
type="dialogid.datatype" />
<xsd:attribute name="prepareddialogid"
type="dialogid.datatype" />
<xsd:attributeGroup ref="fw:framework-attributes" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dialogstart" type="dialogstartType" />
<!-- dialogterminate -->
<xsd:complexType name="dialogterminateType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="dialogid"
type="dialogid.datatype" use="required" />
<xsd:attribute name="immediate"
type="xsd:boolean" default="false" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dialogterminate" type="dialogterminateType" />
<!-- response -->Okay bestie, the response type comes first, then the event, dialogexit, and everything branching off from them 💅✨
<xsd:complexType name="responseType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="status" type="status.datatype"
use="required" />
<xsd:attribute name="reason" type="xsd:string" />
<xsd:attribute name="desclang" type="xsd:language"/>
<xsd:attribute name="dialogid"
type="dialogid.datatype" use="required" />
<xsd:attributeGroup ref="fw:framework-attributes" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="response" type="responseType" />
<!-- event -->
<xsd:complexType name="eventType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:choice>
<xsd:element ref="dialogexit" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="dtmfnotify" minOccurs="0"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:choice>
</xsd:sequence>
<xsd:attribute name="dialogid"
type="dialogid.datatype" use="required" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="event" type="eventType" />
<!-- dialogexit-->
<xsd:complexType name="dialogexitType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="promptinfo" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="controlinfo" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="collectinfo" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="recordinfo" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="params" minOccurs="0"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="status"
type="xsd:nonNegativeInteger" use="required" />
<xsd:attribute name="reason" type="xsd:string" />
<xsd:attribute name="desclang" type="xsd:language"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dialogexit" type="dialogexitType" />Next up is the DTMF notify bit, where the digits get their moment ☎️🎀
<!-- dtmfnotify-->
<xsd:complexType name="dtmfnotifyType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="matchmode"
type="matchmode.datatype" default="all" />
<xsd:attribute name="dtmf" type="dtmfstring.datatype"
use="required" />
<xsd:attribute name="timestamp" type="xsd:dateTime"
use="required" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dtmfnotify" type="dtmfnotifyType" />
<!-- promptinfo -->
<xsd:complexType name="promptinfoType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="duration"
type="xsd:nonNegativeInteger" />
<xsd:attribute name="termmode"
type="prompt_termmode.datatype" use="required" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="promptinfo" type="promptinfoType" />Now the control info and control match elements, which is where the matching vibes live 🦋
<!-- controlinfo -->
<xsd:complexType name="controlinfoType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="controlmatch" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="controlinfo" type="controlinfoType" />
<!-- controlmatch -->
<xsd:complexType name="controlmatchType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="dtmf"
type="dtmfstring.datatype" />
<xsd:attribute name="timestamp" type="xsd:dateTime" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="controlmatch" type="controlmatchType" />Collect info, record info, and media info come next, and they're giving organised 🌸
<!-- collectinfo -->
<xsd:complexType name="collectinfoType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="dtmf"
type="dtmfstring.datatype" />
<xsd:attribute name="termmode"
type="collect_termmode.datatype" use="required" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="collectinfo" type="collectinfoType" />
<!-- recordinfo -->
<xsd:complexType name="recordinfoType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="mediainfo" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="duration"
type="xsd:nonNegativeInteger" />
<xsd:attribute name="termmode"
type="record_termmode.datatype" use="required" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="recordinfo" type="recordinfoType" />
<!-- mediainfo -->
<xsd:complexType name="mediainfoType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="loc" type="xsd:anyURI"
use="required" />
<xsd:attribute name="type" type="mime.datatype"
use="required"/>
<xsd:attribute name="size"
type="xsd:nonNegativeInteger" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="mediainfo" type="mediainfoType" />Subscribe, dtmfsub, and params are up next, and they're serving structure 💜
<!-- subscribe -->
<xsd:complexType name="subscribeType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="dtmfsub" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="subscribe" type="subscribeType" />
<!-- dtmfsub -->
<xsd:complexType name="dtmfsubType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="matchmode"
type="matchmode.datatype" default="all" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dtmfsub" type="dtmfsubType" />
<!-- params -->
<xsd:complexType name="paramsType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="param" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="params" type="paramsType" />The param element is the mixed-content one, so it gets its own special spot ✨
<!-- param -->
<!-- doesn't extend tCore since its content model is mixed -->
<xsd:complexType name="paramType" mixed="true">
<xsd:sequence/>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="type" type="mime.datatype" default="text/plain"/>
<xsd:attribute name="encoding" type="xsd:string"/>
<xsd:anyAttribute namespace="##other" processContents="lax" />
</xsd:complexType>
<xsd:element name="param" type="paramType" />Stream, region, and priority are next, and they're a whole mood 🌈
<!-- stream -->
<xsd:complexType name="streamType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="region" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="priority" minOccurs="0"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<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:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="stream" type="streamType" />
<!-- region -->
<xsd:simpleType name="regionType">
<xsd:restriction base="xsd:NMTOKEN"/>
</xsd:simpleType>
<xsd:element name="region" type="regionType" />
<!-- priority -->
<xsd:simpleType name="priorityType">
<xsd:restriction base="xsd:positiveInteger" />
</xsd:simpleType>
<xsd:element name="priority" type="priorityType" />Dialog, prompt, media, and variable are the last stops on this part's tour 🎀
<!-- dialog -->
<xsd:complexType name="dialogType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="prompt" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="control" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="collect" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="record" minOccurs="0"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="repeatCount"
type="xsd:nonNegativeInteger" default="1" />
<xsd:attribute name="repeatDur"
type="timedesignation.datatype" />
<xsd:attribute name="repeatUntilComplete"
type="xsd:boolean" default="false"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dialog" type="dialogType" />
<!-- prompt -->
<xsd:complexType name="promptType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:choice minOccurs="1" maxOccurs="unbounded">
<xsd:element ref="media" />
<xsd:element ref="variable" />
<xsd:element ref="dtmf" />
<xsd:element ref="par" />
<xsd:any namespace="##other"
processContents="lax" />
</xsd:choice>
<xsd:attribute ref="xml:base" />
<xsd:attribute name="bargein" type="xsd:boolean"
default="true" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="prompt" type="promptType" />
<!-- media -->
<xsd:complexType name="mediaType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="loc" type="xsd:anyURI"
use="required" />
<xsd:attribute name="type" type="mime.datatype" />
<xsd:attribute name="fetchtimeout"
type="timedesignation.datatype" default="30s" />
<xsd:attribute name="soundLevel"
type="percentage.datatype" default="100%" />
<xsd:attribute name="clipBegin"
type="timedesignation.datatype" default="0s" />
<xsd:attribute name="clipEnd"
type="timedesignation.datatype"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="media" type="mediaType" />
<!-- variable -->
<xsd:complexType name="variableT">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="value" type="xsd:string"
use="required" />
<xsd:attribute name="type" type="xsd:string"
use="required" />
<xsd:attribute name="format" type="xsd:string" />
<xsd:attribute name="gender" type="gender.datatype" />
<xsd:attribute ref="xml:lang" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>Okay so the variable element is up next, and this schema is about to get juicy 💅✨
<xsd:element name="variable" type="variableT" />
<!-- dtmf -->
<xsd:complexType name="dtmfType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="digits"
type="dtmfstring.datatype" use="required" />
<xsd:attribute name="level" type="xsd:integer"
default="-6" />
<xsd:attribute name="duration"
type="timedesignation.datatype" default="100ms" />
<xsd:attribute name="interval"
type="timedesignation.datatype" default="100ms" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dtmf" type="dtmfType" />
<!-- par -->
<xsd:complexType name="parType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:choice minOccurs="1" maxOccurs="unbounded">
<xsd:element ref="media" />
<xsd:element ref="variable" />
<xsd:element ref="dtmf" />
<xsd:element ref="seq" />
<xsd:any namespace="##other"
processContents="lax" />
</xsd:choice>
<xsd:attribute name="endsync" type="endsync.datatype"
default="last"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="par" type="parType" />
<!-- seq -->
<xsd:complexType name="seqType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:choice minOccurs="1" maxOccurs="unbounded">
<xsd:element ref="media" />
<xsd:element ref="variable" />
<xsd:element ref="dtmf" />
<xsd:any namespace="##other"
processContents="lax" />
</xsd:choice>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="seq" type="seqType" />
<!-- control -->
<xsd:complexType name="controlType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="skipinterval"
type="timedesignation.datatype" default="6s" />
<xsd:attribute name="ffkey" type="dtmfchar.datatype" />
<xsd:attribute name="rwkey" type="dtmfchar.datatype" />
<xsd:attribute name="pauseinterval"
type="timedesignation.datatype" default="10s" />
<xsd:attribute name="pausekey"
type="dtmfchar.datatype" />
<xsd:attribute name="resumekey"
type="dtmfchar.datatype" />
<xsd:attribute name="volumeinterval"
type="percentage.datatype" default="10%" />
<xsd:attribute name="volupkey"
type="dtmfchar.datatype" />
<xsd:attribute name="voldnkey"
type="dtmfchar.datatype" />
<xsd:attribute name="speedinterval"
type="percentage.datatype" default="10%" />
<xsd:attribute name="speedupkey"
type="dtmfchar.datatype" />
<xsd:attribute name="speeddnkey"
type="dtmfchar.datatype" />
<xsd:attribute name="gotostartkey"
type="dtmfchar.datatype" />
<xsd:attribute name="gotoendkey"
type="dtmfchar.datatype" />
<xsd:attribute name="external"
type="dtmfstring.datatype" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="control" type="controlType" />
<!-- collect -->
<xsd:complexType name="collectType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="grammar" minOccurs="0"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="cleardigitbuffer"
type="xsd:boolean" default="true" />
<xsd:attribute name="timeout"
type="timedesignation.datatype" default="5s" />
<xsd:attribute name="interdigittimeout"
type="timedesignation.datatype" default="2s" />
<xsd:attribute name="termtimeout"
type="timedesignation.datatype" default="0s" />
<xsd:attribute name="escapekey"
type="dtmfchar.datatype" />
<xsd:attribute name="termchar"
type="dtmfchar.datatype" default="#" />
<xsd:attribute name="maxdigits"
type="xsd:positiveInteger" default="5" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="collect" type="collectType" />
<!-- grammar -->
<!-- doesn't extend tCore since its content model is mixed -->
<xsd:complexType name="grammarType" mixed="true">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="src" type="xsd:anyURI" />
<xsd:attribute name="type" type="mime.datatype" />
<xsd:attribute name="fetchtimeout"
type="timedesignation.datatype" default="30s" />
<xsd:anyAttribute namespace="##other" processContents="lax" />
</xsd:complexType>
<xsd:element name="grammar" type="grammarType" />
<!-- record -->
<xsd:complexType name="recordType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="media" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="timeout"
type="timedesignation.datatype" default="5s" />
<xsd:attribute name="beep" type="xsd:boolean"
default="false" />
<xsd:attribute name="vadinitial"
type="xsd:boolean" default="false" />
<xsd:attribute name="vadfinal"
type="xsd:boolean" default="false" />
<xsd:attribute name="dtmfterm"
type="xsd:boolean" default="true" />
<xsd:attribute name="maxtime"
type="timedesignation.datatype" default="15s" />
<xsd:attribute name="finalsilence"
type="timedesignation.datatype" default="5s" />
<xsd:attribute name="append" type="xsd:boolean"
default="false" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="record" type="recordType" />
<!--
#####################################################
AUDIT TYPES
#####################################################
-->
<!-- audit -->
<xsd:complexType name="auditType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="capabilities"
type="xsd:boolean" default="true" />
<xsd:attribute name="dialogs"
type="xsd:boolean" default="true" />
<xsd:attribute name="dialogid"
type="dialogid.datatype"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="audit" type="auditType" />
<!-- auditresponse -->
<xsd:complexType name="auditresponseType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="capabilities" minOccurs="0"
maxOccurs="1" />
<xsd:element ref="dialogs" minOccurs="0"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="status" type="status.datatype"
use="required" />
<xsd:attribute name="reason" type="xsd:string" />
<xsd:attribute name="desclang" type="xsd:language"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="auditresponse" type="auditresponseType" />
<!-- codec -->
<xsd:complexType name="codecType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="subtype" minOccurs="1"
maxOccurs="1" />
<xsd:element ref="params" minOccurs="0"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string"
use="required" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="codec" type="codecType" />
<!-- subtype -->
<xsd:simpleType name="subtypeType">
<xsd:restriction base="xsd:string" />
</xsd:simpleType>
<xsd:element name="subtype" type="subtypeType" />
<!-- codecs -->
<xsd:complexType name="codecsType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="codec" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="codecs" type="codecsType" />
<!-- capabilities -->
<xsd:complexType name="capabilitiesType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="dialoglanguages" minOccurs="1"
maxOccurs="1" />
<xsd:element ref="grammartypes" minOccurs="1"
maxOccurs="1" />
<xsd:element ref="recordtypes" minOccurs="1"
maxOccurs="1" />
<xsd:element ref="prompttypes" minOccurs="1"
maxOccurs="1" />
<xsd:element ref="variables" minOccurs="1"
maxOccurs="1" />
<xsd:element ref="maxpreparedduration" minOccurs="1"
maxOccurs="1" />
<xsd:element ref="maxrecordduration" minOccurs="1"
maxOccurs="1" />
<xsd:element ref="codecs" minOccurs="1"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="capabilities" type="capabilitiesType" />
<!-- mimetype -->
<xsd:element name="mimetype" type="mime.datatype" />
<!-- dialoglanguages -->
<xsd:complexType name="dialoglanguagesType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="mimetype" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dialoglanguages" type="dialoglanguagesType" />
<!-- grammartypes -->
<xsd:complexType name="grammartypesType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="mimetype" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="grammartypes" type="grammartypesType" />
<!-- recordtypes -->
<xsd:complexType name="recordtypesType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="mimetype" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="recordtypes" type="recordtypesType" />
<!-- prompttypes -->
<xsd:complexType name="prompttypesType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="mimetype" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="prompttypes" type="prompttypesType" /><!-- variables -->
<xsd:complexType name="variablesType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="variabletype" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="variables" type="variablesType" />
<xsd:complexType name="variabletypeType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="format" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="type" type="xsd:string" use="required" />
<xsd:attribute name="desc" type="xsd:string"/>
<xsd:attribute name="desclang" type="xsd:language"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="variabletype" type="variabletypeType" />
<!-- format -->
<!-- doesn't extend tCore since its content model is mixed -->
<xsd:complexType name="formatType" mixed="true">
<xsd:sequence>
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="desc" type="xsd:string" />
<xsd:attribute name="desclang" type="xsd:language"/>
<xsd:anyAttribute namespace="##other" processContents="lax" />
</xsd:complexType>
<xsd:element name="format" type="formatType" />
<!-- maxpreparedduration -->
<xsd:element name="maxpreparedduration"
type="timedesignation.datatype"/>
<!-- maxrecordduration -->
<xsd:element name="maxrecordduration"
type="timedesignation.datatype"/>
<!-- dialogs -->
<xsd:complexType name="dialogsType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="dialogaudit" minOccurs="0"
maxOccurs="unbounded" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dialogs" type="dialogsType" />
<!-- dialogaudit -->
<xsd:complexType name="dialogauditType">
<xsd:complexContent>
<xsd:extension base="Tcore">
<xsd:sequence>
<xsd:element ref="codecs" minOccurs="0"
maxOccurs="1" />
<xsd:any namespace="##other" minOccurs="0"
maxOccurs="unbounded" processContents="lax" />
</xsd:sequence>
<xsd:attribute name="dialogid"
type="dialogid.datatype" use="required" />
<xsd:attribute name="state" type="state.datatype"
use="required" />
<xsd:attributeGroup ref="fw:framework-attributes" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="dialogaudit" type="dialogauditType" />
<!--
####################################################
DATATYPES
####################################################
-->
<xsd:simpleType name="version.datatype">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="1.0" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="mime.datatype">
<xsd:restriction base="xsd:string" />
</xsd:simpleType>
<xsd:simpleType name="dialogid.datatype">
<xsd:restriction base="xsd:string" />
</xsd:simpleType>
<xsd:simpleType name="gender.datatype">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="female" />
<xsd:enumeration value="male" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="state.datatype">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="preparing" />
<xsd:enumeration value="prepared" />
<xsd:enumeration value="starting" />
<xsd:enumeration value="started" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="status.datatype">
<xsd:restriction base="xsd:positiveInteger">
<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:enumeration value="inactive" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="timedesignation.datatype">
<xsd:annotation>
<xsd:documentation>
Time designation following Time in CSS2
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:pattern value="(\+)?([0-9]*\.)?[0-9]+(ms|s)" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="dtmfchar.datatype">
<xsd:annotation>
<xsd:documentation>
DTMF character [0-9#*A-D]
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:pattern value="[0-9#*A-D]" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="dtmfstring.datatype">
<xsd:annotation>
<xsd:documentation>
DTMF sequence [0-9#*A-D]
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:pattern value="([0-9#*A-D])+" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="percentage.datatype">
<xsd:annotation>
<xsd:documentation>
whole integer followed by '%'
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:pattern value="([0-9])+%" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="prompt_termmode.datatype">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="completed" />
<xsd:enumeration value="bargein" />
<xsd:enumeration value="stopped" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="collect_termmode.datatype">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="match" />
<xsd:enumeration value="noinput" />
<xsd:enumeration value="nomatch" />
<xsd:enumeration value="stopped" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="record_termmode.datatype">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="noinput" />
<xsd:enumeration value="dtmf" />
<xsd:enumeration value="maxtime" />
<xsd:enumeration value="finalsilence" />
<xsd:enumeration value="stopped" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="matchmode.datatype">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="all" />
<xsd:enumeration value="collect" />
<xsd:enumeration value="control" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="endsync.datatype">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="first" />
<xsd:enumeration value="last" />
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>6. Examples ✨
okay bestie, this section is all about examples of the IVR Control Package 🎀 let's see it in action 💅
6.1. AS-MS Dialog Interaction Examples 🦋
so these examples assume you already have a Control Channel set up and synced, just like the Media Control Channel Framework [RFC6230] describes 🫶
XML messages show up in angled brackets (the root <mscivr> is left out), and the REPORT status is in round brackets. we skip the other parts of the protocol so it's easier to read 💖
6.1.1. Starting an IVR Dialog 🌸
here the IVR dialog starts up no problem 🙌 and when it wraps up normally, the MS sends the AS a dialogexit notification <event> 🎉
Application Server (AS) Media Server (MS)
| |
| (1) CONTROL: <dialogstart> |
| ----------------------------------------> |
| |
| (2) 202 |
| <--------------------------------------- |
| |
| |
| (3) REPORT: <response status="200"/> |
| (terminate) |
| <---------------------------------------- |
| |
| (4) 200 |
| ----------------------------------------> |
| |
| (5) CONTROL: <event ... /> |
| |
| <---------------------------------------- |
| |
| (6) 200 |
| ----------------------------------------> |
| |6.1.2. IVR Dialog Fails to Start 💀
oof, this one flops 💀 the dialog never starts because the dialog language is unknown 🙈 the <response> gets reported inside a framework 200 message
Application Server (AS) Media Server (MS)
| |
| (1) CONTROL: <dialogstart> |
| ----------------------------------------> |
| |
| (2) 200: <response status="421"/> |
| <---------------------------------------- |
| |6.1.3. Preparing and Starting an IVR Dialog 🎀
okay so this one is the happy path, bestie 💖 An IVR dialog gets prepared AND started successfully, and then it exits normally. no drama, just vibes ✨
Application Server (AS) Media Server (MS)
| |
| (1) CONTROL: <dialogprepare> |
| ----------------------------------------> |
| |
| (2) 202 |
| <--------------------------------------- |
| |
| (3) REPORT: <response status="200"/> |
| (terminate) |
| <---------------------------------------- |
| |
| (4) 200 |
| ----------------------------------------> |
| |
| (5) CONTROL: <dialogstart> |
| ----------------------------------------> |
| |
| (6) 202 |
| <--------------------------------------- |
| |
| (7) REPORT: <response status="200"/> |
| (terminate) |
| <---------------------------------------- |
| |
| (8) 200 |
| ----------------------------------------> |
| |
| (9) CONTROL: <event .../> |
| <---------------------------------------- |
| |
| (10) 200 |
| ----------------------------------------> |
| |6.1.4. Terminating a Dialog 🦋
ngl this one is so iconic 😭 An IVR dialog gets started successfully, and then the AS is the one who terminates it. the dialogexit event is what gets sent back to the AS once the dialog exits, so the AS always knows when it's over 💅
Application Server (AS) Media Server (MS)
| |
| (1) CONTROL: <dialogstart> |
| ----------------------------------------> |
| |
| (2) 202 |
| <--------------------------------------- |
| |
| (3) REPORT: <response status="200"/> |
| (terminate) |
| <---------------------------------------- |
| |
| (4) 200 |
| ----------------------------------------> |
| |
| (5) CONTROL: <dialogterminate> |
| ----------------------------------------> |
| |
| (6) 200: <response status="200"/> |
| <---------------------------------------- |
| |
| (7) CONTROL: <event .../> |
| <---------------------------------------- |
| |
| (8) 200 |
| ----------------------------------------> |
| |👀 side note: in (6), the<response>payload that answers the<dialogterminate/>request rides along on a framework 200 response. the reason is that it could finish the requested operation before the transaction timeout hits, so it's kind of a speed thing 🏃♀️💨
6.2. IVR Dialog Examples 🧚
okay now the fun part 🎀 these examples show how <dialog> teams up with <dialogprepare>, <dialogstart>, and <event> to play prompts, set runtime controls, collect DTMF input, and record what the user says. it's giving full toolkit energy 💜
heads up though: the examples don't show every single message between the AS and MS. they're just the highlights, bestie 🙈
6.2.1. Playing Announcements 📣
this one prepares an announcement made of two prompts, and the dialog repeatCount is set to 2, so it plays the whole thing twice 🔁
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogprepare>
<dialog repeatCount="2">
<prompt>
<media loc="http://www.example.com/media/Number_09.wav"/>
<media loc="http://www.example.com/media/Number_11.wav"/>
</prompt>
</dialog>
</dialogprepare>
</mscivr>if the dialog gets prepared successfully, the MS sends back a <response> with status 200 and a dialog identifier that the MS assigned itself. so pretty 🌸
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<response status="200" dialogid="vxi78"/>
</mscivr>next up, the prepared dialog gets started on a conference, playing the prompts twice ✨
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart prepareddialogid="vxi78" conferenceid="conference11"/>
</mscivr>and when it goes well, the output shows up in an <event>. for example 💖
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<event dialogid="vxi78">
<dialogexit status="1">
<promptinfo termmode="completed" duration="24000"/>
</dialogexit>
</event>
</mscivr>6.2.2. Prompt and Collect 🎧
this is giving prompt-then-listen 😌 A prompt gets played, and then the MS waits for 30s for a two digit sequence.
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="7HDY839:HJKSkyHS~HUwkuh7ns">
<dialog>
<prompt>
<media loc="http://www.example.com/prompt1.wav"/>
</prompt>
<collect timeout="30s" maxdigits="2"/>
</dialog>
</dialogstart>
</mscivr>if nothing gets collected within 30s, the following notification event comes back 🥲
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<event dialogid="vxi81">
<dialogexit status="1" >
<promptinfo termmode="completed" duration="4000"/>
<collectinfo termmode="noinput"/>
</dialogexit>
</event>
</mscivr>the collect operation can also happen with no prompt at all 🙌 here the MS just sits there waiting for DTMF input from the user. the maxdigits attribute of <collect> defaults to 5, so you get five digits unless you say otherwise.
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="7HDY839:HJKSkyHS~HUwkuh7ns">
<dialog>
<collect/>
</dialog>
</dialogstart>
</mscivr>if the dialog is successful, the dialogexit <event> carries the DTMF it collected in its result parameter 🔢
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<event dialogid="vxi80">
<dialogexit status="1">
<collectinfo dtmf="12345" termmode="match"/>
</dialogexit>
</event>
</mscivr>and finally, here's one where an input parameter is invalid 💀 The repeatCount is set to two, which is not a valid value.
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="7HDY839:HJKSkyHS~HUwkuh7ns">
<dialog repeatCount="two">
<prompt>
<media loc="http://www.example.com/prompt1.wav"/>
</prompt>
<collect cleardigitbuffer="true"
timeout="4s" interdigittimeout="2s"
termtimeout="0s" maxdigits="2"/>
</dialog>
</dialogstart>
</mscivr>the error gets reported right back in the response 🚨
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<response status="400" dialogid="vxi82"
reason="repeatCount attribute value invalid: two"/>
</mscivr>6.2.3. Prompt and Record 🎙️
in this one, the user gets prompted, and then whatever they say is recorded for a maximum of 30 seconds. bestie, it's literally a voicemail moment 📞✨
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="7HDY839:HJKSkyHS~HUwkuh7ns">
<dialog>
<prompt>
<media loc="http://www.example.com/media/sayname.wav"/>
</prompt>
<record dtmfterm="false" maxtime="30s" beep="true"/>
</dialog>
</dialogstart>
</mscivr>if it's successful and the recording gets ended by DTMF, this is what comes back in a dialogexit <event> 🥹
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<event dialogid="vxi83">
<dialogexit status="1">
<recordinfo termmode="dtmf">
<mediainfo type="audio/x-wav"
loc="http://www.example.com/recording1.wav"/>
</recordinfo>
</dialogexit>
</event>
</mscivr>6.2.4. Runtime Controls 🎛️
this example plays a prompt with the collect operation AND runtime controls turned on. it's giving multitasking 🤹♀️
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="7HDY839:HJKSkyHS~HUwkuh7ns">
<dialog>
<prompt bargein="true">
<media loc="http://www.example.com/prompt1.wav"/>
</prompt>
<control ffkey="5" rwkey="6" speedupkey="3"
speeddnkey="4"/>
<collect maxdigits="2"/>
</dialog>
</dialogstart>
</mscivr>once the dialog is active, the user can press keys 3, 4, 5, and 6 to run runtime controls on the prompt queue 🎶 those keys don't cause bargein to happen. if the user presses any other key, the prompt gets interrupted and DTMF collect begins. also, runtime controls are NOT active during the collect operation, so don't expect them to work then 🙅♀️
when the dialog finishes successfully, both the control and the collect information get reported 📝
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<event dialogid="vxi81">
<dialogexit status="1">
<promptinfo termmode="bargein"/>
<controlinfo>
<controlmatch dtmf="4" timestamp="2008-05-12T12:13:14Z"/>
<controlmatch dtmf="3" timestamp="2008-05-12T12:13:15Z"/>
<controlmatch dtmf="5" timestamp="2008-05-12T12:13:16Z"/>
</controlinfo>
<collectinfo termmode="match" dtmf="14"/>
</dialogexit>
</event>
</mscivr>6.2.5. Subscriptions and Notifications 🔔
in this example, a looped dialog starts with a subscription, so you get a notification every time the user input matches the collect grammar. main character energy 👑
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="7HDY839:HJKSkyHS">
<dialog repeatCount="0">
<collect maxdigits="2"/>
</dialog>
<subscribe>
<dtmfsub matchmode="collect"/>
</subscribe>
</dialogstart>
</mscivr>each time the user enters DTMF that matches the grammar, this notification event gets sent 💌
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<event dialogid="vxi81">
<dtmfnotify matchmode="collect" dtmf="12"
timestamp="2008-05-12T12:13:14Z"/>
</event>
</mscivr>and if there's no user input at all, or the input doesn't match the grammar, the dialog just keeps looping until it gets terminated (or an error happens) 🔁🌈
6.2.6. Dialog Repetition until DTMF Collection Complete ✨
okay bestie, this one is a prompt and collect dialog that grabs the PIN from the user 🔐 the key move is repeatUntilComplete="true" on the <dialog>. Once the grammar collection is complete, the MS automatically stops the repeat cycle and reports back in a <dialogexit> event 💅
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="7HDY839:HJKSkyHS">
<dialog repeatCount="3" repeatUntilComplete="true">
<prompt bargein="true">
<media loc="http://example.com/please_enter_your_pin.vox"/>
</prompt>
<collect maxdigits="4"/>
</dialog>
</dialogstart>
</mscivr>if the user barges in on the prompt and <collect> gets DTMF input that matches the grammar, the dialog cycle is considered complete and the MS sends back this 🎀✨
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<event dialogid="vxi81">
<dialogexit status="1">
<promptinfo duration="3654" termmode="bargein"/>
<collectinfo dtmf="1234" termmode="match"/>
</dialogexit>
</event>
</mscivr>but if there's no input at all, or the input doesn't match the grammar, the dialog loops again, for a max of 3 times 🔁 not me being persistent on your behalf 🙈
6.3. Other Dialog Languages 🌈
this example asks for a VoiceXML dialog to be started 🎧
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart dialogid="d2"
connectionid="7HDY839:HJKSkyHS"
type="application/voicexml+xml"
src="http://www.example.com/mydialog.vxml"
fetchtimeout="15s">
<params>
<param name="prompt1">nfs://nas01/media1.3gp</param>
<param name="prompt2">nfs://nas01/media2.3gp</param>
</params>
</dialogstart>
</mscivr>if the MS doesn't support this dialog language, the response comes back with status code 421 (Section 4.5), which is a whole vibe check 💀 but if it does support VoiceXML, it replies with a 200, activates the VoiceXML dialog, and makes the <params> available to the VoiceXML script, as described in Section 9 💜
when the VoiceXML dialog exits, the exit namelist parameters get passed back using <params> inside the <dialogexit> event 🍓
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<event dialogid="d2">
<dialogexit status="1">
<params>
<param name="username">peter</param>
<param name="pin">1234</param>
</params>
</dialogexit>
</event>
</mscivr>6.4. Foreign Namespace Attributes and Elements 🧚
an MS can support attributes and elements from foreign namespaces inside the <mscivr> element, which is giving extensibility 🦋 for example, the MS could support a <listen> element (in a foreign namespace) for speech recognition, kind of like how <collect> handles DTMF collection 🎤
here's a prompt and collect request that gets extended with a <listen> element 👑
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr"
xmlns:ex="http://www.example.com/mediactrl/extensions/1">
<dialogstart connectionid="7HDY839:HJKSkyHS~HUwkuh7ns">
<dialog>
<prompt>
<media loc="http://www.example.com/prompt1.wav"/>
</prompt>
<collect timeout="30s" maxdigits="4"/>
<ex:listen maxtimeout="30s" >
<ex:grammar src="http://example.org/pin.grxml"/>
</ex:listen>
</dialog>
</dialogstart>
</mscivr>so in the <mscivr> root element, the xmlns:ex attribute declares that "ex" is tied to the foreign namespace URI "http://www.example.com/mediactrl/extensions/1" 💖 the <ex:listen> element, its attributes, and its child elements all belong to that namespace. This <listen> could be defined so it activates an SRGS grammar and listens for user input that matches it, working in a similar way to DTMF collection 🌸
if an MS gets this request but doesn't support the <listen> element, it sends back a 431 response 😭
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<response status="431" dialogid="d560"
reason="unsupported foreign listen element"/>
</mscivr>but if the MS does support this foreign element, it sends a 200 response and starts the dialog with speech recognition 🔥 when the dialog exits, it gives info about the <listen> execution inside <dialogexit>, again using elements from a foreign namespace, like the <listeninfo> below ⭐
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr"
xmlns:ex="http://www.example.com/mediactrl/extensions/1">
<event dialogid="d560">
<dialogexit status="1">
<ex:listeninfo speech="1 2 3 4" termmode="match"/>
</dialogexit>
</event>
</mscivr>quick aside: the AS replies with a Control Framework 200 response even though the notification event has an element in a foreign namespace that it might not understand 🫶 that's the kind of graceful handling I'm obsessed with, periodt 💅
7. Security Considerations 🔐✨
Bestie, this section is SERIOUS, so let's get into it 💅. Since this Control Package processes XML markup, implementations MUST address the security considerations of [RFC3023].
Implementations of this Control Package MUST also cover security, confidentiality, and integrity for messages sent over the Control Channel. Section 12 of "Media Control Channel Framework" [RFC6230] explains this in detail, including Transport Level Protection, Control Channel Policy Management, and Session Establishment 🧚. On top of that, implementations MUST address security, confidentiality, and integrity for User Agent sessions with the MS, covering both the SIP signaling and the associated RTP media flow. Check [RFC6230] for more on that 🦋. Last but not least, implementations MUST address security, confidentiality, and integrity for any sessions where an MS uploads recordings or retrieves documents and resources through a URI scheme. An example is fetching a grammar document from a web server over HTTPS 🔒.
Transport protection and authentication are not optional, especially when the implementation is deployed on open networks 💀. If the implementation doesn't handle these correctly, it opens the door to malicious attacks, including (but not limited to) the following:
- Denial of Service 🙅♀️: An attacker could slide a request message into the transport stream that immediately terminates specific dialogs on the MS. For example,
<dialogterminate dialogid="XXXX" immediate="true">, where the value of "XXXX" could be guessed or found by auditing the active dialogs on the MS with an<audit>request. An attacker could also impersonate the MS and insert error responses into the transport stream, which would block the AS from accessing package capabilities. - Resource Exhaustion 🫠: An attacker could insert brand-new request messages into the Control Channel (or change existing ones). For instance, they could send
<dialogprepare>elements with a very long fetchtimeout attribute and a bogus source URL. Eventually this drains the number of connections the MS is able to make. - Phishing 🎣: An attacker with access to the Control Channel could change the "loc" attribute of a
<media>element in a dialog so it points to a different audio file. That file could contain different information from the original, like another phone number for people to call for more info or to hand over additional details (such as governmental, corporate, or financial information). - Data Theft 😱: An attacker could modify a
<record>element in the Control Channel to add a new recording location:
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart>
<dialog>
<record>
<media type="audio/x-wav" loc="(Good URI)"/>
<media type="audio/x-wav" loc="(Attacker's URI)"/>
</record>
</dialog>
</dialogstart>
</mscivr>The recorded data would then be uploaded to two places: the "{Good URI}" and the "{Attacker's URI}". That means the attacker can steal the recorded audio, which could include sensitive or confidential info, and the person who made the request might never notice 👀.
The Media Control Channel Framework lets security policy be managed further, including resource access and Control Channel usage. This can be defined at the Control Package level, on top of what the Framework already specifies (see Section 12.3 of [RFC6230]) 🎀.
Creating IVR dialogs ties into media processing resources on the MS, like DTMF detectors, media playback, and recording. So this Control Package's security policy needs to spell out how those dialogs are managed securely across more than one Control Channel 🧠. That policy is only useful on channels that are secure, confidential, and integrity-protected. A Control Channel's identity is set by its channel identifier, which is the value of the cfw-id attribute in the SDP and the 'Dialog-ID' header in the channel protocol (see [RFC6230]). Channels with the same identifier are the same; otherwise, they're different. This Control Package adds these extra security policies:
- Responses: The MS MUST only send a response to a dialog management or audit request on the same Control Channel that was used to send the request 📬.
- Notifications: The MS MUST only send notification events for a dialog on the same Control Channel that received the request that created the dialog 🔔.
- Auditing: The MS MUST only provide audit information about dialogs created on the same Control Channel that the
<audit>request was sent on 🔍. - Rejection: The MS SHOULD reject requests to audit or change an existing dialog if the channel isn't the same one that created the dialog. The MS rejects a request by sending a Control Framework 403 response (see Section 7.4 and Section 12.3 of [RFC6230]). For example, if channel 'cfw1234' was used to create a dialog, and the MS gets a request to audit or terminate that dialog on channel 'cfw98969', the MS sends a 403 framework response 🚫.
There can be legit reasons an implementation doesn't reject an audit or dialog manipulation request coming from a different channel than the one that created the dialog 🤓. For example, a system administrator might want a separate channel to audit dialog resources created by system users, and to terminate dialogs that are eating up excessive system resources. Or a system monitor or resource broker might want a separate channel to audit the dialogs this package manages on an MS. Still, the implementation has to fully understand the consequences and weigh them carefully before accepting these reasons as valid. If the reasons don't hold up in their particular situation, the MS rejects those requests ⚖️.
There can also be legit reasons for 'channel handover', such as high availability support, or when one AS needs to take over managing dialogs after the AS that created them has failed 🦸♀️. This could work by having Control Channels reuse the same channel identifier, one after another. For example, say a channel is created with the identifier 'cfw1234' and used to create dialogs on the MS. Then that channel (and its associated SIP dialog) ends because the AS failed. As the Control Framework allows, the identifier 'cfw1234' could be reused for a new channel, so it can 'take over' managing the dialogs on the MS. Once again, the implementation needs to understand the full consequences and weigh them carefully before accepting these reasons as valid. If the reasons don't fit their particular circumstances, the MS uses the appropriate SIP mechanisms to block session establishment when the same channel identifier gets used to set up another Control Channel (see Section 4 of [RFC6230]) 🛑.
8. IANA Considerations 🌸
IANA has registered a new Media Control Channel Framework Package, a new XML namespace, a new XML schema, and a new MIME type 🎉.
IANA has also created a new registry for IVR prompt variable types 🗂️.
8.1. Control Package Registration
This section registers a new Media Control Channel Framework package, following the instructions in Section 13.1 of [RFC6230] 📦.
Package Name: msc-ivr/1.0
Published Specification(s): RFC 6231
Person & email address to contact for further information:
IETF MEDIACTRL working group (mediactrl@ietf.org),
Scott McGlashan (smcg.stds01@mcglashan.org).8.2. URN Sub-Namespace Registration
This section registers a new XML namespace, "urn:ietf:params:xml:ns:msc-ivr", following the guidelines in RFC 3688 [RFC3688] 🪪.
URI: urn:ietf:params:xml:ns:msc-ivr
Registrant Contact: IETF MEDIACTRL working group (mediactrl@ietf.org),
Scott McGlashan (smcg.stds01@mcglashan.org).
XML:
BEGIN
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Media Control Channel Framework IVR
Package attributes</title>
</head>
<body>
<h1>Namespace for Media Control Channel
Framework IVR Package attributes</h1>
<h2>urn:ietf:params:xml:ns:msc-ivr</h2>
<p>See <a href="http://www.rfc-editor.org/rfc/rfc6231.txt">
RFC 6231</a>.</p>
</body>
</html>
END8.3. XML Schema Registration
This section registers an XML schema following the guidelines in RFC 3688 [RFC3688] 📐.
URI: urn:ietf:params:xml:ns:msc-ivr
Registrant Contact: IETF MEDIACTRL working group (mediactrl@ietf.org),
Scott McGlashan (smcg.stds01@mcglashan.org).
Schema: The XML for this schema can be found in Section 5 of this
document.8.4. MIME Media Type Registration for application/msc-ivr+xml
This section registers the application/msc-ivr+xml MIME type 💌.
Type name: application
Subtype name: msc-ivr+xml
Required parameters: (none)
Optional parameters: charset
Indicates the character encoding of enclosed XML. Default is
UTF-8.
Encoding considerations: Uses XML, which can employ 8-bit
characters, depending on the character encoding used. See RFC
3023 [RFC3023], Section 3.2.
Security considerations: No known security considerations outside
of those provided by the Media Control Channel Framework IVR
Package.
Interoperability considerations: This content type provides
constructs for the Media Control Channel Framework IVR package.
Published specification: RFC 6231
Applications that use this media type: Implementations of
the Media Control Channel Framework IVR package.
Additional information:
Magic number(s): (none)
File extension(s): (none)
Macintosh file type code(s): (none)
Person & email address to contact for further information:
Scott McGlashan <smcg.stds01@mcglashan.org>
Intended usage: LIMITED USE
Author/Change controller: The IETF
Other information: None.8.5. IVR Prompt Variable Type Registration Information 💅
Okay bestie, this part sets up an IVR Prompt Variable Type registry for Control Packages and fills it with its first entries 🦋 New entries have to be published in an RFC (either an IETF submission or an RFC Editor submission), and the IANA policy is [RFC5226] "RFC Required" ✨
Variable Type Control Package Reference
------------- --------------- ---------
date msc-ivr/1.0 [RFC6231]
time msc-ivr/1.0 [RFC6231]
digits msc-ivr/1.0 [RFC6231]The following information MUST be provided in an RFC in order to register a new prompt variable type 🎀
- Variable Type: The value for the
<variable>type attribute (Section 4.3.1.1.1). The RFC MUST specify permitted values (if any) for the format attribute of<variable>and how the value attribute is rendered for different values of the format attribute. The RFC MUST NOT weaken but MAY strengthen the valid values of<variable>attributes defined in Section 4.3.1.1.1 of this specification. 💖 - Reference: The RFC number in which the variable type is registered. 🌸
- Control Package: The Control Package associated with the IVR variable type. 🧚
- Person & address to contact for further information: 🫶
9. Using VoiceXML as a Dialog Language 🎀
So the IVR Control Package lets the MS support other dialog languages by pointing at an external dialog document, but it doesn't make that mandatory 🌈 This section gives MS implementations that support the VoiceXML dialog language ([VXML20], [VXML21], [VXML30]) extra details about using those dialogs in this package. It is normative for an MS that supports the VoiceXML dialog language, so it's not just a vibe, it's a rule 💅
This section covers preparing (Section 9.1), starting (Section 9.2), terminating (Section 9.3), and exiting (Section 9.4) VoiceXML dialogs, as well as handling VoiceXML call transfer (Section 9.5) ✨
9.1. Preparing a VoiceXML Dialog 🦋
A VoiceXML dialog gets prepared by sending the MS a request containing a <dialogprepare> element (Section 4.2.1). The type attribute is set to "application/voicexml+xml" and the src attribute to the URI of the VoiceXML document the MS should prepare. Here's an example 💕
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogprepare type="application/voicexml+xml"
src="http://www.example.com/mydialog.vxml"
fetchtimeout="15s"/>
</mscivr>The VoiceXML dialog environment treats the <dialogprepare> request as its chance to fetch and validate the initial document indicated by the src attribute, along with any resources referenced in the VoiceXML document that are marked as prefetchable 👑 The maxage and maxstale attributes, if specified, control how the initial VoiceXML document is fetched using HTTP (see [RFC2616]). Heads up: the fetchtimeout attribute isn't defined in VoiceXML for an initial document, but the MS MUST support this attribute in its VoiceXML environment 🙈
If a <params> child element of <dialogprepare> is specified, then the MS MUST map the parameter information into a VoiceXML session variable object, as described in Section 9.2.3 🌸
The success or failure of the VoiceXML document preparation gets reported in the MS response. For example, if the VoiceXML document can't be retrieved, a 409 error response is returned. If the document is syntactically invalid according to VoiceXML, a 400 response is returned. If it works, the response includes a dialogid attribute, and the AS can use that value in a <dialogstart> element to start the prepared dialog 🎉
9.2. Starting a VoiceXML Dialog 🌸
A VoiceXML dialog gets started by sending the MS a request containing a <dialogstart> element (Section 4.2.2). If a VoiceXML dialog has already been prepared using <dialogprepare>, then the MS starts the dialog indicated by the prepareddialogid attribute. Otherwise, a brand new VoiceXML dialog can be started by setting the type attribute to "application/voicexml+xml" and the src attribute to the URI of the VoiceXML document. Example time 🧚
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="ssd3r3:sds345b"
type="application/voicexml+xml"
src="http://www.example.com/mydialog.vxml"
fetchtimeout="15s"/>
</mscivr>The maxage and maxstale attributes, if specified, control how the initial VoiceXML document is fetched using HTTP (see [RFC2616]). Again, the fetchtimeout attribute isn't defined in VoiceXML for an initial document, but the MS MUST support this attribute in its VoiceXML environment 💖 Also note that support for <dtmfsub> subscriptions (Section 4.2.2.1.1) and their associated dialog notification events is not defined in VoiceXML. If a subscription like that shows up in a <dialogstart> request, the MS sends a 439 error response (see Section 4.5) 💀
The success or failure of starting a VoiceXML dialog is reported in the MS response, as described in Section 4.2.2 ✨
When the MS starts a VoiceXML dialog, the MS MUST map session information into a VoiceXML session variable object. There are 3 types of session information: protocol information (Section 9.2.1), media stream information (Section 9.2.2), and parameter information (Section 9.2.3) 🫶
9.2.1. Session Protocol Information 🦋
If the connectionid attribute is specified, the MS assigns protocol information from the SIP dialog associated with the connection to the following session variables in VoiceXML 👑
session.connection.local.uri: Evaluates to the SIP URI specified in the 'To:' header of the initial INVITE.session.connection.remote.uri: Evaluates to the SIP URI specified in the 'From:' header of the initial INVITE.session.connection.originator: Evaluates to the value ofsession.connection.remote(MS receives inbound connections but does not create outbound connections).session.connection.protocol.name: Evaluates to "sip". Note that this is intended to reflect the use of SIP in general, and does not distinguish between whether the connection accesses the MS via SIP or SIP Secure (SIPS) procedures.session.connection.protocol.version: Evaluates to "2.0".session.connection.redirect: This array is populated by information contained in the 'History-Info' header [RFC4244] in the initial INVITE, or is otherwise undefined. Each entry (hi-entry) in the 'History-Info' header is mapped, in the order it appeared in the 'History-Info' header, into an element of thesession.connection.redirectarray. The properties of each element of the array are determined as follows 🌈uri: Set to the hi-targeted-to-uri value of the History-Info entrypi: Set to 'true' if hi-targeted-to-uri contains a 'Privacy=history' parameter, or if the INVITE 'Privacy' header includes 'history'; 'false' otherwisesi: Set to the value of the 'si' parameter if it exists; undefined otherwisereason: Set verbatim to the value of the 'Reason' parameter of hi-targeted-to-uri
session.connection.aai: Evaluates to the value of a SIP header with the name "aai" if present; undefined otherwise.session.connection.protocol.sip.requesturi: This is an associative array where the array keys and values are formed from the URI parameters on the SIP Request-URI of the initial INVITE. The array key is the URI parameter name. The corresponding array value is obtained by evaluating the URI parameter value as a string. In addition, the array's toString() function returns the full SIP Request-URI ⭐session.connection.protocol.sip.headers: This is an associative array where each key in the array is the non-compact name of a SIP header in the initial INVITE, converted to lowercase (note the case conversion does not apply to the header value). If multiple header fields of the same field name are present, the values are combined into a single comma-separated value. Implementations MUST at a minimum include the 'Call-ID' header and MAY include other headers. For example,session.connection.protocol.sip.headers["call-id"]evaluates to the Call-ID of the SIP dialog 🔥
If a conferenceid attribute is specified, then the MS populates the following session variables in VoiceXML 🌸
session.conference.name: Evaluates to the value of the conferenceid attribute.
9.2.2. Session Media Stream Information 🎀
The media streams of the connection or conference to use for the dialog are described in Section 4.2.2, including use of <stream> elements (Section 4.2.2.2) if specified. The MS maps media stream information into the VoiceXML session variable session.connection.protocol.sip.media for a connection, and session.conference.media for a conference. In both variables, the value of the variable is an array where each array element is an object with the following properties 💜
type: This required property indicates the type of the media associated with the stream (see Section 4.2.2.2<stream>type attribute definition).direction: This required property indicates the directionality of the media relative to the endpoint of the dialog (see Section 4.2.2.2<stream>direction attribute definition).format: This property is optional. If defined, the value of the property is an array. Each array element is an object that specifies information about one format of the media stream. The object contains at least one property called name, whose value is the subtype name of the media format [RFC4855]. Other properties may be defined with string values; these correspond to required and, if defined, optional parameters of the format.
As a consequence of this definition, when a connectionid is specified there is an array entry in session.connection.protocol.sip.media for each media stream used by the VoiceXML dialog. For an example, consider a connection with bidirectional G.711 mu-law audio sampled at 8kHz, where the dialog is started with 🦋
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="ssd3r3:sds345b"
type="application/voicexml+xml"
src="http://www.example.com/mydialog.vxml"
fetchtimeout="15s">
<stream media="audio" direction="recvonly"/>
</dialogstart>
</mscivr>In this case, session.connection.protocol.sip.media[0].type evaluates to "audio", session.connection.protocol.sip.media[0].direction evaluates to "recvonly" (i.e., the endpoint only receives media from the dialog -- the endpoint does not send media to the dialog), session.connection.protocol.sip.media[0].format[0].name evaluates to "PCMU", and session.connection.protocol.sip.media[0].format[0].rate evaluates to "8000" 🍓
Note that the session variable is updated if the connection or conference media session characteristics for the VoiceXML dialog change (e.g., due to a SIP re-INVITE) 🔥
9.2.3. Session Parameter Information ✨
okay so parameter info lives in the <params> child element of <dialogprepare> and <dialogstart>, and each parameter gets its own <param> element 💖 the MS then turns all that into VoiceXML session variables like this:
session.valuesis an associative array mapped to the<params>element. It is undefined if no<params>element is specified. If a<params>element is specified in both<dialogprepare>and<dialogstart>for the same dialog, the array is first initialized with the<params>from<dialogprepare>and then updated with the<params>from<dialogstart>. When there's a conflict, the<dialogstart>parameter value takes priority 🔥 Array keys and values are formed from the<param>children of the<params>element. Each key is the value of the name attribute of a<param>. If the same name shows up in more than one<param>, the key is linked to the last<param>in document order. The value for each key is an object with two required properties: a "type" property evaluating to the value of the type attribute, and a "content" property evaluating to the content of the<param>. On top of that, this object's toString() function returns the value of the "content" property as a string ✨
here's an example of a VoiceXML dialog started with one parameter, no cap it's super clear 🎀
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr">
<dialogstart connectionid="ssd3r3:sds345b"
type="application/voicexml+xml"
src="http://www.example.com/mydialog.vxml"
fetchtimeout="15s">
<params>
<param name="mode">playannouncement</param>
</params>
</dialogstart>
</mscivr>so in this case, session.values gets one item in the array. session.values['mode'].type evaluates to "text/plain" (the default value), session.values['mode'].content evaluates to "playannouncement", and session.values['mode'].toString() also evaluates to "playannouncement" 🦋
the MS sends an error response (see Section 4.2.2) if a <param> isn't supported by the MS, like if the parameter type isn't supported 💀
9.3. Terminating a VoiceXML Dialog 🌸
when the MS gets a request with a <dialogterminate> element (Section 4.2.3), the MS throws a 'connection.disconnect.hangup' event into the specified VoiceXML dialog. ngl this part is important: if the immediate attribute has the value true, then the MS MUST NOT return <params> information when the VoiceXML dialog exits, even if the dialog would normally provide it 🙈 see Section 9.4 for more 💅
if the connection or conference tied to the VoiceXML dialog terminates, the MS throws a 'connection.disconnect.hangup' event into the specified VoiceXML dialog too 🧚
9.4. Exiting a VoiceXML Dialog 🚪
the MS sends a <dialogexit> notification event (Section 4.2.5.1) when the VoiceXML dialog is complete, has been terminated, or exits because of an error 😭 the status attribute on <dialogexit> tells you the status of the dialog when it exits, and its <params> child element carries any info the dialog sent back 🎀
a VoiceXML dialog exits when it processes a <disconnect> element, an <exit> element, or an implicit exit according to the VoiceXML form interpretation algorithm (FIA). If the dialog runs a <disconnect> and then later runs an <exit> with namelist info, the namelist info from the <exit> gets thrown away 🗑️
the MS reports namelist variables in the <params> element of the <dialogexit>. Each <param> reports on one namelist variable. The MS sets the <param> name attribute to the name of the VoiceXML variable, and sets the <param> type attribute according to the type of that variable. The type is 'text/plain' when the VoiceXML variable is a simple ECMAScript value. If the VoiceXML variable is a recording, the MS sets the <param> type to the MIME media type of the recording and encodes the recorded content as CDATA in the <param> (see Section 4.2.6.1 for an example) 🎙️ If the VoiceXML variable is a complex ECMAScript value (like an object, array, etc.), the MS sets the <param> type to 'application/json' and converts the variable value to its JSON value equivalent [RFC4627]. What happens when you specify an ECMAScript object with circular references is not defined, so that's a no-go zone 🙅♀️
if the expr attribute is specified on the VoiceXML <exit> element instead of the namelist attribute, the MS creates a <param> element with the reserved name '__exit'. If the value is an ECMAScript literal, the <param> type is 'text/plain' and the content is the literal value. If the value is a variable, the <param> type and content are set the same way as a namelist variable. For example, an expr attribute referencing a variable with a simple ECMAScript value has the type 'text/plain', and the content is set to that ECMAScript value 🍓
here's the part that's lowkey genius: so the AS can tell apart a <dialogexit> coming from a VoiceXML <disconnect> and one coming from an <exit>, the MS creates a <param> with the reserved name '__reason' and the type 'text/plain'. Its value is "disconnect" (without brackets) when VoiceXML's <disconnect> element was used, and "exit" (without brackets) when there was an explicit <exit> in the VoiceXML dialog 🧠 if the VoiceXML session ends for other reasons (like hitting an error), this parameter MAY be omitted or take on platform-specific values prefixed with an underscore 🌈
Table 2 has some examples of VoiceXML <exit> usage and the matching <params> element in the <dialogexit> notification event. It assumes these VoiceXML variable names and values: userAuthorized=true, pin=1234, and errors=0. The <param> type attributes ('text/plain') are left out for clarity 👑
+------------------------+------------------------------------------+
| <exit> Usage | <params> Result |
+------------------------+------------------------------------------+
| <exit> | <params> <param |
| | name="__reason">exit</param> </params> |
| <exit expr="5"> | <params> <param |
| | name="__reason">exit</param> <param |
| | name="__exit">5</param> </params> |
| <exit expr="'done'"> | <params> <param |
| | name="__reason">exit</param> <param |
| | name="__exit">'done'</param> </params> |
| <exit | <params> <param |
| expr="userAuthorized"> | name="__reason">exit</param> <param |
| | name="__exit">true</param> </params> |
| <exit namelist="pin | <params> <param |
| errors"> | name="__reason">exit</param> <param |
| | name="pin">1234</param> <param |
| | name="errors">0</param> </params> |
+------------------------+------------------------------------------+
Table 2: VoiceXML <exit> Mapping Examples9.5. Call Transfer 📞
so VoiceXML is at its core a dialog language, but it also has an optional call transfer capability ✨ it is NOT RECOMMENDED to use VoiceXML's call transfer capability in networks that involve application servers, ngl that's a big vibe check 🚫 instead, the AS itself can handle call routing by taking signaling actions based on the data it gets back, either through VoiceXML's own data submission mechanisms or through the mechanism described in Section 9.4 💅 if the MS runs into a VoiceXML dialog asking for call transfer capability, the MS SHOULD raise an error event in the VoiceXML dialog execution context. That's error.unsupported.transfer.blind if blind transfer is requested, error.unsupported.transfer.bridge if bridge transfer is requested, or error.unsupported.transfer.consultation if consultation transfer is requested 🫶
10. Contributors 🌟
Asher Shiratzky provided valuable support and contributions to the early versions of this document 🥹
the authors would like to thank the IVR design team, Roni Even, Lorenzo Miniero, Adnan Saleem, Diego Besprosvan, Mary Barnes, and Steve Buko, who gave valuable feedback, input, and text to this document 🦋
11. Acknowledgments 💜
the authors would like to thank Adnan Saleem, Gene Shtirmer, Dave Burke, Dan York, Steve Buko, Jean-Francois Bertrand, Henry Lum, and Lorenzo Miniero for their expert reviews of this work 🙌
Ben Campbell carried out the RAI expert review on this specification and gave a great deal of invaluable input ✨ Donald Eastlake carried out a thorough security review 🔐
12. References 📚
12.1. Normative References 📚
These are the docs this spec leans on hardcore, so the references below are kept exactly as written 💅
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
Languages", BCP 18, RFC 2277, January 1998.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
Types", RFC 3023, January 2001.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", BCP 13, RFC 4288, December 2005.
[RFC4574] Levin, O. and G. Camarillo, "The Session Description
Protocol (SDP) Label Attribute", RFC 4574, August 2006.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4647] Phillips, A. and M. Davis, "Matching of Language Tags",
BCP 47, RFC 4647, September 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
Languages", BCP 47, RFC 5646, September 2009.
[RFC6230] Boulton, C., Melanchuk, T., and S. McGlashan, "Media
Control Channel Framework", RFC 6230, May 2011.
[SRGS] Hunt, A. and S. McGlashan, "Speech Recognition Grammar
Specification Version 1.0", W3C Recommendation,
March 2004.
[VXML20] McGlashan, S., Burnett, D., Carter, J., Danielsen, P.,
Ferrans, J., Hunt, A., Lucas, B., Porter, B., Rehor, K.,
and S. Tryphonas, "Voice Extensible Markup Language
(VoiceXML) Version 2.0", W3C Recommendation, March 2004.
[VXML21] Oshry, M., Auburn, RJ., Baggia, P., Bodell, M., Burke, D.,
Burnett, D., Candell, E., Carter, J., McGlashan, S., Lee,
A., Porter, B., and K. Rehor, "Voice Extensible Markup
Language (VoiceXML) Version 2.1", W3C Recommendation,
June 2007.
[W3C.REC-SMIL2-20051213]
Jansen, J., Layaida, N., Michel, T., Grassel, G.,
Koivisto, A., Bulterman, D., Mullender, S., and D. Zucker,
"Synchronized Multimedia Integration Language (SMIL 2.1)",
World Wide Web Consortium Recommendation REC-SMIL2-
20051213, December 2005,
<http://www.w3.org/TR/2005/REC-SMIL2-20051213>.
[XML] Bray, T., Paoli, J., Sperberg-McQueen, C M., Maler, E.,
and F. Yergeau, "Extensible Markup Language (XML) 1.0
(Third Edition)", W3C Recommendation, February 2004.
[XMLSchema:Part2]
Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
Second Edition", W3C Recommendation, October 2004.12.2. Informative References 🧠
These ones are extra-helpful background reading, bestie 🌸
[CCXML10] Auburn, R J., "Voice Browser Call Control: CCXML Version
1.0", W3C Candidate Recommendation (work in progress),
April 2010.
[H.248.9] "Gateway control protocol: Advanced media server
packages", ITU-T Recommendation H.248.9.
[IANA] IANA, "RTP Payload Types", available
from http://www.iana.org.
[MIME.mediatypes]
IANA, "MIME Media Types", available
from http://www.iana.org.
[MIXER-CP]
McGlashan, S., Melanchuk, T., and C. Boulton, "A Mixer
Control Package for the Media Control Channel Framework",
Work in Progress, January 2011.
[RFC2897] Cromwell, D., "Proposal for an MGCP Advanced Audio
Package", RFC 2897, August 2000.
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
A., Peterson, J., Sparks, R., Handley, M., and E.
Schooler, "SIP: Session Initiation Protocol", RFC 3261,
June 2002.
[RFC4240] Burger, E., Van Dyke, J., and A. Spitzer, "Basic Network
Media Services with SIP", RFC 4240, December 2005.
[RFC4244] Barnes, M., "An Extension to the Session Initiation
Protocol (SIP) for Request History Information", RFC 4244,
November 2005.
[RFC4267] Froumentin, M., "The W3C Speech Interface Framework Media
Types: application/voicexml+xml, application/ssml+xml,
application/srgs, application/srgs+xml, application/
ccxml+xml, and application/pls+xml", RFC 4267,
November 2005.
[RFC4281] Gellens, R., Singer, D., and P. Frojdh, "The Codecs
Parameter for "Bucket" Media Types", RFC 4281,
November 2005.
[RFC4730] Burger, E. and M. Dolly, "A Session Initiation Protocol
(SIP) Event Package for Key Press Stimulus (KPML)",
RFC 4730, November 2006.
[RFC4733] Schulzrinne, H. and T. Taylor, "RTP Payload for DTMF
Digits, Telephony Tones, and Telephony Signals", RFC 4733,
December 2006.
[RFC4855] Casner, S., "Media Type Registration of RTP Payload
Formats", RFC 4855, February 2007.
[RFC5022] Van Dyke, J., Burger, E., and A. Spitzer, "Media Server
Control Markup Language (MSCML) and Protocol", RFC 5022,
September 2007.
[RFC5167] Dolly, M. and R. Even, "Media Server Control Protocol
Requirements", RFC 5167, March 2008.
[RFC5707] Saleem, A., Xin, Y., and G. Sharratt, "Media Server Markup
Language (MSML)", RFC 5707, February 2010.
[VXML30] McGlashan, S., Burnett, D., Akolkar, R., Auburn, RJ.,
Baggia, P., Barnett, J., Bodell, M., Carter, J., Oshry,
M., Rehor, K., Young, M., and R. Hosn, "Voice Extensible
Markup Language (VoiceXML) Version 3.0", W3C Working
Draft, August 2010.
[XCON-DATA-MODEL]
Novo, O., Camarillo, G., Morgan, D., and J. Urpalainen,
"Conference Information Data Model for Centralized
Conferencing (XCON)", Work in Progress, April 2011.Authors' Addresses ✨
These are the babes who wrote it 🫶
Scott McGlashan
Hewlett-Packard
EMail: smcg.stds01@mcglashan.org
Tim Melanchuk
Rainwillow
EMail: timm@rainwillow.com
Chris Boulton
NS-Technologies
EMail: chris@ns-technologies.com📦 where this page comes from
- ietf: rfc6231 2011-05
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms