Jump to: navigation, search

Using AngelXML

AngelXML is a powerful way to define Voice Page objects programmatically. When you use AngelXML, you can defer the creation of a voice user interface to the time a call is occurring. AngelXML allows you to tap into the full functionality of the Site Builder framework from your own web server.

To use AngelXML, create a Transaction Page and specify AngelXML as the response type.

To see some examples of AngelXML, see AngelXML Examples.

Document Type Definition

Use the following Document Type Definition to validate output from your scripts:

<!ELEMENT ANGELXML (VARIABLES?, (MESSAGE | QUESTION | TRANSFER |
VOICEMAIL), VARIABLES?) >
<!ATTLIST ANGELXML
bargein (true | false) "true"
xmlns CDATA #IMPLIED
xmlns:xsd CDATA #IMPLIED
xmlns:xsi CDATA #IMPLIED
>
<!ELEMENT MESSAGE (COMMENT*, PLAY, (LINK* | ACTION | GOTO), ERROR_STRATEGY*) >
<!ELEMENT QUESTION (COMMENT*, PLAY, RESPONSE, ERROR_STRATEGY*, ASR_SETTINGS?) >
<!ATTLIST QUESTION
var CDATA #IMPLIED
>
<!ELEMENT RESPONSE (KEYWORD | NUMBER | YES_NO | CREDITCARD | CCEXP | CURRENCY |
DATE | TIME) >
<!ATTLIST RESPONSE
confirm (true | false) "false"
>
<!ELEMENT ASR_SETTINGS (PROPERTY+) >
<!ELEMENT PROPERTY EMPTY >
<!ATTLIST PROPERTY
name (confidencelevel | sensitivity | speedvsaccuracy | completetimeout | incompletetimeout | 
interdigittimeout | timeout | maxspeechtimeout) #REQUIRED
value CDATA #REQUIRED
>
<!ELEMENT VOICEMAIL (COMMENT*, PLAY, (ACTION | GOTO)? , ERROR_STRATEGY*) >
<!ATTLIST VOICEMAIL
mailbox CDATA #REQUIRED
confirm (true | false) "false"
finalSilence CDATA #IMPLIED
var CDATA #IMPLIED
>
<!ELEMENT TRANSFER (COMMENT*, PLAY, ERROR_STRATEGY*) >
<!ATTLIST TRANSFER
destination CDATA #REQUIRED
rings CDATA "4"
if_fail CDATA "hangup"
if_completed CDATA #REQUIRED
out_caller_id CDATA #IMPLIED
>
<!ELEMENT ERROR_STRATEGY (PROMPT+, (ACTION | GOTO)?)>
<!ATTLIST ERROR_STRATEGY
type (noinput | nomatch) #REQUIRED
reprompt (true | false) #IMPLIED
>

<!ELEMENT COMMENT (#PCDATA) >
<!ELEMENT PLAY (PROMPT+) >
<!ELEMENT PROMPT (#PCDATA) >
<!ATTLIST PROMPT type (text|sound|audio|angelaudio|externalaudio) "text">
<!ELEMENT ACTION EMPTY>
<!ATTLIST ACTION
type (back | hangup) #REQUIRED
>
<!ELEMENT GOTO EMPTY>
<!ATTLIST GOTO
destination CDATA #REQUIRED
>
<!ELEMENT LINK EMPTY>
<!ATTLIST LINK
keyword CDATA #IMPLIED
dtmf CDATA #IMPLIED
returnValue CDATA #IMPLIED
destination CDATA #REQUIRED
>
<!ELEMENT KEYWORD (LINK+)>
<!ELEMENT CREDITCARD ((MASTERCARD | VISA | AMEX | DISCOVER | DINERSCLUB)+,
VALID, INVALID)>
<!ELEMENT MASTERCARD EMPTY>
<!ELEMENT VISA EMPTY>
<!ELEMENT AMEX EMPTY>
<!ELEMENT DISCOVER EMPTY>
<!ELEMENT DINERSCLUB EMPTY>
<!ELEMENT CCEXP (VALID, INVALID)>
<!ELEMENT NUMBER EMPTY>
<!ATTLIST NUMBER
numberType (natural | variable | fixed | range) #IMPLIED
numberLength CDATA "5"
minNumberLength CDATA "1"
maxNumberLength CDATA "5"
destination CDATA #REQUIRED
>
<!ELEMENT CURRENCY EMPTY>
<!ATTLIST CURRENCY
destination CDATA #REQUIRED
>
<!ELEMENT DATE EMPTY>
<!ATTLIST DATE
destination CDATA #REQUIRED
>
<!ELEMENT TIME EMPTY>
<!ATTLIST TIME
destination CDATA #REQUIRED
>

<!ELEMENT YES_NO (YES, NO)>
<!ELEMENT YES EMPTY>
<!ATTLIST YES
destination CDATA #REQUIRED
>
<!ELEMENT NO EMPTY>
<!ATTLIST NO
destination CDATA #REQUIRED
>
<!ELEMENT VALID EMPTY>
<!ATTLIST VALID
destination CDATA #REQUIRED
>
<!ELEMENT INVALID EMPTY>
<!ATTLIST INVALID
destination CDATA #REQUIRED
>
<!ELEMENT VARIABLES (VAR*)>
<!ELEMENT VAR EMPTY>
<!ATTLIST VAR
name CDATA #REQUIRED
type CDATA #IMPLIED
value CDATA #IMPLIED
separator CDATA #IMPLIED
>


AngelXML Node Semantics

The following XML nodes exist in AngelXML:

XML Node
Parent Description Requirements Attributes
ACTION

MESSAGE VOICEMAIL ERROR_STRATEGY

Defines an action to be taken after the playback of prompts on a Message Page, or the recording of a voicemail message on a Voicemail Page, or reaching the last PROMPT on an ERROR_STRATEGY. None type (required)— To end the call, set this attribute to hangup. To send the caller back to the previous page, set this attribute to back
AMEX
CREDITCARD The credit card is accepted. None None
ANGELXML
None The root node of an AngelXML document.

at most one VARIABLE node either one MESSAGE node or one QUESTION node one TRANSFER node one VOICEMAIL node

bargein (optional)—To prevent users from interrupting prompt playback on this voice page with speech or DTMF input, set this attribute to false. The default value is true.
xmlns (optional)—Prevents parsing errors if ANGELXML has been generated programmatically by an XML Generator (.NET, for example).
xmlns:xsd (optional)—Prevents parsing errors if ANGELXML has been generated programmatically by an XML Generator (.NET, for example).
xmlns:xsi (optional)—Prevents parsing errors if ANGELXML has been generated programmatically by an XML Generator (.NET, for example).

ASR_SETTINGS
QUESTION Defines the customized ASR Settings of a Question Page. One or more PROPERTY nodes None
CCEXP
RESPONSE Defines a Credit Card Expiration Question Page. one VALID node.

one INVALID node.

None
COMMENT

MESSAGE QUESTION TRANSFER VOICEMAIL

Allows you to comment your AngelXML code. None None
CREDITCARD
RESPONSE Contains the nodes related to specifying accepted credit card types for a Question Page and destinations for valid and/or invalid card scenarios. Must be one or more of:
  • MASTERCARD
  • VISA
  • AMEX
  • DISCOVER
  • DINERSCLUB

one VALID node
one INVALID node

None
Note: Credit Card validation is performed to ensure that a credit card number is plausible, or well formed. It does not authorize the credit card (no AVS check is performed).
CURRENCY
RESPONSE Defines the current Question Page as a Currency Question Page. None destination (required)—Defines the destination site and page code to follow. Define the destination as 123/456 where 123 represents the site number and 456 the page number.
Notes: When using currency Question Pages, the following responses are accepted from the caller:
  • X dollars and Y Cents
  • Dollars: Natural numbers from 0 to 999,999
  • Cents: Natural numbers from 0 to 99

With DTMF/keypad input, use digits for dollar, followed by * for decimal point, and two digits for cents.

DATE
RESPONSE Defines the current Question Page as a Date Question Page. None destination (required)—Defines the destination site and page code to follow. Define the destination as 123/456 where 123 represents the site number and 456 the page number.
Notes: When using date Question Pages, the following responses are accepted from the caller: today, tomorrow, yesterday, Month, day and Month, Day, Year.

Callers can also enter the response using an eight-digit string such as MMDDYYYY. Today, Tomorrow and Yesterday are considered as EST time.

DINERSCLUB
CREDITCARD This type of credit card is accepted. None None
DISCOVER
CREDITCARD This type of credit card is accepted. None None
ERROR_STRATEGY

MESSAGE QUESTION TRANSFER VOICEMAIL

Defines a set of prompts to play incrementally if the caller does not respond to an initial dialog, or responds with an unrecognized utterance or keypad press. one or more PROMPT nodes

one ACTION node or one GOTO node

type (required)—Defines the type of strategy that this node will react to. Possible values:
  • noinput: Define a noinput strategy to specify which prompts will be played if the caller does not speak or press any key after the main Voice Page prompts are played.
  • nomatch: Define a nomatch strategy to specify which prompts will be played if the caller speaks something not defined, or unambiguously defined in the active site and page level links. This strategy will also be triggered if the caller presses a key with no defined action.

reprompt (optional)—Defines whether the system will play the main page prompt(s) after each error prompt is played. The default value is true.

Notes: The order in which the prompts appear inside the ERROR_STRATEGY node defines the order in which they will be used. For example:
  • the main prompt says Please say a number.
    • prompt 1 for noinput says what was that again?
    • prompt 2 for noinput says I didn’t hear you.
    • prompt 3 for noinput says I’m having trouble hearing you.
  • the result of a caller remaining silent, would be:
    • Please say a number.
    • (listen for input)
    • What was that again? Please say a number.
    • (listen for input)
    • I didn’t hear you. Please say a number.
    • (listen for input)
    • I’m having trouble hearing you. Please say a number.
    • (listen for input)
  • if set reprompt to false:
    • Please say a number.
    • (listen for input)
    • What was that again?
    • (listen for input)
    • I didn’t hear you.
    • (listen for input)
    • I’m having trouble hearing you..
    • (listen for input)
GOTO

MESSAGE VOICEMAIL

Defines an automatic transition to another voice page without waiting for user input. None destination (required)—Defines the destination site and page code to follow. Define the destination as 123/456 where 123 represents the site number and 456 the page number.
INVALID

CREDITCARD CCEXP

Defines the destination to go to if the credit card number or expiration date are invalid. None destination (required)—Defines the destination site and page code to follow.
KEYWORD
RESPONSE Defines the keyword response type of a Question Page. Must have one or more LINK nodes. None
LINK

MESSAGE KEYWORD

Defines a group of page-level links for a Message Page. None keyword (optional)—Include a comma-separated set of keywords that callers can say to follow this link. The same rules that apply to keywords entered through Angel’s web interface apply to keywords here.

dtmf (optional)—Provide a keypad equivalent for this selection. Please ensure that no duplicate DTMF entries exist. Values 1-9 are accepted.
returnValue (optional)—In the case of a RESPONSE-associated link, the returnValue defines the string that will be submitted when this keyword is selected in a Question Page. Identical to the Save Value in Question Pages with keyword response type.
destination (required)—Defines the destination site and page code to follow. Define the destination as 123/456 where 123 represents the site number and 456 the page number.

MASTERCARD
CREDITCARD This type of credit card is accepted. None None
MESSAGE
ANGELXML Defines the structure of a Message Page. a COMMENT node

one PLAY node must have: zero or more LINK nodes or one ACTION node or one GOTO node one VARIABLES node zero or more ERROR_STRATEGY nodes

None
NO
YES_NO Defines the action to be taken if a user provides a No response to a Yes/No Question Page. None.

destination (required)—Defines the destination site and page code to follow. Define the destination as 123/456 where 123 represents the site number and 456 the page number.

Note: Must appear one time only.
NUMBER
RESPONSE Defines the response type of a Question Page.

one NUMBER node or one KEYWORD node or one YES_NO node.

numberType (required)—Defines the type of the number response. Valid entries are:
  • natural for Natural Number. This is the default value.
  • variable for Variable Length Digit Sequence.
  • range for a Digit Sequence within a digit range.
  • fixed for Fixed Length Digit Sequence. (this is deprecated, use range instead, with minNumberLength = maxNumberLength)

numberLength (optional)—If the numberType is defined as fixed, this attribute specifies the length of the digit string to solicit from the caller. The default value is 5.
minNumberLength (optional)—If the numberType is defined as range, this attribute specifies the minimum digit length of the digit string to solicit from the caller. For example, a value of 4 would indicate to the system to accept numbers starting at 1000. The default value is 1.
maxNumberLength (optional)—If the numberType is defined as range, this attribute specifies the maximum digit length of the digit string to solicit from the caller. For example, a value of 4 would indicate to the system to accept numbers no larger than 9999. The default value is 5.
destination (required)—Defines the destination site and page code to follow. Define the destination as 123/456 where 123 represents the site number and 456 the page number.

PLAY

MESSAGE QUESTION TRANSFER VOICEMAIL

Defines a group of prompts to be played. Must have one or more PROMPT nodes None
PROMPT
PLAY Defines a prompt for Angel to play for the caller. The prompt may be text for text-to-speech playback or a sound file. The text enclosed by the <PROMPT></PROMPT> tags is interpreted depending on the type attribute of the prompt. type (optional)—For text-to-speech playback, set this attribute to text. This is the default. The text enclosed in the node will be interpreted and validated as text to speech.

To play an audio file stored in your Angel.com account, set this attribute to audio. The correct format for the audio file reference in this case is /<folder>/<audiofilename>.wav.
To play an audio file on a remote server, set this attribute to externalaudio. The correct format for the audio file reference in this case is http://server_name/audiofilepath

PROPERTY
ASR_SETTINGS Defines an ASR Setting None name (required)—Defines the name of ASR settings.

Valid entries are:

  • confidencelevel: Define confidence level.
  • sensitivity: Define sensitivity.
  • speedvsaccuracy: Define speed vs accuracy.
  • completetimeout: Define complete timeout.
  • incompletetimeout: Define incomplete timeout.
  • interdigittimeout: Define inter digit timeout
  • timeout: Define timeout.
  • maxspeechtimeout: Define max speed timeout

value (required)—Defines the value of ASR settings, it should be a numeric String.

Note: interdigittimeout was added to AngelXML starting with CX Builder 15.5. Previously, this parameter was only supported through ASR Settings on the Question Page and the Transaction Page.

QUESTION
ANGELXML Defines the structure of a Question Page.

COMMENT node
one PLAY node
one RESPONSE node
zero or more ERROR_STRATEGY nodes
zero or one ASR_SETTINGS node

var (optional)—Sets a value for a variable. In applications where you are making more than one call to a Transaction Page, using variables that have been previously returned by AngelXML. Select the checkbox Submit all Variables defined in any AngelXML document.
RESPONSE
QUESTION Defines the response type of a Question Page. Must have:

either one NUMBER node or one KEYWORD node or one YES_NO node or CREDITCARD node or one CCEXP node or one CURRENCY node or one DATE node or one TIME node

confirm (optional)—Determines whether the system should confirm with the caller the response that the system understood. Acceptable values are true for confirmation on and false for confirmation off. The default value is false. Confirmation is available for NUMBER, KEYWORD, CREDITCARD, CCEXP, CURRENCY, DATE and TIME. In the case of NUMBER, KEYWORD, CURRENCY, DATE and TIME, confirmation on will confirm only when the response is ambiguous, and confirmation off will never confirm. In the case of CREDITCARD and CCEXP, confirmation on will always confirm, and confirmation off will only confirm if the response is ambiguous.
Note: Additionally, for time responses, turning confirmation on also turns on disambiguation of AM/PM for responses which could mean either.
TIME
RESPONSE Defines the current Question Page as a Time Question Page. None destination (required)—Defines the destination site and page code to follow. Define the destination as 123/456 where 123 represents the site number and 456 the page number.
Notes: When using time Question Pages, the following responses are accepted from the caller:
  • Hour Minutes AM/PM
  • Hour o’clock AM/PM
  • Noon
  • Midnight

Callers can also enter the response using an five-digit string such as HHMMX where X is 1 for AM and 2 for PM.

TRANSFER
ANGELXML Defines the structure of a Call Transfer Page.

a COMMENT node
one PLAY node
zero or more ERROR_STRATEGY nodes

destination (required)— Defines the phone number to dial. Please enter a 10 digit string representing a valid US non-premium number. Toll free numbers are also accepted.

rings (optional)—Defines the number of rings to wait before giving up trying. The default is 4.

if_fail (optional)—Defines the destination site and page code to follow if the call fails to complete. Define the destination as 123/456 where 123 represents the site number and 456 the page number. Reasons for failing to complete a call:

  • line is busy
  • no response

if_completed (required)—Defines the destination site and page code to follow if the call completes successfully. Define the destination as 123/456 where 123 represents the site number and 456 the page number.

out_caller_id (optional)—If you want to identify calls as coming from Angel instead of as coming from specific callers, specify the last four digits you wish to see appear on the outgoing Caller ID. For example, if you specify 1234, the Caller ID will appear as (000) 000 – 1234. If this attribute is not specified, the value passed on is the Caller ID of the incoming call, if available.

Note: The if_fail and if_completed attributes have a special destination value of hangup which can be used to instruct the system to hang up if the condition for which it is specified is met. hangup is the default value for if_fail.
VALID

CREDITCARD CCEXP

Defines the destination to go to if the credit card number or expiration date are valid. None destination (required)—Defines the destination site and page code to follow.
VAR
VARIABLES Defines the assignment to the variables. The variable should be initialized in Site Variables in order to be used. None

name (required)—Defines the name of the variable to be assigned a value. type (optional)—Defines the type of the variable. Valid entries are:

  • scaler: Holds one value. This is the default value.
  • list: Holds multiple values.

value (optional—Defines the value to be assigned to the variable.
separator (optional)—Defines the delimiter for list type variable. The default value is , (comma).

Note: A scalar type always loses its current value when assigned a new one. For example, when a caller answers the same question twice in the same call, if the value is a scalar the variable will hold the second answer. A list always appends new values to the end separated by the separator value.
VARIABLES
ANGELXML Defines the structure of variable assignment. one or more VAR nodes None
VOICEMAIL
ANGELXML Defines the structure of a Voicemail Page. a COMMENT node

one PLAY node
one ACTION node
or one GOTO node
zero or more ERROR_STRATEGY nodes

mailbox (required}—Defines the name of the mailbox where the caller’s message will be recorded. Enter a String matching the mailbox name where you would like the message deposited.
confirm (optional)—Determines whether the system should confirm with the caller the recording that the system took from the caller. This allows the caller to hear and re-record the response again. Acceptable values are true for confirmation on and false for confirmation off. The default value is false.
finalSilence (optional)—Determines how many seconds of silence to wait before determining that the caller wishes to end the recording. The default value is 3.5 secs. A recording can always be completed by pressing a key.
Var (optional)—Defines the name of the variable that will hold the URL of the message.

VISA
CREDITCARD This type of credit card is accepted. None None
YES
YES_NO Defines the action to be taken if a user provides a Yes response to a Yes/No Question Page. None

destination (required)—Defines the destination site and page code to follow. Define the destination as 123/456 where 123 represents the site number and 456 the page number.

Note: Must appear one time only.
YES_NO
RESPONSE Defines the Yes/No response type of a Question Page. one or more LINK nodes None


Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on 13 May 2016, at 13:07.