| CallXML 3.0 Development Guide | Home | Frameset Home |
| cache | Data Type: (yes|no) | Default: none - attribute is optional |
| Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all. | ||
| choices | Data Type: (grammar value) | Default: Optional |
The 'choices' attribute defines a list of comma delimited voice recognition utterances that will be active for the container element. Alternatively, the attribute can contain a choice followed parantheses containing different words which equate to that choice. Note that both dtmf grammars, and spoken word grammar utterances can be defined; digit values always indicate dtmf input, whereas spelled 'literals' for numbers imply that the grammar must be spoken:One can also define multiple matches to return the same value to the application by specifying the values in the following format: <ContainerElementName choices="ReturnValue (subchoice1, subchoice2)">As such, either of the 'subchoice' utterances will be interpreted as 'ReturnValue'. To illustrate in greater detail: <say choices="Beatles (john, paul, ringo, george), Lastly, developers can also make use of a builtin number grammar for capturing a string of digit values by specifying [x DIGITS], where 'x' is the length of the string that you wish to collect: <block choices="[5 DIGITS]"> This can also be modified to accept input of varying lengths by specifying [x-y DIGITS], where 'x' and 'y' are the minimum and maximum values for the length of the string being collected: <block choices="[5-8 DIGITS]"> | ||
| cleardigits | Data Type: (true|false) | Default: none - attribute is optional |
| This attribute's value is a Boolean, indicating whether the queued digits buffer should be cleared when this action starts. "true" clears the digits buffer; "false" leaves the contents of the digit buffer alone. | ||
| format | Data Type: URI | Default: none - attribute is optional |
| The 'format' attribute defines the string formatting to use for the element. If the value is undefined, the audio file format should be determined from the file name extension, if possible, and, if necessary, override the default format. | ||
| id | Data Type: (element id) | Default: none - attribute is optional |
The new 'id' attribute in CallXML3.0 is applicable to all container and action elements. Specifying this attribute allows yet another level of control and event handling when events occur and are caught by the <on> element. When an event occurs, the handler will first check the event, and then verify that the handler has a handler specific to the 'id' attribute to execute. This allows the developer to plan a specific course of action for events based on where in the application that they occur. | ||
| say | Data Type: STRING | Default: none - attribute is optional |
| The 'say' attribute allows the developer to specify backup TTS to be output in the event that the .wav file cannot be found. | ||
| test | Data Type: CDATA | Default: Optional |
| The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document. | ||
| value | Data Type: URI | Default: none - attribute is required |
| The 'value' attribute defines the audio file to play to the caller when the parent element is first entered. | ||
| value-is | Data Type: STRING | Default: none - attribute is optional |
| Another new attribute, 'value-is', grants the developer with the ability to perform conditional logic upon container elements, or action elements for the first time within the CallXML markup. The value specified in the 'value-is' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is' equate to 'true', then the element specified will execute. If the value equates to 'false' then the element will be skipped during document execution. | ||
| value-is-not | Data Type: STRING | Default: none - attribute is optional |
| Another new attribute, 'value-is-not', grants the developer with the ability to perform conditional logic upon container elements, or action elements, for the first time within the CallXML markup. The value specified in the 'value-is-not' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is-not' equate to 'false', then the element specified will execute. If the value equates to 'true' then the element will be skipped during document execution. | ||
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <do repeat="5"> <playaudio value="feelgood.wav" choices="#" cache="no" format="audio/wav"/> <on event="choice:#"> <prompt value="so, you dont like James Brown then"/> </on> </do> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <do repeat="3"> <prompt> Listen to the self-help assertations from James Brown, and press one when you feel as if you have achieved a higher conciousness. </prompt> <!-- this will not play --> <playaudio value="1feelgood.wav" say="1 Hoowah! I feel good!" choices="1" id="JB1" test="'JBrown' = 'OWinfrey'"/> <!-- this will play --> <playaudio value="1feelgood.wav" say="2 Hoowah! I feel good!" choices="1" id="JB2" test="JBrown"/> <!-- this will play --> <playaudio value="1feelgood.wav" say="3 Hoowah! I feel good!" choices="1" id="JB3" test="1=1"/> <!-- this will not play --> <playaudio value="1feelgood.wav" say="4 Hoowah! I feel kind of sick!" choices="1" id="JB4" test="1!=1"/> <!-- this will play --> <playaudio value="1feelgood.wav" say="5 Hoowah! I feel good!" choices="1" id="JB5" test="1!=2"/> <on value="choice=1" target="JB1"> <prompt value="there is no way that this can happen"/> </on> <on value="choice=1" target="JB2"> <prompt value="The path of enlightenment is achieved through feeling good"/> </on> <on value="choice=1" target="JB3"> <prompt value="The path of enlightenment is achieved through feeling good. You knew that you would, now"/> </on> <on value="choice=1" target="JB4"> <prompt value="there is no way that this can happen"/> </on> <on value="choice=1" target="JB5"> <prompt value="The path of enlightenment is achieved through copious amounts of money and gullibility, if you happen to be a scientologist"/> </on> </do> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <do value="JamesBrown"> <!-- this will play --> <playaudio value="feelgood.wav" say="Hoowah! I feel good!" value-is="JamesBrown"/> <!-- this will NOT play --> <playaudio value="feelgood.wav" say="Ugh, I dont feel good! Please pass the Imodium AD." value-is="GodfatherOfSoul"/> <!-- this will play --> <playaudio value="feelgood.wav" say="Hoowah! I feel good!" value-is-not="GodfatherOfSoul"/> <!-- this will NOT play --> <playaudio value="feelgood.wav" say="Blurk! I dont feel good. Must have been something I ate" value-is-not="JamesBrown"/> </do> </callxml> |
| ANNOTATIONS: EXISTING POSTS |
jpw
|
|
| huh? what's this:
<on value="choice=1" target="JB3"> what is "value=" ? It's NOT in the <on> docs! |
|
voxeojeff
|
|
| Hello,
This is a typo in the documentation. It should read: <on event="choice:1" target="JB3"> It will be corrected in the next documentation update. Regards, Jeff |
|
jpw
|
|
| how about an example of using termdigits, too please? The purpose of that presumably is just to let the user stop playing the audio, right? | |
VoxeoDante
|
|
| Hello JPW,
I believe you would be looking for something like this. <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <do repeat="5"> <playaudio value="Hello.wav" cache="no" termdigits="5" format="audio/wav"/> <on event="termdigit:5"> <prompt value="you have decided to end the current action"/> <exit/> </on> </do> </callxml> The purpose of the termdigit is to allow the caller / callee to end the current action. In this case it would allow them to end the playback of the audio file, and exit the application. Remember that any termdigit specified should always have an associated <on event="termdigit:"> event to handle the action. I hope this is what you were looking for. Regards, Danté Vitulano |
|
jpw
|
|
| useful note: playaudio throws an error if the url is unavailable, so you better trap it unless your are 100% certain the url exists.
<playaudio value="$mywavurl;" /> <on event="error"> <say>cannot access the audio file</say> </on> IMO that's a bug and it ought to gracefully continue execution, or at least there ought to be an ignoreerrors attribute. But, if throwing an error is the way it has to be (as it is now) then it would nice if the offending missing url was available in some variable, since you might have 10 <playaudio> and it would be nice to have 1 error handler for all of the them. Another reason it's a bug IMO to always throw an error is that a missing audio file should not kill execution of the rest of the block you are in, but when the error is thrown, you're out of luck continuing execution... that block is done. This makes for 'fragile' applications. |
|
VoxeoDustin
|
|
| Hey JP,
This functionality is by design. A failed fetch is an error and we definitely want the browser to throw one, and it's always a best practice to have error handlers in our code. Fortunately, this particular error isn't fatal, so we can continue call flow after it. Here's a little sample code of how to do that: [code] <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <do label="B1"> <say choices="1"> Press one now. </say> <getdigits var="Var_1" maxtime="3s"/> <on event="choice:1" next="#B2"> <playaudio value="http://myserver.com/mywav.wav" /> <on event="error"> <log value="contains('foobar', 'foo')"/> <log value="$session.lasterror;"/> <if test="contains('$session.lasterror;', 'Server')"> <say>Backup TTS!</say> </if> </on> </on> <do label="B2"> <say>Block 2!</say> </do> <on event="nomatch"> <prompt value="That isn't a valid selection"/> </on> <on event="maxtime"> <prompt value="you didn't press anything"/> </on> <on event="hangup"> <log> *** USER HUNG UP ***</log> </on> </do> <on event="error"> <log>******* GLOBAL ERROR HANDLER *******</log> <log value="$session.lasterror;"/> <!-- this will only happen if we don't specify a locally scoped error handler --> </on> </callxml> [/code] Thanks, Dustin |
|
jpw
|
|
| in another thread on the forum I reported a bug in the 'test=' for <playaudio> (maybe everywhere else that uses test=):
the docs say if the test= condition is not true it skips to the next container, but in the case of <playaudio> that's not true... it STILL evaluates the value= parameters, and if it's empty for example it throws an error. in other words <playaudio value="$myurl;" test="'$urlpresent;' = 'true'"/> if $urlpresent=false then it should not matter what is in $myurl, because the container is supposed to be skipped, but in fact if $myurl is empty it throws an error. This makes no sense since a program clearly ought to be able to have <playaudio> statements that may not be executed in certain cases (like there's no data to play at the moment!). There's an easy workaround (put the playaudio inside an <if test= ... > block instead of using test= in the <playaudio>), but it's a bug nonetheless |
|
VoxeoDustin
|
|
| Hey JP,
Since we're setting the variable to false, we don't need an expression to to evaluate it with test. This should do the trick for you. [code] <assign var="urlpresent" value="false"/> <playaudio value="http://myserver.com/mywav.wav" test="'$urlpresent;'" />[/code] Note: We don't need single quotes around "false" when assigning the var, but we do need it around test="'$urlpresent;'" because we're evaluating it with Xpath. Hope this helps, Dustin |
|
jpw
|
|
| the bug (confirmed in the forums) is that if your url is empty or bad -- a variable, for example, not hard-coded like your example -- it crashes the system because it evaluates the value= even though the test condition is false so it shouldn't. | |
jpw
|
|
| Does this element playaudio use choices, termdigits, or both? Docs on this page say both but I think I read in a forum that's not true it can be ONLY one or the other? | |
MattHenry
|
|
|
Hi JP, I think that you came across some errata in our docs, (which has been fixed internally). When using CXML 3.0, folks should stick to using 'choices' as opposed to the older 'termdigits' syntax. Cheers, ~Matthew Henry |
|
jpw
|
|
| How about SOME kind of list showing the valid "format" values? Like, for example, VOX. | |
voxeojeff
|
|
| Hi Pardner,
As it stands right now, allowable values for the "format" attribute are: - audio/wav - audio/vox Hope this helps, Jeff |
|
zoop
|
|
| I have seen from my callxml that I can use the termdigits option on the playaudio tag. I'm wondering why it isn't documented here. If that is because it's suppose to be replaced by chocies the is there a way to have <on event="chocie:123456789>....</on> so that I can match all numbers or do I really have to create one on event for each number to match it?
Thanks -Zoop |
|
voxeoJeffK
|
|
| Hi Zoop,
It would be best to stick with "choices" rather than "termdigits". You are free to use a generic <on> handler for choice. If you want to match any, but only one of the numbers it might be easier to use the DIGITS grammar of the <block> tag. Here's an example: <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <block choices="[1 DIGITS]"> <playaudio value="Pulse.wav"/> <on event="choice"> <say> You entered </say> <playnumber format="digits" value="$session.lastchoice;"/> </on> </block> </callxml> hope that helps Jeff K. |
| login |