First Published: August 10, 2016 Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 USA http://www.cisco.com Tel: 408 526-4000 800 553-NETS (6387) Fax: 408 527-0883
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of the UNIX operating system. All rights reserved. Copyright 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED AS IS" WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental. Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: http:// www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R) 2016 Cisco Systems, Inc. All rights reserved.
CONTENTS Preface Preface vii Change History vii About this Guide vii Audience vii Related Documents viii Documentation and Support viii Documentation Feedback viii CHAPTER 1 System Configuration APIs 1 API Usage and Conventions 1 Application 2 Data Structure for Application 2 Application Scripts and Parameters List 2 Create an Application 4 Get List of Applications 5 Get an Application 5 Modify an Application 6 Delete an Application 7 SIP Trigger 7 Data Structure for SIP Trigger 7 Simple Data Structure for SIP Trigger 8 Create SIP Trigger 9 Get List of SIP Triggers 10 Get SIP Trigger by Directory Number 10 Modify SIP Trigger 10 Delete SIP Trigger 11 SIP RAI 12 iii
Contents Data Structure for SIP RAI 12 Create SIP RAI 12 Get List of SIP RAI 13 Get SIP RAI by Server Name 13 Modify SIP RAI 14 Delete a SIP RAI 15 Prompt Files 15 Create a New Folder for prompt 15 Upload Prompt 16 Upload Files to a Temporary Folder 16 Store Files in Database 17 Get List for Prompt Files and Folder 17 Get Prompt Files and Folder 18 Modify Prompt Folder Name or File Name 18 Delete Prompt Files and Folder 19 ASR 20 ASR Server 20 Data Structure for ASR Server 20 Simple Data Structure for ASR Server 21 Create a ASR Server 21 Get List of ASR Server 22 Get ASR Server by Name 22 Modify ASR Server 23 Delete ASR Server 23 TTS 24 TTS Server 24 Data Structure for TTS Server 24 Create TTS Server 25 Get List of TTS Servers 26 Get a TTS Server 26 Modify TTS Server 27 Delete TTS Server 27 VBB Info 28 General APIs 29 GET Client Cache Statistics 29 iv
Contents CHAPTER 2 Cisco VVB Features 31 User Input 31 Voice Input 31 DTMF Input 32 Environment and Resources 32 Property 32 Control Flow and Scripting 33 Support Session Variables 33 Cisco-Specific VoiceXML Elements and 34 GTD Manipulation 34 GTD Parameters and Fields Mapped to VoiceXML Variables 35 GTD Object and Parameter Syntax 37 Multiple Instances of GTD Messages 37 Creating a new GTD Message 38 Modifying GTD Parameters 38 GTD Manipulation Sample Scripts 39 Using <transfer and <disconnect for GTD Manipulation 41 APPENDIX A Cisco VVB DTD 43 APPENDIX B Cisco VVB VoiceXML Elements: Reference Table 51 v
Contents vi
Preface Change History, page vii About this Guide, page vii Audience, page vii Related Documents, page viii Documentation and Support, page viii Documentation Feedback, page viii Change History This table lists and links to changes made to this guide, and gives the dates those changes were made. Earliest changes appear in the bottom rows. Change Date Initial release of the document. August 10, 2016 About this Guide This document describes how to use the programming APIs provided by Cisco Virtualized Voice Browser (Cisco VVB). Audience This document is intended for developers and administrators to create VoiceXML applications and configure the Cisco VVB respectively. vii
Related Documents Preface Related Documents Cisco VVB provides the following documentation: Design Guide for Cisco Unified Customer Voice Portal Configuration Guide for Cisco Unified Customer Voice Portal Installation and Upgrade Guide for Cisco Virtualized Voice Browser Developer Guide for Cisco Virtualized Voice Browser Port Utilization Guide for Cisco Virtualized Voice Browser Operations Guide for Cisco Virtualized Voice Browser Troubleshooting Wiki for Cisco Virtualized Voice Browser Documentation and Support To download documentation, submit a service request, and find additional information, see What's New in Cisco Product Documentation at: http://www.cisco.com/en/us/docs/general/whatsnew/whatsnew.html You can also subscribe to the What's New in Cisco Product Documentation RSS feed to deliver updates directly to an RSS reader on your desktop. The RSS feeds are a free service. Cisco currently supports RSS Version 2.0. Documentation Feedback To provide comments about this document, send an email to contactcenterproducts_docfeedback@cisco.com viii
CHAPTER 1 System Configuration APIs API Usage and Conventions, page 1 Application, page 2 SIP Trigger, page 7 SIP RAI, page 12 Prompt Files, page 15 ASR, page 20 TTS, page 24 VBB Info, page 28 General APIs, page 29 API Usage and Conventions The Cisco VVB provides REST-based API functions that are accessed over HTTP. Five API functions are supported; each is mapped to an HTTP operation. Table 1: API Functions and Description API Function Description create (http POST) Creates an object in the database and returns a response that contains the URL reference to the newly created object. delete (http DELETE) Deletes the object. get (http GET) Returns data for an object. GET takes an <id. update (http PUT) Modifies an object. list (http GET) Returns a list of objects with multiple records. 1
Application System Configuration APIs The POST and PUT operations take a payload with an XML-based input. GET and DELETE calls do not take a payload. All output is provided as XML when there is a response other than HTTP headers. XML is case sensitive. When XML data is sent to the server, the tag names must match. <Name and <name are two different XML elements. If a payload contains duplicate fields, only one is transmitted. The duplicate fields are ignored. Application Application API provides options to configure, add, modify and delete applications. Data Structure for Application Table 2: The table provides attribute names and description Attribute Name Base Type Restrictions Description ScriptApplication ScriptApplication None Type of script id int 0 to 65535 (mandatory,unique) Numeric identifier of the application applicationname applicationname max length = 30 (mandatory,unique) min length = 1 Application name contains alphanumeric characters, special characters, spaces, underscores (_), and hyphens (-) without leading or trailing white spaces. Name that uniquely identifies the application maxsession int 1 to Number of licenses available (mandatory ) Maximum number of sessions enabled string true false (mandatory) Application Scripts and Parameters List The following scripts are provided to configure the Applications through APIs. 2
System Configuration APIs Application Scripts and Parameters List Note While creating an Application, you must add parameter elements that are required to be configured. The parameters that are not provided in the input XML retains the default value. Script Parameter Default Base Type Description CVPComprehensive.aef Secured false Boolean Use to encrypt the communication between VVB and VXML Server. If this parameter is enabled, ensure to: 1 Upload relevant certificate 2 Restart the VVB tomcat server. To restart the tomcat server, type the following command in CLI: utils service restart Cisco Tomcat Sigdigit "0" Numeric Enable this parameter to use Significant Digits feature. Enter the number of digits that are used as sigdigit. When the Cisco VVB receives the call, the CVP comprehensive service is configured to strip the digits, so that when the IVR leg of the call is set up, the original label is used on the incoming VoiceXML request. Error.aef CVPErrorPrompt critical_error.wav URL Provide the custom error wav file to play. 3
Create an Application System Configuration APIs Script Parameter Default Base Type Description SelfService.aef ApplicationName "HelloWorld" Alphanumaric Application name that is present on the VXML server. Mandatory field to enter. port "7000" Numeric Port on which the CVP or load balancer is running. Primary VXMLServer "" Alphanumaric IP address of CVP or load balancer. Backup VXMLServer "" Alphanumaric CVP backup server. secured false Boolean To encrypt the communication between VVB and VXML Server. If this parameter is enabled, ensure to: 1 Change the port number to "7443" 2 Upload relevant certificate 3 Restart the VVB tomcat server. To restart the tomcat server, type the following command in CLI: utils service restart Cisco Tomcat Ringtone.aef CVPRingtone ringback.vxml Numeric Default ringtone that is configured on Unified CVP. Create an Application HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Code Error Codes POST http://<serverip/adminapi/application http://serverip/adminapi/application Application/XML, Application/JSON 201 400, 401, 405, 412 4
System Configuration APIs Get List of Applications Sample Input <application <ScriptApplication <scriptsscript[selfservice.aef]</script </ScriptApplication <id58</id <applicationnameapp1</applicationname <typecisco Script Application</type <descriptioncisco Script Application</description <maxsession25</maxsession <enabledtrue</enabled <defaultscriptringtone.aef</defaultscript </application Note The number of sessions for <maxsession must not exceed the total number of license installed. Get List of Applications HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes GET http://<serverip/adminapi/application http://serverip/adminapi/application Application/XML, Application/JSON 200 401, 405 Success Response HTTP/1.1 200 OK Get an Application HTTP Method URI Example URI Content Type GET http://<serverip/adminapi/application/{applicationname} http://serverip/adminapi/application/app1 Application/XML, Application/JSON 5
Modify an Application System Configuration APIs HTTP Success Code HTTP Failure Codes Error Codes 200 401, 405 Success Response HTTP/1.1 200 OK Modify an Application HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes PUT http://<serverip/adminapi/application/{applicationname} http://serverip/adminapi/application/app1 Application/XML, Application/JSON 200 400, 401, 405, 412 Sample Input <application <ScriptApplication <scriptsscript[selfservice.aef]</script </ScriptApplication <id58</id <applicationnameapp1</applicationname <typecisco Script Application</type <descriptioncisco Script Application</description <maxsession20</maxsession <enabledtrue</enabled <defaultscriptringtone.aef</defaultscript </application Note The number of sessions for <maxsession must not exceed the total number of license provided. 6
System Configuration APIs Delete an Application Delete an Application HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes DELETE http://<serverip/adminapi/application/{applicationname} http://serverip/adminapi/application/app1 Application/XML, Application/JSON 200 401, 404, 405, 412 Success Response HTTP/1.1 200 OK SIP Trigger A SIP trigger responds to calls that arrive on a specific route point by selecting telephony and media resources to serve the call and invoking an application script to handle the call. Note You must configure SIP triggers to invoke application scripts in response to incoming contacts. Data Structure for SIP Trigger Attribute Name Base Type Restrictions Description directorynumber directorynumber minoccurs = 1 A unique phone number. maxoccurs = 1 locale RestrictedString minoccurs = 0 Defines the locale. maxoccurs = 1 application nameuripair minoccurs = 1 maxoccurs = 1 Application name used to associate with the trigger. 7
Simple Data Structure for SIP Trigger System Configuration APIs Attribute Name Base Type Restrictions Description description description minoccurs = 1 maxoccurs = 1 A descriptive name for the CTI route point. callcontrolgroup nameuripair minoccurs = 1 maxoccurs = 1 The call control group used to associate with the trigger. triggerenabled boolean minoccurs = 1 maxoccurs = 1 Used to enable or disable the trigger. default = true idletimeout baseidint minoccurs = 0 maxoccurs = 1 default = "5000" The number of milliseconds (ms) the system should wait before rejecting the SIP request for this trigger. overridemediatermination overridemediatermination minoccurs = 0 maxoccurs = 1 Used to enable or disable the media termination. Simple Data Structure for SIP Trigger Attribute Name Base Type Restrictions Description directorynumber string min length = 1 max length = 24 A unique identifier for this device. All digits from 0 to 9, and character *!T.X. description string min length = 1 max length = 50 A descriptive name for the CTI route point. Regex: ([^\s;^"\\; &<>,/] {1,}[^"\\; &<>,/]*) Description cannot have special characters ",\,&,<,,,,/ and cannot have a leading space. overridemediatermination sequence (dialoggroup : nameuripair) minoccurs= 0 maxoccurs = "unbounded" Override media termination 8
System Configuration APIs Create SIP Trigger Create SIP Trigger HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes POST http://<serverip/adminapi/siptrigger http://serverip/adminapi/siptrigger Application/XML, Application/JSON 201 400, 401, 405, 409 Success Response HTTP/1.1 200 OK Sample Input <siptrigger <self rel="self" href="http://10.78.0.35/adminapi/siptrigger/222333" type="siptrigger"/ <directorynumber222333</directorynumber <localeen_us</locale <application name="app1" <refurlhttp://10.78.0.35/adminapi/application/app1</refurl </application <descriptionsip_trigger_222333</description <callcontrolgroup name="0" <refurlhttp://10.78.0.35/adminapi/callcontrolgroup/0</refurl </callcontrolgroup <triggerenabledtrue</triggerenabled <idletimeout5000</idletimeout <overridemediatermination <dialoggroup name="0" <refurlhttp://10.78.0.35/adminapi/dialoggroup/0</refurl </dialoggroup </overridemediatermination </siptrigger Note For Standalone and Comprehensive applications, set dialoggroup element attribute as 1. For example, <dialoggroup name ="1". This will select default as MRCP dialog group. For Ringtone and Error applications, set dialoggroup element attribute as 0. For example, <dialoggroup name ="0". This will select default as CMT. 9
Get List of SIP Triggers System Configuration APIs Get List of SIP Triggers HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes GET http://<serverip/adminapi/siptrigger http://<serverip/adminapi/siptrigger Application/XML, Application/JSON 200 401, 403, 404, 405 Success Response HTTP/1.1 200 OK Get SIP Trigger by Directory Number HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes GET http://<serverip/adminapi/siptrigger/<trigger number http://serverip/adminapi/siptrigger/888666 Application/XML, Application/JSON 200 400, 401, 402, 404, 405 Success Response HTTP/1.1 200 OK Modify SIP Trigger HTTP Method PUT 10
System Configuration APIs Delete SIP Trigger URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes http://<serverip/adminapi/siptrigger/<trigger number http://serverip/adminapi/siptrigger/222333 Application/XML, Application/JSON 200 400, 404 Success Response HTTP/1.1 200 OK Sample Input <siptrigger <self rel="self" href="http://10.78.0.35/adminapi/siptrigger/222333" type="siptrigger"/ <directorynumber222333</directorynumber <localeen_us</locale <application name="app1" <refurlhttp://10.78.0.35/adminapi/application/app1</refurl </application <descriptionsip_trigger_222333</description <callcontrolgroup name="0" <refurlhttp://10.78.0.35/adminapi/callcontrolgroup/0</refurl </callcontrolgroup <triggerenabledtrue</triggerenabled <idletimeout2500</idletimeout <overridemediatermination <dialoggroup name="0" <refurlhttp://10.78.0.35/adminapi/dialoggroup/0</refurl </dialoggroup </overridemediatermination </siptrigger Note For Standalone and Comprehensive applications, set dialoggroup element attribute as 1. For example, <dialoggroup name ="1". This will select default as MRCP dialog group. For Ringtone and Error applications, set dialoggroup element attribute as 0. For example, <dialoggroup name ="0". This will select default as CMT. Delete SIP Trigger HTTP Method URI DELETE http://<serverip/adminapi/siptrigger/<trigger number 11
SIP RAI System Configuration APIs Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes http://serverip/adminapi/siptrigger/222333 Application/XML, Application/JSON 200 400, 404, 500 Success Response HTTP/1.1 200 OK SIP RAI The Resource Available Indication (RAI) feature monitors CPU, memory, DSP, and DS0 resources and reports the Cisco VVB status to the externally configured device. Data Structure for SIP RAI Attribute Name Base Type Restrictions Description Server Name alphanumeric min length = 1 Host name or server IP address. max length = 24 regex: [A-Za-z0-9.-_\s] port numeric min value = 1 max value = 65535 SIP server port number to communicate. interval numeric min value = 30 max value = 86400 Interval time to send RAI reports. (in seconds) Create SIP RAI HTTP Method POST URI http://<serverip/adminapi/siprai Example URI http://serverip/adminapi/siprai 12
System Configuration APIs Get List of SIP RAI Content Type HTTP Success Code HTTP Failure Codes Error Codes Application/XML, Application/JSON 201 400, 401, 405, 409 Success Response HTTP/1.1 200 OK Sample Input <siprai <selfhttp://10.64.82.147/adminapi/siprai/server12</self <raiservername10.345.24</raiservername <portnumber2345</portnumber <interval208</interval </siprai Get List of SIP RAI HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes GET http://<serverip/adminapi/siprai http://<serverip/adminapi/siprai Application/XML, Application/JSON 200 401, 403, 404, 405 Success Response HTTP/1.1 200 OK Get SIP RAI by Server Name HTTP Method URI GET http://<serverip/adminapi/siptrigger/siprai/<servername 13
Modify SIP RAI System Configuration APIs Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes http://serverip/adminapi/siprai/server12 Application/XML, Application/JSON 200 400, 401, 402, 404, 405 Success Response HTTP/1.1 200 OK Modify SIP RAI HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes PUT http://<serverip/adminapi/siprai/<server Name http://serverip/adminapi/siprai/server12 Application/XML, Application/JSON 200 400, 404 Success Response HTTP/1.1 200 OK Sample Input <?xml version="1.0" encoding="utf-8"? <siprai <selfhttp://10.64.82.147/adminapi/siprai/server12</self <raiservername10.345.24</raiservername <portnumber2346</portnumber <interval220</interval </siprai 14
System Configuration APIs Delete a SIP RAI Delete a SIP RAI HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes DELETE http://<serverip/adminapi/siprai/<server Name http://serverip/adminapi/siprai/server12 Application/XML, Application/JSON 200 400, 404, 500 Success Response HTTP/1.1 200 OK Prompt Files Unified Voice Browser applications can make use of auxiliary files such as pre-recorded prompts to interact with callers. To manage these auxiliary files, you must complete the following tasks: Provision telephony and media resources. Provision Unified Voice Browser subsystem, if required. Provision additional subsystems, if required. Configure Cisco script applications. Create a New Folder for prompt HTTP Method URI Content Type HTTP Success Code HTTP Failure Codes POST http://<serverip/adminapi/prompt Application/XML 201 401, 405, 500 15
Upload Prompt System Configuration APIs Error Codes - Sample Input <?xml version="1.0" encoding="utf-8"? <Files xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:nonamespaceschemalocation= "Files.xsd" <Prompt <Folder <path/</path <FolderNamePromptFolder1</FolderName </Folder </Prompt </Files Upload Prompt Uploading the prompt is a two-step process: 1 Upload files into a temporary folder 2 Store files in database Upload Files to a Temporary Folder HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes POST http://<serverip/adminapi/prompt/uploadfile http://serverip/adminapi/prompt/uploadfile multipart/form-data 201 401, 405, 500 Success Response HTTP/1.1 201 Created Sample Input form-data file : Attach wave file 16
System Configuration APIs Get List for Prompt Files and Folder Store Files in Database HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Failure Response Error Codes POST http://<serverip/adminapi/prompt/ http://serverip/adminapi/prompt Application/XML, Application/JSON 201 401, 405, 500 HTTP/1.1 400 Bad Request Success Response HTTP/1.1 201 Created Sample Input XML Create a Configuration Object for a VXML File <?xml version="1.0" encoding="utf-8"? <Files xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:nonamespaceschemalocation="files.xsd" <Prompt <File <path/ftcustompromptlanguage1/ftcustompromptfolder1/</path <FileNameFTCustomPrompt3.wav</FileName </File </Prompt </Files Get List for Prompt Files and Folder HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http://<serverip/adminapi/prompt http://serverip/adminapi/prompt Application/XML, Application/JSON 200 401, 405, 500 17
Get Prompt Files and Folder System Configuration APIs Error Codes Success Response HTTP/1.1 200 OK Get Prompt Files and Folder HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes GET http://<serverip/adminapi/prompt/{filepath/folderpath} Note FilePath is the fully qualified name of the file. FolderPath is the fully qualified name of the folder. http://serverip/adminapi/prompt/folderpath/ http://serverip/adminapi/prompt/filepath/ Application/XML, Application/JSON 200 401, 405, 500 Success Response HTTP/1.1 200 OK Modify Prompt Folder Name or File Name HTTP Method URI Example URI Content Type HTTP Success Code PUT http://<serverip/adminapi/prompt/folderpath http://<serverip/adminapi/prompt/filepath http://serverip/adminapi/prompt/folder/ http://serverip/adminapi/prompt/file/ Application/XML, Application/JSON 200 18
System Configuration APIs Delete Prompt Files and Folder HTTP Failure Codes Error Codes 404, 500 Success Response HTTP/1.1 200 OK Sample Input XML Modifying a Folder URI : http://10.64.82.163/adminapi/prompt/<folder_name/ Body: <?xml version="1.0" encoding="utf-8"? <Files xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:nonamespaceschemalocation= "Files.xsd" <Prompt <Folder <path/</path <FolderNameFOLDER_NAME</FolderName <renametonew FOLDER_NAME</reNameTo </Folder </Prompt </Files Sample Input XML Modifying a File URI : http://10.64.82.163/adminapi/prompt/<wav file Body: <?xml version="1.0" encoding="utf-8"? <Files xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:nonamespaceschemalocation= "Files.xsd" <Prompt <File <path/</path <FileNamewav file</filename <renametonew wav filename</renameto </File </Prompt </Files Delete Prompt Files and Folder HTTP Method URI Example URI Content Type HTTP Success Code DELETE http://<serverip/adminapi/prompt/{file/folderpath} http://serverip/adminapi/prompt/folder/ http://serverip/adminapi/prompt/folder/test.wav Application/XML, Application/JSON 200 19
ASR System Configuration APIs HTTP Failure Codes Error Codes 404, 500 Success Response HTTP/1.1 200 OK ASR The Automatic Speech Recognition (ASR) subsystem allows users to navigate through a menu of options by speaking instead of pressing keys on a touch-tone telephone. Note Use these port number for MRCPv1: 4900 and for MRCPv2: 5060 ASR Server Use this API to specify information about the speech server's name, port location, and available language. Data Structure for ASR Server Attribute Name Base Type Restrictions Description asrserverid baseidint minoccurs = 0 maxoccurs = 1 Host name or IP address in which the ASR server software is installed. asrservername string minoccurs = 1 maxoccurs = 1 IP Address or hostname of the ASR server. providername providertype Default ASR provider name should not be modified and the default value is "provider0". portnumber int minoccurs = 1 maxoccurs = 1 TCP port numbers used to connect to a MRCP server: OSR 3.1x 4900 2003 SISR 554 Nuance 554 20
System Configuration APIs ASR Server Attribute Name Base Type Restrictions Description locales locale minoccurs = 1 maxoccurs = 1 Languages supported by the ASR Provider. status string minoccurs = 1 maxoccurs = 1 Provides the status of the ASR server. Simple Data Structure for ASR Server Attribute Name Base Type Restrictions Description asrservername string min length = 1 max length = 50 Host name or IP address of the server. regex: [A-Za-z0-9.-_\s] providertype string min length = 1 Name of the ASR Provider max length = 20 regex: [A-Za-z0-9.-_\s] portnumber int min value = 1 max value = 65535 TCP port numbers that are used to connect to the server. locale string regex: [a-z]{2}_[a-z]{2} [a-z]{2} Languages supported by the ASR Provider. Create a ASR Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes POST http://<serverip/adminapi/asrserver http://<serverip/adminapi/asrserver Application/XML, Application/JSON 201 400, 401, 405, 409 21
ASR Server System Configuration APIs Success Response HTTP/1.1 201 OK Sample Input <asrservername10.11.12.14</asrservername <providernameprovider0</providername <portnumber5060</portnumber <locales <localeen_us</locale </locales </asrserver Get List of ASR Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes GET http://<serverip/adminapi/asrserver/ http://<serverip/adminapi/asrserver/ Application/XML, Application/JSON 200 400, 401, 402, 404, 405 Success Response HTTP/1.1 200 OK Get ASR Server by Name HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http://<serverip/adminapi/asrserver/<asrservername http://<serverip/adminapi/asrserver/asrservername Application/XML, Application/JSON 200 400, 401, 402, 405 22
System Configuration APIs ASR Server Error Codes Success Response HTTP/1.1 200 OK Modify ASR Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes PUT http://<serverip/adminapi/asrserver/<asrserverrname http://<serverip/adminapi/asrserver/asrservername Application/XML, Application/JSON 200 400, 401, 404 Success Response HTTP/1.1 200 OK Sample Input <asrservername10.64.82.174</asrservername <providernameprovider0</providername <portnumber5060</portnumber <statusreachable</status <locales <localeen_us</locale </locales </asrserver Delete ASR Server HTTP Method URI Example URI Content Type HTTP Success Code DELETE http://<server/adminapi/asrserver/<asrserverrname http://<serverip/adminapi/asrserver/asrservername Application/XML, Application/JSON 200 23
TTS System Configuration APIs HTTP Failure Codes Error Codes 400, 404, Success Response HTTP/1.1 200 OK TTS The Text-To-Speech (TTS) subsystem converts plain text (UNICODE) into spoken words to provide information or prompt a user to respond to an action. Note Use these port number for MRCPv1: 4900 and for MRCPv2: 5060 TTS Server Use this API to configure the TTS server's name, port location, and available languages. Data Structure for TTS Server Attribute Name Base Type Restrictions Description ttsservername string Regex: [A-Za-z0-9_.-]+ IP Address or hostname of the TTS server. \d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3} providername providertype Default TTS provider that should not be modified and the default value is "Nuance Vocalizer 5.0" portnumber int mininclusive = 0 Port number used for the TTS. maxinclusive = 65535 locales localetype minoccurs = 1 maxoccurs = unbounded The type of locale used for the TTS. nillable = false 24
System Configuration APIs TTS Server Attribute Name Base Type Restrictions Description language string minoccurs = 1 maxoccurs = 1 The type of language used for the TTS. nillable = false gender enumeration minoccurs = 1 maxoccurs = 1 The type of gender used for the TTS. nillable = false Enumeraton: (Male, Female and Neutral) defaultgender enumeration minoccurs = 1 maxoccurs = 1 The default gender used for the TTS. nillable = false Enumeraton: (Male, Female and Neutral) Create TTS Server HTTP Method POST URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes http://<serverip/adminapi/<ttsservername http://serverip/adminapi/ttsserver Application/XML 200, 201 400, 401, 402, 405 Success Response Retrieves the unique URI. Sample Input XML <ttsserver <ttsserverid15</ttsserverid <ttsservername10.64.82.171</ttsservername <providernamenuance Vocalizer 5.0</providerName <portnumber5060</portnumber 25
TTS Server System Configuration APIs <locales <languageen_us</language <genderneutral</gender <defgenderneutral</defgender </locales </ttsserver Get List of TTS Servers HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes GET http://<serverip/adminapi/ttsserver http://serverip/adminapi/ttsserver Application/XML, Application/JSON 200 401, 402, 405 Success Response HTTP/1.1 200 OK Get a TTS Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes GET http://<serverip/adminapi/ttsserver/<ttsservername http://serverip/adminapi/ttsserver/ttsservername Application/XML, Application/JSON 200 401, 402, 404, 405 Success Response HTTP/1.1 200 OK 26
System Configuration APIs TTS Server Modify TTS Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes PUT http://<serverip/adminapi/ttsserver</ttsservername http://serverip/adminapi/ttsserver/ttsserver Application/XML 200, 201 400, 401, 402, 404, 405 Sample Input <ttsserver <ttsserverid15</ttsserverid <ttsservername10.64.82.171</ttsservername <providernamenuance Vocalizer 5.0</providerName <portnumber5060</portnumber <locales <languageen_us</language <genderneutral</gender <defgenderneutral</defgender </locales </ttsserver Delete TTS Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes DELETE http://<serveipr/adminapi/ttsserver/<ttsservername http://serverip/adminapi/ttsserver/ttsservername Application/XML 200 401, 402, 404, 405 Success Response HTTP/1.1 200 OK 27
VBB Info System Configuration APIs VBB Info VBB Info trigger reports current Cisco Virtualized Voice Browser version and Cisco Virtualized Voice Browser status. Note PUT, POST, DELETE operations are not supported. Table 3: Data structure for VBB Info Attribute Name Base Type Restrictions Description vvbversion string minoccurs=1 maxoccurs=1 Cisco VVB Version, Regex Details :: [0-9._-]+ vvbstatus string minoccurs=1 maxoccurs=1 Cisco VVB Status, Regex Details :: [a-za-z -]+ Get VVB Info HTTP Method GET URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes http://<serverip/ HostName/FQDN/adminapi/vvbInfo http://10.10.10.10/adminapi/vvbinfo Application/XML 200 405, 415 - Success Response <vvbinfo <vvbversion11.5.0.99100-86</vvbversion <vvbstatusin SERVICE</vvbStatus </vvbinfo 28
System Configuration APIs General APIs General APIs GET Client Cache Statistics HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Error Codes GET https://<serverip/adminapi/httpclientcache http://serverip/adminapi/httpclientcache Application/XML, Application/JSON 200 401, 402, 404, 405 Success Response <?xml version="1.0" encoding="utf-8"? <httpclientcaches <httpclientcache <totalsizeinkb24414</totalsizeinkb <totalsizeusedinkb383</totalsizeusedinkb <totalnumberofentries3</totalnumberofentries <httpcacheentries <httpcacheentry <urlhttp://10.xx.xx.xx:80/en-us/app/music.wav</url <age03 days:01 hours:14 minutes:23 seconds</age <size392120</size </httpcacheentry <httpcacheentry <urlhttp://10.xx.xx.xx:7000/cvp/audio/cachetest.vxml</url <age03 days:01 hours:14 minutes:23 seconds</age <size423</size </httpcacheentry <httpcacheentry <urlhttp://10.xx.xx.xx:7000/cvp/audio/counter.js</url <age03 days:01 hours:14 minutes:23 seconds</age <size21</size </httpcacheentry </httpcacheentries </httpclientcache </httpclientcaches Element Description totalsizeinkb totalsizeusedinkb httpcacheentries The total cache memory size that is configured. The total cache memory used up to store all the files listed. The total size of all the cached files. The list of cached entries with details. 29
GET Client Cache Statistics System Configuration APIs Element httpcacheentry url age size Description The individual cache entry with details. Shows the entire URL that the data is retrieved from. Note The URL starts with either "http:" or "https:". The distinction between the following two URLs: http://www.myserver.com/app.vxml and https://www.myserver.com/app.vxml. The age element provides the duration of the URL since it was downloaded. The number of bytes the cache entry has occupied. 30
CHAPTER 2 Cisco VVB Features User Input, page 31 Environment and Resources, page 32 Control Flow and Scripting, page 33 GTD Manipulation, page 34 User Input You can use two types of user input in Cisco VVB, voice and DTMF. Cisco VVB accepts both types of input and processes them either through an external media server or through voice gateway, depending on the type of input and grammar used to collect the input. For user input recognition based on DTMF, the voice gateway is capable of recognizing that input without the help of any external media recognition devices. Recognition of user input such as ASR or TTS involves an external media server working with the voice gateway. The grammar formats required to process ASR and TTS-based input are dependent on the support provided by the media server vendor. All external media servers are required to support at least the W3C XML grammar format. Media server vendors may support other standard or proprietary grammar formats such as Nuance GSL grammar format. Note Regex is the only grammar format supported for DTMF-based recognition. Regex grammar used for DTMF input is a Cisco grammar format and is not supported by vendors on their media servers. Voice Input To handle voice input, an external media server is required to work with Cisco VVB. The media server conducts ASR and communicates the interpretation back to the VoiceXML interpreter, running on the voice browser, for processing. Cisco VVB only supports W3C XML grammar for speech recognition. The user can dynamically change the media server for the next ASR by setting the Cisco-specific VoiceXML property com.cisco.asr-server in the VoiceXML script. For example, the statement, 31
DTMF Input Cisco VVB Features <property name= com.cisco.asr-server value = rtsp://asr-server/recognizer / sets rtsp://asr-server/recognizer as the external media server for the next ASR, and continues with the same setting until the property is set again with a different server. <property name= com.cisco.asr-server value = default / sets default and the existing connection to the ASR server gets disconnected, and uses local VVB for DTMF recognition. DTMF Input To handle DTMF input, VoiceXML uses either an external media server or the Cisco VVB, which can handle all DTMF applications. Use W3C XML grammar to enable external media server to collect DTMF input. Use Cisco specific DTMF grammar to enable Cisco VVB to collect DTMF input. Environment and Resources Property Cisco <property extensions are listed in the table. 32
Cisco VVB Features Control Flow and Scripting Property com.cisco.tts-server Description Allows the document to specify an external media server for text-to-speech operations. The media server is specified in the form of an URI, and is used in all consecutive ASR operations until the next media server is specified. It can be defined for: An entire application or document at the <vxml level, A specific dialog at the form or menu level, or A specific form item. The media server s URI can be formatted for Media Resource Control Protocol version 1 (MRCP v1) which uses Real Time Streaming Protocol (RTSP), for example: <property name= com.cisco.tts-server value= rtsp://tts-server/synthesizer / There are two ways to specify an external media server for TTS and ASR operations: Servers configured through administrator page or REST APIs Media server sessions are created for each call to IVR applications, regardless of whether an application needs to talk to the media server. com.cisco.tt-server and com.cisco.asr-server <property extensions Media server sessions are created for each call to that application. If only a small number of applications require TTS/ASR media sessions, you should use the <property extensions within those applications to define the external media server URL in the VoiceXML script. com.cisco.asr-server Allows a document to specify an external media server for automatic speech recognition operations. The media server is specified in the form of an URI, and is used in all consecutive ASR operations. By default, the media server is selected in round-robin approach. If you specify a particular media server, then only that specified server is used by overriding the default behavior. The media server s URI can be formatted for Media Resource Control Protocol version 1 (MRCP v1) which uses RTSP, for example: <property name= com.cisco.asr-server value= rtsp://asr-server/recognizer / Control Flow and Scripting Support Session Variables The following VXML session variables are set depending on the call type: 33
Cisco-Specific VoiceXML Elements and Cisco VVB Features Variable CALL_ANI CALL_DNIS CALL_ID CALL_LEGID PRIMARY BACKUP SECUREDPORT PORT CALL_UUI APP_URI CISCO_GUID GTD_BODY Description Value of ANI for the incoming call. Value of DN for the incoming call. Value of Cisco-GUID header for the INVITE. Value of CALL-ID header for the INVITE. Hostname of IOP Address for the primary VXML Server. Hostname or IP Address of the backup VXML Server. HTTPS port of the VXML Server. Nonsecured HTTP port of the VXML Server. User-to-User information for the incoming call. VXML application URL. Value of Cisco-GUID header of the INVITE. Generic Transparency Descriptor (GTD) message from the incoming call. Cisco-Specific VoiceXML Elements and The following Cisco proprietary tags are supported: cisco-gtd Used as attribute cisco-typeaheadflush Used as either attribute or element cisco-disc_cause Used as attribute GTD Manipulation Cisco VVB enables a VoiceXML script to access GTD parameters before and after a call transfer, to append and override GTD parameters, and to create new GTD messages. For example, if an incoming call setup event contains a GTD IAM message, the <transfer element uses the IAM message and overrides or appends the parameters specified by the <transfer GTD attributes. If the incoming setup event does not contain the IAM message, and if the VoiceXML script wants to send a GTD message on the outgoing leg, it creates a new IAM GTD message and adds or appends the required GTD parameters to it. The VoiceXML script sends this new GTD message to the outgoing leg using the <transfer element. The GTD messages can only contain parameters specified in the tables in this document. 34
Cisco VVB Features GTD Parameters and Fields Mapped to VoiceXML Variables GTD messages and their individual parameters are represented as JavaScript objects. The GTD message object is at the top level, and the individual parameters are represented at the subobject level. The individual subfields of supported GTD parameters can be accessed and modified as properties of the parameter subobject. GTD messages received on an incoming call leg during the setup event are represented by the Cisco VoiceXML session variable com.cisco.signal.gtdlist which is an array of GTD objects indexed by the call signal event name (setup_indication). This session variable allows the VoiceXML script to only read the GTD parameters received in the setup message. Being a session variable, the VoiceXML script has read-only access to the GTD parameters. The Cisco VoiceXML shadow variable of the form <transfer_name$.com.cisco.signal.gtdlist is used to read GTD parameters on the outgoing leg after the call transfer terminates. This shadow variable is a read-only variable representing an array of GTD objects indexed by the call signal event name. Reading a valid parameter that is not included in a GTD message results in the return value undefined. Setting a parameter that is not supported causes an exception error event to be thrown by the system. The object com.cisco.objclass.gtd is a Cisco object class that is used to modify an existing GTD message or create a new GTD message that allows the VoiceXML script to have read-write access to the GTD messages. The VoiceXML script can use the Cisco attribute cisco-gtd with the <transfer element to send a modified GTD message to the outbound call leg. The attribute represents the GTD object that is sent on the outbound leg. cisco-gtd is also used with the <disconnect element to send a GTD message during a call release. GTD Parameters and Fields Mapped to VoiceXML Variables The following table describes GTD parameters and fields that are supported in Cisco VVB. Note A GTD parameter can be sent or received in any GTD message. Table 4: GTD Parameter and Field GTD Parameter.Field CGN.noa CGN.npi CGN.cni CGN.pi CGN.si CGN.# UUS.pd UUS.dat DIS.info 35
GTD Parameters and Fields Mapped to VoiceXML Variables Cisco VVB Features To create, modify, and read GTDs, the following Cisco objects are used: com.cisco.objclass.gtd This is a Cisco-specific JavaScript object class that is used to create new GTD messages. To create an object of a specific class (instantiate) for creating a new GTD message, use: X= new com.cisco.objclass.gtd() Later, the GTD message can be represented in a format similar to: X.message_type = "'IAM'" Note IAM is used only as an example com.cisco.signal.gtdlist This is a Cisco-specific session variable that represents an array of GTD objects (each object representing a GTD message) for signaling events arriving on the incoming leg. The elements of this array can be accessed in read-only mode. The VoiceXML script accesses the GTD parameters and their fields from this session variable, which is indexed by the signaling event as shown in the following format: com.cisco.signal.gtdlist["setup_indication"] where The elements of this array are read-only. The VoiceXML/ECMA script can access the GTD parameters and their fields from com.cisco.signal.gtdlist indexed by the signaling event as in: X = com.cisco.signal.gtdlist["setup_indication"] where X is read-only. dat1 = X.UUS[0].dat for the dat field in the first instance of the UUS parameter. Another Object can be created from com.cisco.signal.gtdlist using the new operation in com.cisco.objclass.gtd as in: Y = new com.cisco.objclass.gtd(com.cisco.signal.gtdlist["setup_indication"]) In this case, the new object Y contains a copy of the GTD message that arrived with the Setup Ind event and is a read-write object. Y can now be used for modifying GTD parameters. <transfer-name$.com.cisco.signal.gtdlist This is a Cisco-specific shadow variable that is used by the VoiceXML script to access GTD parameters on the outgoing leg after the <transfer is complete. The shadow variable consists of the transfer name and "$" prepended to com.cisco.signal.gtdlist. In <transfer name= "gtd_xfer".../, gtd_xfer$.com.signal.gtdlist is an array of GTD objects for the outgoing leg indexed by signaling event names mentioned in gtd_xfer$.com.cisco.signal.gtdlist["<event-name"] 36
Cisco VVB Features GTD Object and Parameter Syntax GTD Object and Parameter Syntax GTD Parameter Syntax <gtd-object-name.<gtd-parameter-name [<instance-number] For example, the first instance of the UUS parameter is referenced as my_gtd.uus[0], where my_gtdis created as an instance of the GTD message or com.cisco.signal.gtdlist. GTD Parameter Field Syntax <gtd-object-name.<gtd-parameter-name[<instance-number].<field-name For example, the datafield of the first instance of the UUS parameter is referenced as my_gtd.uus[0].dat, where my_gtdis created as an instance of the GTD message or com.cisco.signal.gtdlist. Multiple Instances of GTD Messages A parameter in a GTD message can have multiple instances which need not be contiguous. In VoiceXML and JavaScript, indexing of instance numbers of GTD parameters starts with zero. For example, the first instance of a GTD parameter is referenced with the index number zero, the second instance is referenced with the index number one, the third instance is referenced with the index number two, and so on. The syntax <gtd-object-name.<gtd-parameter-object-name[<instance-number] refers to a specific instance. The property instance_count is exposed to every GTD parameter object. The VoiceXML script must first read this property before accessing a specific instance. The instance number must be less than or equal to the total number of instances read by the script. For example: <assign name="my_gtd" expr= "new com.cisco.objclass.gtd(com.cisco.signal.gtdlist['setup_indication'])"/ <assign name="total_uus_inst" expr="my_gtd.uus.instance_count"/ <assign name="uus2" expr="my_gtd.uus[2]" / <assign name="uus2" expr="my_gtd.uus[2].dat"/ GTD parameter instance numbers start with 0 for the first instance. For example, <assign name= "my_gtd" expr= "com.cisco.signal.gtdlist['setup_indication']"/ <assign name= "uus1" expr= "my_gtd.uus[0]"/ == for first UUS instance <assign name= "uus2" expr= "my_gtd.uus[1]"/ == for second UUS instance Note If VoiceXML and JavaScript do not accept some special characters such as #, -, or + for field names, those field names must be provided within square brackets []. For example, to access the number (#) field of the first instance of the CGN parameter using JavaScript, it is specified as var cgn_num= my_gtd.cgn[0]['#']. 37
Creating a new GTD Message Cisco VVB Features Creating a new GTD Message The Cisco object class com.cisco.objclass.gtdis used to create GTD objects for read-write purposes. This object class is used to create a completely new GTD message or to create a copy of a GTD message received in a signaling event. To create a new GTD message, use the format new com.cisco.objclass.gtd(). Example: <var name= "my_new_gtd" expr= "new com.cisco.objclass.gtd()"creates a new empty GTD message. The message type for this GTD can be set later. For example, <var name= "my_new_gtd.message_type" expr="iam"/. This GTD message is sent out using the <transfer element. Only GTD objects can be created; parameter objects cannot be created. For example, <assign name="my_uus" expr="new UUS"/ is incorrect. <assign name="my_uus" expr="my_gtd.uus[0]"/ is correct (for the first instance). Modifying GTD Parameters To modify a GTD message, an instance is created using the new operator in com.cisco.objclass.gtd. Examples 1 <var name= "my_gtd" expr= "new com.cisco.objclass.gtd(com.cisco.signal.gtdlist['setup_indication'])"/ This example creates a copy of the GTD message that came with the Setup Ind event on the incoming leg. 2 <var name= "out_gtd" expr= "new com.cisco.objclass.gtd(gtd_xfer$.com.cisco.signal.gtdlist['setup_indication'])"/ This example creates a copy of the GTD message from the <transfer shadow variable gtd_xfer$.com.cisco.signal.gtdlist (assuming that gtd_xfer was the name of the transfer.) out_gtd contains a copy of the GTD parameters that arrived in the setup message on the outgoing leg. This is a read-write variable and is used to modify GTD parameters. 3 <var name= "my_gtd" expr= "new com.cisco.objclass.gtd(com.cisco.signal.gtdlist['setup_indication'])"/ This example creates a copy of the GTD message received in the setup message on the incoming leg which will be used to modify a GTD message. <assign name= "my_gtd.uus[0].dat" expr="'99'"/ updates the dat field of the first instance of the UUS parameter of the GTD message represented by my_gtd. <var name= "my_uus" expr= "my_gtd.uus[0]"/ // first instance of UUS parameter <var name= "uus_data" expr= "my_uus.dat"/ <assign name= "my_uus.dat" expr= "hello"/ This example shows a VoiceXML script modifying a GTD message that arrived with a Setup Ind event. The same example is shown here using an ECMAScript: <script var my_gtd= new com.cisco.objclass.gtd(com.cisco.signal.gtdlist["setup_indication"]) var my_uus= my_gtd.uus[0]; // first instance of UUS parameter my_uus.dat= "'hello'"; <script/ The following modifications of a GTD parameter or field are supported: 38
Cisco VVB Features GTD Manipulation Sample Scripts Replace Append Delete is not supported. If the VoiceXML script adds an instance of a GTD parameter with the instance number being greater than the current instance count by one, the parameter is appended. If the instance number is less than or equal to the current instance count, the specified parameter is replaced. Examples If the number of instances currently existing in a GTD message is two, and: The VoiceXML script specifies <assign name= "UUS[2].dat" expr= "'ABCDEF0123'"/, the GTD parameter is appended. The VoiceXML script specifies <assign name= "UUS[1].dat" expr= "'ABCDEF0123'"/, the GTD parameter is replaced. The VoiceXML script specifies <assign name= "my_gtd[4].dat" expr= "'ABCDEF0123'"/, an exception error is thrown because in this case only the instance numbers of 0 to 2 are valid, 0 and 1 for replace and 2 for append. GTD Manipulation Sample Scripts Here are some sample scripts you can use to get familiar with GTD Manipulation. Accessing GTD parameters received during call setup <vxml version="2.0" <form <var name="x" expr="com.cisco.signal.gtdlist['setup_indication']"/ <var name="cgn1" expr="x.cgn[0].noa"/ <var name="cgn2" expr="x.cgn[0].npi"/ <var name="cgn3" expr="x.cgn[0].pi"/ <var name="cgn4" expr="x.cgn[0].si"/ <var name="y" expr="x.cgn[0]['#']"/ <block <log y is:<value expr="y"/:</log <var name="rc" expr="'passed'"/ <if cond="y!= '9876543210'" <assign name="rc" expr="'failed'"/ </if <log WB_FEAT_GTD_1001:END: <value expr="rc"/ </log <disconnect/ </block </form </vxml 39
GTD Manipulation Sample Scripts Cisco VVB Features Creating a GTD Message <form <var name="my_new_gtd0" expr="new com.cisco.objclass.gtd()"/ <var name="my_new_gtd1" expr="new com.cisco.objclass.gtd()"/ <var name="my_new_gtd2" expr="new com.cisco.objclass.gtd()"/ <var name="my_new_gtd3" expr="new com.cisco.objclass.gtd()"/ <var name = "my_new_gtd0.message_type" expr = "'IAM'"/ <var name = "my_new_gtd1.message_type" expr = "'ACM'"/ <var name = "my_new_gtd2.message_type" expr = "'CPG'"/ <var name = "my_new_gtd3.message_type" expr = "'REL'"/ <block <log message type for my_new_gtd0 is <value expr="my_new_gtd0.message_type"/</log <log message type for my_new_gtd1 is <value expr="my_new_gtd1.message_type"/</log <log message type for my_new_gtd2 is <value expr="my_new_gtd2.message_type"/</log <log message type for my_new_gtd3 is <value expr="my_new_gtd2.message_type"/</log <goto next="#printresult"/ </block </form <catch event="error.semantic" <assign name="res" expr="'failed'"/ <goto next="#printresult"/ </catch <form id="printresult" <block <log <value expr="testcase"/:end:<value expr="res"/ </log </block </form </vxml Modifying in a GTD Message <form <var name="my_gtd0" expr="new com.cisco.objclass.gtd()"/ <var name = "my_gtd0.message_type" expr = "'IAM'" / <var name = "my_gtd0.cgn[0].npi" expr = "4" / <var name = "my_gtd0.cgn[0].pi" expr = "'y'" / <var name = "my_gtd0.cgn[0]['#']" expr = "'408-527-4800'" / <!-- Second gtd message use if needed -- <var name="my_gtd1" expr="new com.cisco.objclass.gtd()"/ <var name = "my_gtd1.message_type" expr = "'CPG'" / <block <log message type for my_gtd0 is <value expr="my_gtd0.message_type"/</log <log cgn.npi for my_gtd0 is <value expr="my_gtd0.cgn[0].npi"/</log <log cgn.pi for my_gtd0 is <value expr="my_gtd0.cgn[0].pi"/</log <log cgn.# for my_gtd0 is <value expr="my_gtd0.cgn[0]['#']"/</log <if cond="my_gtd0.cgn[0].npi== '4' my_gtd0.cgn[0].pi== 'y' my_gtd0.cgn[0]['#'] == '408-527-4800'" <assign name="res" expr="'passed'"/ <else/ <log Failed to modify new GTD instance.</log </if <goto next="#printresult"/ </block </form <form id="printresult" <block <log <value expr="testcase"/:end:<value expr="res"/ </log </block </form </vxml 40
Cisco VVB Features Using <transfer and <disconnect for GTD Manipulation Accessing a Valid but Unavailable GTD Parameter <form <var name="x" expr="com.cisco.signal.gtdlist['setup_indication']"/ <var name= uus" expr="x.uus[0]"/ <block <if cond="uus == 'Undefined' uus == 'undefined'" <log UUS unavailable <value expr= uus"/:</log <else/ <assign name= uusdat" expr="x.uus[0].dat"/ </if </block </form </vxml Using <transfer and <disconnect for GTD Manipulation The Cisco-specific attribute cisco-gtd is used with the <transfer element to send GTDs on the outgoing call leg. <transfer name="gtd_xfer" dest="tel: +1-555-555-0167" bridge="true"!! cisco-gtd="my_gtd"!! / It is also used as an attribute of the <disconnect element to send GTDs during a call release. <disconnect cisco-disc_cause= cause_code cisco-gtd= my_gtd! / 41
Using <transfer and <disconnect for GTD Manipulation Cisco VVB Features 42
APPENDIX A Cisco VVB DTD Cisco VVB VoiceXML DTD <!-- Cisco Virtualized Voice Browser VoiceXML DTD Copyright 1998-2006 W3C (MIT, ERCIM, Keio), All Rights Reserved. Permission to use, copy, modify and distribute the VoiceXML DTD and its accompanying documentation for any purpose and without fee is hereby granted in perpetuity, provided that the above copyright notice and this paragraph appear in all copies. The copyright holders make no representation about the suitability of the DTD for any purpose. It is provided "as is" without expressed or implied warranty. -- <!ENTITY % audio "#PCDATA audio enumerate value" <!ENTITY % bargeintype "( speech hotword )" <!ENTITY % boolean "(true false)" <!ENTITY % content.type "CDATA" <!ENTITY % duration "CDATA" <!ENTITY % event.handler "catch help noinput nomatch error" <!ENTITY % event.name "NMTOKEN" <!ENTITY % event.names "NMTOKENS" <!ENTITY % executable.content "%audio; assign clear data disconnect exit foreach goto if log prompt reprompt return script submit throw var cisco-typeaheadflush " <!ENTITY % expression "CDATA" <!ENTITY % restrictedvariable.name "CDATA" <!ENTITY % variable.name "CDATA" <!ENTITY % restrictedvariable.names "CDATA" <!ENTITY % variable.names "CDATA" <!ENTITY % integer "CDATA" <!ENTITY % item.attrs "name %restrictedvariable.name; #IMPLIED cond %expression; #IMPLIED expr %expression; #IMPLIED " <!ENTITY % uri "CDATA" <!ENTITY % cache.attrs "fetchhint (prefetch safe) #IMPLIED fetchtimeout %duration; #IMPLIED maxage %integer; #IMPLIED maxstale %integer; #IMPLIED" <!ENTITY % next.attrs "next %uri; #IMPLIED expr %expression; #IMPLIED " <!ENTITY % submit.attrs "method (get post) 'get' enctype %content.type; 'application/x-www-form-urlencoded' namelist %variable.names; #IMPLIED" <!ENTITY % throw.attrs "event %event.name; #IMPLIED eventexpr %expression; #IMPLIED message CDATA #IMPLIED messageexpr %expression; #IMPLIED" <!ENTITY % variable "block data field var" 43
Cisco VVB DTD <!--================================= Root ================================-- <!ELEMENT vxml (%event.handler; data form link menu meta metadata property script var )+ <!ATTLIST vxml application %uri; #IMPLIED xml:base %uri; #IMPLIED xml:lang NMTOKEN #IMPLIED xmlns CDATA #FIXED 'http://www.w3.org/2001/vxml' xmlns:xsi CDATA #IMPLIED xsi:schemalocation CDATA #IMPLIED version CDATA #REQUIRED <!ELEMENT meta EMPTY <!ATTLIST meta name NMTOKEN #IMPLIED content CDATA #REQUIRED http-equiv NMTOKEN #IMPLIED <!ELEMENT metadata ANY <!--================================ Prompts ==============================-- <!-- definitions adapted from SSML 1.0 DTD -- <!ENTITY % structure "p s" <!ENTITY % sentence-elements "break emphasis phoneme prosody say-as voice sub" <!-- addition of enumerate and value elements as 'allowed-within-sentence' audio elements -- <!ENTITY % allowed-within-sentence " %audio; %sentence-elements; " <!-- Prompt is modelled on SSML 1.0 DTD speak element: - addition of 'bargein', 'bargeintype', 'cond', 'count' and 'timeout' attributes - removal of xmlns, xmlns:xsi, and xsi:schemalocation attributes - version attribute fixed as "1.0" -- <!ELEMENT prompt (%allowed-within-sentence; foreach %structure; lexicon metadata meta )* <!ATTLIST prompt bargein %boolean; #IMPLIED bargeintype %bargeintype; #IMPLIED cond %expression; #IMPLIED count %integer; #IMPLIED xml:lang NMTOKEN #IMPLIED cisco-typeaheadflush %boolean; false timeout %duration; #IMPLIED xml:base %uri; #IMPLIED version CDATA #FIXED "1.0" <!ELEMENT enumerate (%allowed-within-sentence; %structure;)* <!ELEMENT reprompt EMPTY <!--================================= Dialogs =============================-- <!ENTITY % input "grammar" <!ENTITY % scope "(document dialog)" <!ELEMENT form (%input; %event.handler; filled initial object link property record script subdialog transfer %variable;)* <!ATTLIST form id ID #IMPLIED scope %scope; "dialog" <!ENTITY % accept.attrs "accept (exact approximate) 'exact'" <!ELEMENT menu (%audio; choice %event.handler; prompt property )* <!ATTLIST menu 44
Cisco VVB DTD id ID #IMPLIED scope %scope; "dialog" %accept.attrs; dtmf %boolean; "false" <!ELEMENT choice ( #PCDATA %input; )* <!ATTLIST choice %cache.attrs; accept (exact approximate) #IMPLIED dtmf CDATA #IMPLIED %throw.attrs; fetchaudio %uri; #IMPLIED %next.attrs; <!--================================ Audio Output ==============================-- <!-- definitions adapted from SSML 1.0 DTD -- <!ELEMENT p (%allowed-within-sentence; s)* <!ATTLIST p xml:lang NMTOKEN #IMPLIED <!ELEMENT s (%allowed-within-sentence;)* <!ATTLIST s xml:lang NMTOKEN #IMPLIED <!ELEMENT voice (%allowed-within-sentence; %structure;)* <!ATTLIST voice xml:lang NMTOKEN #IMPLIED gender (male female neutral) #IMPLIED age %integer; #IMPLIED variant %integer; #IMPLIED name CDATA #IMPLIED <!ELEMENT prosody (%allowed-within-sentence; %structure;)* <!ATTLIST prosody pitch CDATA #IMPLIED contour CDATA #IMPLIED range CDATA #IMPLIED rate CDATA #IMPLIED duration %duration; #IMPLIED volume CDATA #IMPLIED <!-- Changes to SSML 1.0 DTD audio element: - src not obligatory, addition of 'expr' and caching attributes -- <!ELEMENT audio (%allowed-within-sentence; %structure; desc)* <!ATTLIST audio src %uri; #IMPLIED expr %expression; #IMPLIED %cache.attrs; <!ELEMENT desc (#PCDATA) <!ATTLIST desc xml:lang NMTOKEN #IMPLIED <!ELEMENT emphasis (%allowed-within-sentence;)* <!ATTLIST emphasis level (strong moderate none reduced) "moderate" <!-- Changes to SSML 1.0 DTD say-as element: - allows value element as child -- 45
Cisco VVB DTD <!ELEMENT say-as (#PCDATA value )* <!ATTLIST say-as interpret-as NMTOKEN #REQUIRED format NMTOKEN #IMPLIED detail NMTOKEN #IMPLIED <!ELEMENT sub (#PCDATA) <!ATTLIST sub alias CDATA #REQUIRED <!ELEMENT phoneme (#PCDATA) <!ATTLIST phoneme ph CDATA #REQUIRED alphabet CDATA #IMPLIED <!ELEMENT break EMPTY <!ATTLIST break time CDATA #IMPLIED strength (none x-weak weak medium strong x-strong) "medium" <!--================================ Fields ===============================-- <!ELEMENT field (%audio; %event.handler; filled %input; link option prompt property)* <!ATTLIST field %item.attrs; type CDATA #IMPLIED slot NMTOKEN #IMPLIED modal %boolean; "false" <!ELEMENT option (#PCDATA) <!ATTLIST option %accept.attrs; dtmf CDATA #IMPLIED value CDATA #IMPLIED <!ELEMENT var EMPTY <!ATTLIST var name %restrictedvariable.name; #REQUIRED expr %expression; #IMPLIED <!ELEMENT initial (%audio; %event.handler; link prompt property)* <!ATTLIST initial %item.attrs; <!ELEMENT block (%executable.content;)* <!ATTLIST block %item.attrs; <!ELEMENT assign EMPTY <!ATTLIST assign name %variable.name; #REQUIRED expr %expression; #REQUIRED <!ELEMENT clear EMPTY <!ATTLIST clear namelist %variable.names; #IMPLIED <!ELEMENT value EMPTY <!ATTLIST value expr %expression; #REQUIRED 46
Cisco VVB DTD <!--================================== Events =============================-- <!ENTITY % event.handler.attrs "count %integer; #IMPLIED cond %expression; #IMPLIED" <!ELEMENT catch (%executable.content;)* <!ATTLIST catch event %event.names; #IMPLIED %event.handler.attrs; <!ELEMENT error (%executable.content;)* <!ATTLIST error %event.handler.attrs; <!ELEMENT help (%executable.content;)* <!ATTLIST help %event.handler.attrs; <!ELEMENT link (%input;)* <!ATTLIST link %cache.attrs; %next.attrs; fetchaudio %uri; #IMPLIED dtmf CDATA #IMPLIED %throw.attrs; <!ELEMENT noinput (%executable.content;)* <!ATTLIST noinput %event.handler.attrs; <!ELEMENT nomatch (%executable.content;)* <!ATTLIST nomatch %event.handler.attrs; <!ELEMENT throw EMPTY <!ATTLIST throw %throw.attrs; <!--============================= Grammar Input =============================-- <!-- definitions adapted from SRGS 1.0 DTD -- <!ENTITY % rule-expansion "#PCDATA token ruleref item one-of tag " <!ELEMENT ruleref EMPTY <!ATTLIST ruleref uri %uri; #IMPLIED type CDATA #IMPLIED special (NULL VOID GARBAGE) #IMPLIED <!ELEMENT token (#PCDATA) <!ATTLIST token xml:lang NMTOKEN #IMPLIED <!ELEMENT tag (#PCDATA) <!ELEMENT one-of (item)+ <!ATTLIST one-of xml:lang NMTOKEN #IMPLIED <!ELEMENT item (%rule-expansion;)* <!ATTLIST item repeat NMTOKEN #IMPLIED repeat-prob NMTOKEN #IMPLIED 47
Cisco VVB DTD weight NMTOKEN #IMPLIED xml:lang NMTOKEN #IMPLIED <!ELEMENT rule (%rule-expansion; example)* <!ATTLIST rule id ID #REQUIRED scope (private public) "private" <!ELEMENT example (#PCDATA) <!ELEMENT lexicon EMPTY <!ATTLIST lexicon uri %uri; #REQUIRED type CDATA #IMPLIED <!-- Changes to SRGS 1.0 DTD grammar element: - mixed, unordered content model - addition of 'scope', 'src', 'type', 'weight' and caching attributes - 'version' attribute is optional - removal of xmlns, xmlns:xsi, and xsi:schemalocation attributes -- <!ELEMENT grammar (#PCDATA meta metadata lexicon rule tag)* <!ATTLIST grammar scope %scope; #IMPLIED src %uri; #IMPLIED srcexpr %expression; #IMPLIED type CDATA #IMPLIED weight CDATA #IMPLIED %cache.attrs; tag-format %uri; #IMPLIED xml:base %uri; #IMPLIED version NMTOKEN #IMPLIED xml:lang NMTOKEN #IMPLIED root IDREF #IMPLIED mode (voice dtmf) "voice" <!--============================= Audio Input =============================-- <!ELEMENT record (%audio; %event.handler; filled %input; prompt Property)* <!ATTLIST record %item.attrs; type CDATA #IMPLIED beep %boolean; "false" maxtime %duration; #IMPLIED modal %boolean; "true" finalsilence %duration; #IMPLIED dtmfterm %boolean; "true" <!--============================ Call Control ============================-- <!ELEMENT disconnect EMPTY <!ATTLIST disconnect namelist %variable.names; #IMPLIED cisco-gtd expression; #IMPLIED cisco-disc_cause expression; #IMPLIED <!ELEMENT transfer (%audio; %event.handler; filled %input; prompt Property)* <!ATTLIST transfer %item.attrs; dest %uri; #IMPLIED destexpr %expression; #IMPLIED bridge %boolean; #IMPLIED type NMTOKEN #IMPLIED connecttimeout %duration; #IMPLIED maxtime %duration; #IMPLIED transferaudio %uri; #IMPLIED 48
Cisco VVB DTD aai CDATA #IMPLIED aaiexpr %expression; #IMPLIED <!--============================ Control Flow ============================-- <!ENTITY % if.attrs "cond %expression; #REQUIRED" <!ELEMENT if (%executable.content; elseif else)* <!ATTLIST if %if.attrs; <!ELEMENT elseif EMPTY <!ATTLIST elseif %if.attrs; <!ELEMENT else EMPTY <!ELEMENT exit EMPTY <!ATTLIST exit expr %expression; #IMPLIED namelist %variable.names; #IMPLIED <!ELEMENT filled (%executable.content;)* <!ATTLIST filled mode (any all) #IMPLIED namelist %restrictedvariable.names; #IMPLIED <!-- executable content + contents of prompt -- <!ELEMENT foreach (%executable.content; %sentence-elements; %structure; )* <!ATTLIST foreach item %restrictedvariable.name; #REQUIRED array CDATA #REQUIRED <!ELEMENT goto EMPTY <!ATTLIST goto %cache.attrs; %next.attrs; fetchaudio %uri; #IMPLIED expritem %expression; #IMPLIED nextitem %restrictedvariable.name; #IMPLIED <!ELEMENT param EMPTY <!ATTLIST param name NMTOKEN #REQUIRED expr %expression; #IMPLIED value CDATA #IMPLIED valuetype (data ref) "data" type CDATA #IMPLIED <!ELEMENT return EMPTY <!ATTLIST return namelist %variable.names; #IMPLIED %throw.attrs; <!ELEMENT subdialog (%audio; %event.handler; filled param prompt Property)* <!ATTLIST subdialog %item.attrs; src %uri; #IMPLIED srcexpr %expression; #IMPLIED %cache.attrs; fetchaudio %uri; #IMPLIED %submit.attrs; 49
Cisco VVB DTD <!ELEMENT submit EMPTY <!ATTLIST submit %cache.attrs; %next.attrs; fetchaudio %uri; #IMPLIED %submit.attrs; <!--========================== Miscellaneous ==============================-- <!ELEMENT data EMPTY <!ATTLIST data name %restrictedvariable.name; #IMPLIED src %uri; #IMPLIED srcexpr %expression; #IMPLIED fetchaudio %uri; #IMPLIED %submit.attrs; %cache.attrs; <!ELEMENT log (#PCDATA value)* <!ATTLIST log label CDATA #IMPLIED expr %expression; #IMPLIED <!ELEMENT object (%audio; %event.handler; filled param prompt Property)* <!ATTLIST object %item.attrs; %cache.attrs; classid %uri; #IMPLIED codebase %uri; #IMPLIED data %uri; #IMPLIED type CDATA #IMPLIED codetype CDATA #IMPLIED archive %uri; #IMPLIED <!ELEMENT property EMPTY <!ATTLIST property name NMTOKEN #REQUIRED value CDATA #REQUIRED <!ELEMENT script (#PCDATA) <!ATTLIST script src %uri; #IMPLIED srcexpr %expression; #IMPLIED charset CDATA #IMPLIED %cache.attrs; <!ELEMENT cisco-typeaheadflush EMPTY Note The bargein type hotword is not supported. The cache attribute prefetch is not supported. 50
APPENDIX B Cisco VVB VoiceXML Elements: Reference Table This appendix contains the VoiceXML elements used by Cisco VVB, and summarizes the elements and their attributes, and their corresponding parent and children elements in the VoiceXML 2.0 W3C Candidate Recommendation in alphabetical order. Note If an unsupported element is used in a VoiceXML document, an error event is generated. However, there is a subset of unsupported elements which are ignored and for which error events are generated. <assign element name, expr block, catch, error, filled, help, if, noinput, nomatch No children <audio element src, fetchtimeout, fetchhint, maxage, maxstale, expr block, catch, choice, emphasis, error, field, filled, help, if, initial, menu, noinput, nomatch, object, p, paragraph, prosody, record, s, sentence, subdialog, transfer, voice audio, break, emphasis, enumerate, mark, p, paragraph, phoneme, prosody, s, say-as, sentence, value, voice, #pcdata 51