Developer Guide for Cisco Virtualized Voice Browser, Release 11.6(1)

Transcription

1 First Published: Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA USA Tel: NETS (6387) Fax:

2 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: 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) 2017 Cisco Systems, Inc. All rights reserved.

3 CONTENTS Preface Preface vii Change History vii About this Guide viii Audience viii Related Documents viii Documentation and Support viii Documentation Feedback viii CHAPTER 1 API Usage and Conventions 1 Application 2 Data Structure for Application 2 Application Scripts and Parameters List 2 Create Application 4 Get List of Applications 5 Get Application 5 Modify Application 6 Delete Application 6 SIP Trigger 7 Data Structure for SIP Trigger 7 Simple Data Structure for SIP Trigger 8 Create SIP Trigger 8 Get List of SIP Triggers 9 Get SIP Trigger by Directory Number 10 Modify SIP Trigger 10 Delete SIP Trigger 11 SIP RAI 11 Data Structure for SIP RAI 12 iii

4 Contents Create SIP RAI 12 Get List of SIP RAI 13 Get SIP RAI by Server Name 13 Modify SIP RAI 13 Delete a SIP RAI 14 Prompt Files 14 Create New Folder for Prompt 14 Upload Prompt 15 Upload Files to Temporary Folder 15 Store Files in Database 16 Get List for Prompt Files and Folder 16 Get Prompt Files and Folder 17 Modify Prompt Folder Name or File Name 17 Delete Prompt Files and Folder 18 ASR 19 ASR Server 19 Data Structure for ASR Server 19 Simple Data Structure for ASR Server 20 Create ASR Server 20 Get List of ASR Server 21 Get ASR Server by Name 21 Modify ASR Server 21 Delete ASR Server 22 TTS 23 TTS Server 23 Data Structure for TTS Server 23 Create TTS Server 24 Get List of TTS Servers 24 Get a TTS Server 25 Modify TTS Server 25 Delete TTS Server 26 VVB Info 26 General APIs 27 GET Client Cache Statistics 27 iv

5 Contents CHAPTER 2 User Input 29 Voice Input 29 DTMF Input 30 Environment and Resources 30 Property 30 Control Flow and Scripting 32 Support Session Variables 32 Cisco-Specific VoiceXML Elements and 33 GTD Manipulation 33 GTD Parameters and Fields Mapped to VoiceXML Variables 34 GTD Object and Parameter Syntax 35 Multiple Instances of GTD Messages 36 Creating a new GTD Message 36 Modifying GTD Parameters 37 GTD Manipulation Sample Scripts 38 Using <transfer and <disconnect for GTD Manipulation 39 APPENDIX A Cisco VVB DTD 41 APPENDIX B Cisco VVB VoiceXML Elements: Reference Table 49 v

6 Contents vi

7 Preface Change History, page vii About this Guide, page viii Audience, page viii Related Documents, page viii Documentation and Support, page viii Documentation Feedback, page viii Change History This table lists changes made to this guide. Most recent changes appear at the top. Change See Date August 2017 Initial Release of Document for Release 11.6(1) Added VRUComprehensive.aef Documented fetchaudio feature Application Scripts and Parameters List Cisco VVB VoiceXML Elements Cisco VVB DTD Added two new properties: com.cisco.sessionxml.location Environment and Resources com.cisco.securelogging vii

8 About this Guide Preface 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 Cisco VVB. Related Documents Cisco VVB provides the following documentation: Solution 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 Solution Port Utilization Guide for Cisco Virtualized Voice Browser Operations Guide 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: 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 to contactcenterproducts_docfeedback@cisco.com viii

9 CHAPTER 1 API Usage and Conventions Cisco VVB provides REST-based API functions that are accessed over HTTP(S). Five API functions are supported; each is mapped to an HTTP(S) operation. Table 1: API Functions and Description API Function Description create (POST) Creates an object in the database and returns a response that contains the URL reference to the newly created object. delete (DELETE) Deletes the object. get (GET) Returns data for an object. update (PUT) Modifies an object. list (GET) Returns a list of objects with multiple records. The POST and PUT operations take a payload with an XML/JSON-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/JSON 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, page 2 SIP Trigger, page 7 SIP RAI, page 11 Prompt Files, page 14 ASR, page 19 TTS, page 23 VVB Info, page 26 1

10 Application API Usage and Conventions General APIs, page 27 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 (mandatory,unique) Numeric identifier of the application applicationname maxsession enabled applicationname int string 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. 1 to maximum number of IVR ports supported for Cisco VVB (mandatory) For more information on the maximum ports supported for your profile, see Virtualization for Cisco Virtualized Voice Browser available at voice_ip_comm/uc_system/ virtualization/ virtualization-cisco-virtualized-voice-browser.html. true false (mandatory) Name that uniquely identifies the application Maximum number of sessions For more information on the maximum sessions supported for your profile, see Virtualization for Cisco Virtualized Voice Browser available at voice_ip_comm/uc_system/ virtualization/ virtualization-cisco-virtualized-voice-browser.html. Application Scripts and Parameters List The following scripts are provided to configure the Applications through APIs. 2

11 API Usage and Conventions 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 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. VRUComprehensive.aef PrimaryVXMLServer BackupVXMLServer "" "" Alphanumeric Alphanumeric The non-reference VRU call flow and VRU-only call flow run this scripting application. Port "7000" Numeric Secured false Boolean Sigdigit 0 Numeric Error.aef CVPErrorPrompt critical_error.wav URL Provide the custom error wav file to play. 3

12 Create Application API Usage and Conventions 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 Application HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Code POST http(s)://<serverip/hostname/fqdn/adminapi/application http(s):// /adminapi/application Application/XML, Application/JSON , 401, 405, 412 4

13 API Usage and Conventions Get List of Applications Sample Input <application <ScriptApplication <scriptsscript[cvpcomprehensive.aef]</script </ScriptApplication <id1</id <applicationnamecomprehensive</applicationname <typecisco Script Application</type <descriptioncomprehensive Application</description <maxsession480</maxsession <enabledtrue</enabled </application Get List of Applications HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/application http(s):// /adminapi/application Application/XML, Application/JSON , 405 Success Response HTTP/ OK Get Application HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/application/{applicationname} http(s):// /adminapi/application/app1 Application/XML, Application/JSON , 405 5

14 Modify Application API Usage and Conventions Success Response HTTP/ OK Modify Application HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes PUT http(s)://<serverip/hostname/fqdn/adminapi/application/{applicationname} http(s):// /adminapi/application/app1 Application/XML, Application/JSON , 401, 405, 412 Sample Input <application <self </self <ScriptApplication <scriptsscript[cvpcomprehensive.aef]</script </ScriptApplication <id1</id <applicationnamecomprehensive</applicationname <typecisco Script Application</type <descriptioncomprehensive Application</description <maxsession480</maxsession <enabledtrue</enabled </application Delete Application HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes DELETE http(s)://<serverip/hostname/fqdn/adminapi/application/{applicationname} http(s):// /adminapi/application/app1 Application/XML, Application/JSON , 404, 405, 412 6

15 API Usage and Conventions SIP Trigger Success Response HTTP/ 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. 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. 7

16 Simple Data Structure for SIP Trigger API Usage and Conventions 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 *. 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 Note For Standalone, Comprehensive, and VRU-only 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. Create SIP Trigger HTTP Method URI Example URI Content Type POST http(s)://<serverip/hostname/fqdn/adminapi/siptrigger http(s):// /adminapi/siptrigger Application/XML, Application/JSON 8

17 API Usage and Conventions Get List of SIP Triggers HTTP Success Code HTTP Failure Codes , 401, 405, 409 Success Response HTTP/ OK Sample Input <siptrigger <self rel="self" href=" type="siptrigger"/ <directorynumber919191*</directorynumber <localeen_us</locale <application name="ringtone" <refurlhttps:// /adminapi/application/ringtone</refurl </application <descriptionringtone</description <callcontrolgroup name="0" <refurlhttps:// /adminapi/callcontrolgroup/0</refurl </callcontrolgroup <triggerenabledtrue</triggerenabled <idletimeout5000</idletimeout <overridemediatermination <dialoggroup name="0" <refurlhttps:// /adminapi/dialoggroup/0</refurl </dialoggroup </overridemediatermination </siptrigger Note For Standalone, Comprehensive, and VRU-only 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. Get List of SIP Triggers HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/siptrigger http(s):// /adminapi/siptrigger Application/XML, Application/JSON , 403, 404, 405 9

18 Get SIP Trigger by Directory Number API Usage and Conventions Success Response HTTP/ OK Get SIP Trigger by Directory Number HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/siptrigger/<trigger number http(s):// /adminapi/siptrigger/ Application/XML, Application/JSON , 401, 402, 404, 405 Success Response HTTP/ OK Modify SIP Trigger HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes PUT http(s)://<serverip/hostname/fqdn/adminapi/siptrigger/<trigger number http(s):// /adminapi/siptrigger/ Application/XML, Application/JSON , 404 Success Response HTTP/ OK Sample Input <siptrigger <self rel="self" href=" type="siptrigger"/ <directorynumber222333</directorynumber <localeen_us</locale 10

19 API Usage and Conventions Delete SIP Trigger <application name="app1" <refurlhttp:// /adminapi/application/app1</refurl </application <descriptionsip_trigger_222333</description <callcontrolgroup name="0" <refurlhttp:// /adminapi/callcontrolgroup/0</refurl </callcontrolgroup <triggerenabledtrue</triggerenabled <idletimeout2500</idletimeout <overridemediatermination <dialoggroup name="0" <refurlhttp:// /adminapi/dialoggroup/0</refurl </dialoggroup </overridemediatermination </siptrigger Note For Standalone, Comprehensive, and VRU-only 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 Example URI Content Type HTTP Success Code HTTP Failure Codes DELETE http(s)://<serverip/hostname/fqdn/adminapi/siptrigger/<trigger number http(s):// /adminapi/siptrigger/ Application/XML, Application/JSON , 404, 500 Success Response HTTP/ 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. 11

20 Data Structure for SIP RAI API Usage and Conventions 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 = SIP server port number to communicate. interval numeric min value = 30 max value = Interval time to send RAI reports. (in seconds) Create SIP RAI HTTP Method POST URI Example URI Content Type HTTP Success Code HTTP Failure Codes http(s)://<serverip/hostname/fqdn/adminapi/siprai http(s):// /adminapi/siprai Application/XML, Application/JSON , 401, 405, 409 Sample Success Response HTTP/ OK Sample Input <siprai <selfhttp:// /adminapi/siprai/server12</self <raiservername </raiservername <portnumber2345</portnumber <interval208</interval </siprai 12

21 API Usage and Conventions Get List of SIP RAI Get List of SIP RAI HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/siprai http(s):// /adminapi/siprai Application/XML, Application/JSON , 403, 404, 405 Success Response HTTP/ OK Get SIP RAI by Server Name HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/siptrigger/siprai/<servername http(s):// /adminapi/siprai/server12 Application/XML, Application/JSON , 401, 402, 404, 405 Success Response HTTP/ OK Modify SIP RAI HTTP Method URI Example URI PUT http(s)://<serverip/hostname/fqdn/adminapi/siprai/<server Name http(s):// /adminapi/siprai/server12 13

22 Delete a SIP RAI API Usage and Conventions Content Type HTTP Success Code HTTP Failure Codes Application/XML, Application/JSON , 404 Success Response HTTP/ OK Sample Input <?xml version="1.0" encoding="utf-8"? <siprai <selfhttp:// /adminapi/siprai/server12</self <raiservername </raiservername <portnumber2346</portnumber <interval220</interval </siprai Delete a SIP RAI HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes DELETE http(s)://<serverip/hostname/fqdn/adminapi/siprai/<server Name http(s):// /adminapi/siprai/server12 Application/XML, Application/JSON , 404, 500 Success Response HTTP/ OK Prompt Files Create New Folder for Prompt HTTP Method POST 14

23 API Usage and Conventions Upload Prompt URI Content Type HTTP Success Code HTTP Failure Codes http(s)://<serverip/hostname/fqdn/adminapi/prompt Application/XML, Application/JSON , 405, 500 Sample Input <?xml version="1.0" encoding="utf-8"? <Files xmlns:xsi=" 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 Temporary Folder HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes POST http(s)://<serverip/hostname/fqdn/adminapi/prompt/uploadfile http(s):// /adminapi/prompt/uploadfile multipart/form-data , 405, 500 Success Response HTTP/ Created 15

24 Get List for Prompt Files and Folder API Usage and Conventions Sample Input form-data file : Attach wave file Store Files in Database HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes Failure Response POST http(s)://<serverip/hostname/fqdn/adminapi/prompt/ http(s):// /adminapi/prompt Application/XML, Application/JSON , 405, 500 HTTP/ Bad Request Success Response HTTP/ Created Sample Input XML Create a Configuration Object for a VXML File <?xml version="1.0" encoding="utf-8"? <Files xmlns:xsi=" 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 GET http(s)://<serverip/hostname/fqdn/adminapi/prompt http(s):// /adminapi/prompt Application/XML, Application/JSON

25 API Usage and Conventions Get Prompt Files and Folder HTTP Failure Codes 401, 405, 500 Success Response HTTP/ OK Get Prompt Files and Folder HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/prompt/<filepath/folderpath Note FilePath is the fully qualified name of the file. FolderPath is the fully qualified name of the folder. http(s):// /adminapi/prompt/folderpath/ http(s):// /adminapi/prompt/filepath Application/XML, Application/JSON , 405, 500 Success Response HTTP/ OK Modify Prompt Folder Name or File Name HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes PUT http(s)://<serverip/hostname/fqdn/adminapi/prompt/<folderpath http(s)://<serverip/hostname/fqdn/adminapi/prompt/<filepath http(s):// /adminapi/prompt/folder/ http(s):// /adminapi/prompt/file Application/XML, Application/JSON ,

26 Delete Prompt Files and Folder API Usage and Conventions Success Response HTTP/ OK Sample Input XML Modifying a Folder URI : Body: <?xml version="1.0" encoding="utf-8"? <Files xmlns:xsi=" 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 : file Body: <?xml version="1.0" encoding="utf-8"? <Files xmlns:xsi=" 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 HTTP Failure Codes DELETE http(s)://<serverip/hostname/fqdn/adminapi/prompt/<file/folderpath http(s):// /adminapi/prompt/folder/ http(s):// /adminapi/prompt/folder/test.wav Application/XML, Application/JSON ,

27 API Usage and Conventions ASR Success Response HTTP/ 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 Hostname 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 an MRCP server: MRCPv1: 4900 MRCPv2: 5060 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. 19

28 ASR Server API Usage and Conventions Simple Data Structure for ASR Server Attribute Name Base Type Restrictions Description asrservername string min length = 1 max length = 50 Hostname 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 = 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 ASR Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes POST http(s)://<serverip/hostname/fqdn/adminapi/asrserver http(s):// /adminapi/asrserver Application/XML, Application/JSON , 401, 405, 409 Success Response HTTP/ OK Sample Input <asrserver <asrservername </asrservername <providernameprovider0</providername <portnumber5060</portnumber <statusreachable</status 20

29 API Usage and Conventions ASR Server <locales <localeen_us</locale </locales </asrserver Get List of ASR Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/asrserver/ http(s):// /adminapi/asrserver/ Application/XML, Application/JSON , 401, 402, 404, 405 Success Response HTTP/ OK Get ASR Server by Name HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/asrserver/<asrservername http(s):// /adminapi/asrserver/asrservername Application/XML, Application/JSON , 401, 402, 405 Success Response HTTP/ OK Modify ASR Server HTTP Method URI PUT http(s)://<serverip/hostname/fqdn/adminapi/asrserver/<asrservername 21

30 ASR Server API Usage and Conventions Example URI Content Type HTTP Success Code HTTP Failure Codes http(s):// /adminapi/asrserver/asrservername Application/XML, Application/JSON , 401, 404 Success Response HTTP/ OK Sample Input <asrservername </asrservername <providernameprovider0</providername <portnumber5060</portnumber <statusreachable</status <locales <localeen_us</locale </locales </asrserver <asrserver <asrservername </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 HTTP Failure Codes DELETE http(s)://<serverip/hostname/fqdn/adminapi/asrserver/<asrservername http(s):// /adminapi/asrserver/asrservername Application/XML, Application/JSON , 404, Success Response HTTP/ OK 22

31 API Usage and Conventions TTS 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 must not be modified and the default value is "Nuance Vocalizer 5.0" portnumber int mininclusive = 0 Port number used for the TTS. maxinclusive = locales localetype minoccurs = 1 maxoccurs = unbounded The type of locale used for the TTS. nillable = false 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) 23

32 TTS Server API Usage and Conventions Attribute Name Base Type Restrictions Description 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 http(s)://<serverip/hostname/fqdn/adminapi/<ttsservername http(s):// /adminapi/ttsserver Application/XML, Application/JSON 200, , 401, 402, 405 Success Response Retrieves the unique URI. Sample Input XML <ttsserver <ttsserverid15</ttsserverid <ttsservername </ttsservername <providernamenuance Vocalizer 5.0</providerName <portnumber5060</portnumber <locales <languageen_us</language <genderneutral</gender <defgenderneutral</defgender </locales </ttsserver Get List of TTS Servers HTTP Method URI Example URI GET http(s)://<serverip/hostname/fqdn/adminapi/ttsserver http(s):// /adminapi/ttsserver 24

33 API Usage and Conventions TTS Server Content Type HTTP Success Code HTTP Failure Codes Application/XML, Application/JSON , 402, 405 Success Response HTTP/ OK Get a TTS Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/ttsserver/<ttsservername http(s):// /adminapi/ttsserver/ttsservername Application/XML, Application/JSON , 402, 404, 405 Success Response HTTP/ OK Modify TTS Server HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes PUT http(s)://<serverip/hostname/fqdn/adminapi/ttsserver</ttsservername http(s):// /adminapi/ttsserver/ttsserver Application/XML, Application/JSON 200, , 401, 402, 404,

34 VVB Info API Usage and Conventions Sample Input <ttsserver <ttsserverid15</ttsserverid <ttsservername </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 DELETE http(s)://<serverip/hostname/fqdn/adminapi/ttsserver/<ttsservername http(s):// /adminapi/ttsserver/ttsservername Application/XML , 402, 404, 405 Success Response HTTP/ OK VVB Info VVB Info trigger reports the current version and the status of Cisco Virtualized Voice Browser. Note PUT, POST, DELETE operations are not supported. Table 3: Data structure for VVB 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 -]+ 26

35 API Usage and Conventions General APIs Get VVB Info HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/ hostname/fqdn/adminapi/vvbinfo http(s):// /adminapi/vvbinfo Application/XML, Application/JSON , 415 Sample Success Response <vvbinfo <vvbversion </vvbversion <vvbstatusin SERVICE</vvbStatus </vvbinfo General APIs GET Client Cache Statistics Note PUT, POST, DELETE operations are not supported. HTTP Method URI Example URI Content Type HTTP Success Code HTTP Failure Codes GET http(s)://<serverip/hostname/fqdn/adminapi/httpclientcache http(s):// /adminapi/httpclientcache Application/XML, Application/JSON , 402, 404,

36 GET Client Cache Statistics API Usage and Conventions 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 totalsizeinkb Description The total cache memory size that is configured. totalsizeusedinkb httpcacheentries httpcacheentry url age size The total cache memory used to store all the files listed. The total size of all the cached files. The list of cached entries with details. 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 age element provides the duration of the URL since it was downloaded. The number of bytes the cache entry has occupied. 28

37 CHAPTER 2 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 Cisco VVB, depending on the type of input and grammar used to collect the input. For user input recognition based on DTMF, Cisco VVB 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 Cisco VVB 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. 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, page 29 DTMF Input, page 30 Environment and Resources, page 30 Control Flow and Scripting, page 32 GTD Manipulation, page 33 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, 29

38 DTMF Input User Input <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. <property name= com.cisco.asr-server value = sip:mresources@mediaserver.com / sets sip:mresources@mediaserver.com 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. 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. 30

39 User Input Property 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 (MRCPv1) which uses Real Time Streaming Protocol (RTSP), for example: <property name= com.cisco.tts-server value= rtsp://tts-server/synthesizer / The media server s URI can be formatted for Media Resource Control Protocol version 2 (MRCPv2) which uses Session Initiation Protocol (SIP), for example: <property name= com.cisco.tts-server value= sip:mresources@mediaserver.com"/ 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 (MRCPv1) which uses RTSP, for example: <property name= com.cisco.asr-server value= rtsp://asr-server/recognizer / The media server s URI can be formatted for Media Resource Control Protocol version 2 (MRCPv2) which uses Session Initiation Protocol (SIP), for example: <property name= com.cisco.asr-server value= sip:mresources@mediaserver.com"/ 31

40 Control Flow and Scripting User Input Property com.cisco.sessionxml.location com.cisco.securelogging Description Allows a document to specify the session xml file location which is used in the SPEAK/RECOGNIZE of MRCPv2 messages. <property name= com.cisco.sessionxml.location value= /CVP/audio/samplesessionXML.xml / This file is a valid optional XML file which contains information required by third-party speech servers. Cisco VVB creates the MIME body using the content of this file and sends it to third-party servers in MRCPv2 dialog-creating request. Note For more information on content of this file, refer to third-party documentation. Allows the user to enable or disable the secure logging functionality to protect sensitive information printed in the logs. This is applicable for user-input-based VXML elements. The value can be true or false to enable or disable the user input logging, for example: <property name="com.cisco.securelogging" value="true" / As the property is applicable at field level, the user should be able to enable or disable secure logging in each field in a single VXML application. Control Flow and Scripting Support Session Variables The following VXML session variables are set depending on the call type: Variable CALL_ANI CALL_DNIS CALL_ID CALL_LEGID PRIMARY BACKUP SECUREDPORT 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 or IP Address for the primary VXML Server. Hostname or IP Address of the backup VXML Server. HTTPS port of the VXML Server. 32

41 User Input Cisco-Specific VoiceXML Elements and Variable PORT CALL_UUI APP_URI CISCO_GUID GTD_BODY Description 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. 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. 33

42 GTD Parameters and Fields Mapped to VoiceXML Variables User Input 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 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'" 34

43 User Input GTD Object and Parameter Syntax 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"] 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_gtd is 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. 35

44 Multiple Instances of GTD Messages User Input 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]['#']. 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). 36

45 User Input Modifying GTD Parameters 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: 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. 37

46 GTD Manipulation Sample Scripts User Input 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!= ' '" <assign name="rc" expr="'failed'"/ </if <log WB_FEAT_GTD_1001:END: <value expr="rc"/ </log <disconnect/ </block </form </vxml 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 38

47 User Input Using <transfer and <disconnect for GTD Manipulation 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 = "' '" / <!-- 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]['#'] == ' '" <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 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: " 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! / 39

48 Using <transfer and <disconnect for GTD Manipulation User Input 40

49 APPENDIX A Cisco VVB DTD Cisco VVB VoiceXML DTD <!-- Cisco Virtualized Voice Browser VoiceXML DTD Copyright 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" 41

50 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 ' 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 42

51 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 -- 43

52 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 44

53 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 45

54 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 46

55 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; 47

56 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. 48

57 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/2.1 W3C Candidate Recommendation in alphabetical order. Note If an unsupported element is used in a VoiceXML document, an error event is generated. <assign element name, expr block, catch, error, filled, help, if, noinput, nomatch - <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 49