Variables Reference

VoiceXML variables and ECMAScript variables share the same variable space. In other words, variables declared in a <script> element can be used in VoiceXML, and ECMAScript can use variables declared by a <var> element. There are 3 ways that variables can be declared:

Declared by a <var> element
Declared within the <script> element in an ECMAScript block
Field item variables declared by one of form items: <block>, <field>, <initial>, <object>, <record>, <subdialog>, and <transfer>

Scope

VoiceXML defines the following variable scopes:

Session - session variables are available to all VoiceXML applications within a particular session. They are declared by the interpreter and are read-only. New session variables cannot be declared by VoiceXML documents.
Application - application variables are available to the root document and its application leaf documents. They are declared by the <var> elements of the application root document's <vxml> element.
Document - document variables are available within the VoiceXML document. They are declared by the <var> elements that are children of the <vxml> element. Certain form items (<field>, <record>, <transfer>) may declare shadow variables in addition to the field item variable itself; please refer to each tag reference for detailed information.
Dialog - each dialog (<form> or <menu>) has a dialog scope that exists while the user is visiting the dialog. Variables are declared by <var> elements or by form items.
(Anonymous) - <block>, <filled>, and <catch> (includes <error>, <help>, <noinput>, and <nomatch>) elements defines a new anonymous scope to contain variables declared in that element. Other predefined anonymous variables are available within the <catch> and <enumerate> elements; please refer to the tag reference for detailed information.

Session Variables

VoiceXML Session Variables

The following are the currently or previously standard VoiceXML session variables. All "telephone" variables continue to be supported. Note that although a certain variable may be supported, it will only be set if it has been enabled during platform configuration.

Variable	Description
session.telephone.ani	Automatic Number Identification (Calling Party Number). Provides the telephone number of the caller if the service is supported. Mapped to the SIP `From:` header.
session.telephone.dnis	Dialed Number Identification Service (Called Party Number). Provides the telephone number dialed by the caller if the service is supported. Mapped to the SIP `To:` header.
session.connection.local.uri	Set to the SIP-Request URI passed by SIPD in starting the session for an incoming call and set to the SIP From URI sent to UAD when making an outbound call. The value remains URL-encoded and thus is the exact text that appears in the SIPD PDU. If UAD does not accept a From URI, then this value will be set to ECMAScript undefined. This is identical to session.connection.protocol.sip.uri. Represents a URI of an IP Media Server platform. This is equivalent to `session.telephone.dnis` if the caller calls into the IP Media Server platform, and is equivalent to `session.telephone.ani` if the IP Media Server platform makes an outbound call to a remote caller device.
session.connection.remote.uri	Set to the SIP From URI passed by SIPD in starting the session for an incoming call and set to the SIP Request-URI passed to UAD when initiating an outbound call. The value remains URL-encoded and thus is the exact text that appears in the SIPD PDU. This is identical to session.connection.protocol.sip.from. Represents a URI of the remote caller device. This is equivalent to `session.telephone.ani` if the caller calls into the IP Media Server platform, and is equivalent to `session.telephone.dnis` if the IP Media Server platform makes an outbound call to a remote caller device.
session.connection.protocol.name	Represents the name of the underlying connection protocol.
session.connection.protocol.version	Represents the version of the connection protocol. Not currently supported.
session.connection.protocol.<name>	When `session.connection.protocol.name` is available, this variable is a member of the `session.connection.protocol` object, with the <name> specified by `session.connection.protocol.name`. In standards compliance mode, if the protocol <name> is available, this variable is always set to an ECMAScript object (although it may or may not have properties, depending on the protocol being used). If the `com.voicegenie.STRICTCONFORMANCE` property is set to `FALSE`, this variable is not always defined, depending on the protocol being used.
session.connection.redirect	An array representing the connection redirection path. The first element is the original called number; the last element is the last redirect number. Each element of the array contains a uri, pi (presentation information), si (screening information), and reason property. The reason property can be either "unknown", "user busy", "no reply", "deflect during alerting", "deflection immediate response", or "mobile subscriber not reachable". Not currently supported.
session.connection.originator	Represents the originator device. It is equal to either `session.connection.local.uri` or `session.connection.remote.uri`. Note that if the local.uri and/or remote.uri variables have not been enabled, the originator variable (if it has been enabled) will be undefined.
session.connection.media	An array where each element represents an RTP media stream. Each array element has the following associated attributes: “type” – indicates the MIME type of media stream (currently either “audio” or “video”). “subtype” – indicates the MIME sub-type, or encoding, of the media stream (e.g. PCMU, PCMA, H264, etc.). The names and values of these attributes are taken from RFC 3555 “MIME Type Registration of RTP Payload Formats.” As an example consider the following session variables: session.connection.media[0].type=”audio” session.connection.media[0].subtype=”PCMU” session.connection.media[1].type=”video” session.connection.media[1].subtype=”H263” These indicate that the media server and endpoint have agreed on G.711 for audio and H.264 for video. (Note: ECMAscript arrays have a built-in length property that can be used to determine the number of elements. Using the above array definition, “session.connection.media.length” would return the value 2.)

^†Note: See Call-Related Variables for details on the naming conventions.

The VoiceXML 2.0 specification also defines the session.connection.protocol session variable whose members give additional information about the underlying protocol:

session.connection.protocol.sip.uri	Represents the originator device. It is equal to either session.connection.local.uri or session.connection.remote.uri. Note that if the local.uri and/or remote.uri variables have not been enabled, the originator variable (if it has been enabled) will be undefined.
session.connection.protocol.sip.from	Set to the SIP From URI of the corresponding SIP session. The value remains URL-encoded and thus is the exact text that appears in the SIPD PDU.
session.connection.protocol.sip.to	Set to the SIP To URI of the corresponding SIP session. The value remains URL-encoded and thus is the exact text that appears in the SIPD PDU.
session.connection.protocol.sip.call_id	Set to the SIP Call-ID of the corresponding SIP session. The value remains URL-encoded and thus is the exact text that appears in the SIPD PDU.
session.connection.protocol.sip.parameter	This is an ordinal array that reflects the names and values of SIP Request-URI parameters received from SIPD when a call is set up. Each item in the array is an ECMAScript object with two members, “name” and “value”. For instance, a SIP Request-URI of sip:1234@mediaserver.com;abc=1234 would have session.connection.protocol.sip.parameter[0].name = “abc” and session.connection.protocol.sip.parameter[0].value = ‘1234’. Both the parameter names and values presented are URL-decoded.

Application Variables

Application variables defined in the root document can be referenced by the application leaf documents as application.variable.

The application.lastresult$ shadow variable can be modified by a VoiceXML application.
When any shadow variable is not set, its value will be ECMAScript undefined.

The following are supported VoiceXML application variables:

Variable	Description
application.lastresult$	This read-only variable holds information about the last recognition to occur within this application. It is an array of elements application.lastresult$[i] for the N-best recognition.
application.lastresult$[i].confidence	The confidence level for this result from 0.0 (minimum confidence) to 1.0 (maximum confidence). It is an ECMAScript number.
application.lastresult$[i].utterance	The raw string of words that were recognized for this result. `fieldname$.utterance`, `lastresult$.utterance`, and `lastresult$[0].utterance` will all be identical and contain the utterance with the best confidence score. `lastresult$[i].utterance`, where `i`>0 and `i`<`maxnbest`-1, will each contain the utterance for the `i`th result. Limitation: Currently, only `lastresult$[0].utterance` will be set; any other elements in the lastresult array (i.e. `lastresult$[i].utterance`, for `i`>0 and `i`<`maxnbest`), will be `undefined`. This limitation applies to all ASR engines except SpeechWorks ASR.
application.lastresult$[i].inputmode	The mode in which user input was provided: dtmf or voice.
application.lastresult$[i].interpretation	The interpretation of this result (set of slot names and values). This interpretation can be formatted either as an ECMAScript object, or as a string. The choice of format depends on the value of the com.voicegenie.fieldobject property. Note that when `application.lastresult$.interpretation` is set as an object as a result of semantic interpretation, it is not set to the same object as `application.lastresult$[0].interpretation`. They are set as individual objects (the W3C specification does not explicitly state whether they should be the same object or not) with members with the same values.
application.lastresult$[i].markname	(VoiceXML 2.1 feature) The name of the mark last executed by the SSML processor before barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. For more details, see `<mark>`.
application.lastresult$[i].marktime	(VoiceXML 2.1 feature) The number of milliseconds that elapsed since the last mark was executed by the SSML processor, until barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. For more details, see `<mark>`.
application.lastresult$[i].recording	(VoiceXML 2.1 feature) This variable stores a reference to the recording, or undefined if no audio is collected (like `application.lastresult$[i].utteranceaudio`). This shadow variable is only set if the `recordutterance` property is set to true.
application.lastresult$[i].recordingsize	(VoiceXML 2.1 feature) This variable stores the size of the recording in bytes, or undefined if no audio is collected (like `application.lastresult$[i].size`). This shadow variable is only set if the `recordutterance` property is set to true.
application.lastresult$[i].recordingduration	(VoiceXML 2.1 feature) This variable stores the duration of the recording in milliseconds, or undefined if no audio is collected (like `application.lastresult$[i].duration`). This shadow variable is only set if the `recordutterance` property is set to true.
application.lastresult$[i].rawresults	Complete results from ASR in the format of: +[?][slot1:]value1[:score1]+ [?][slot2:]value2[:score2]+... Where ? implies ambiguous match, and optional parts are quoted in [ and ].
application.lastresult$.activegrammars[]	An array containing all the grammar objects that were active at the time of the recognition. This will contain a valid value whenever voice input is recognized. For now, DTMF input will not result in this variable being set to a meaningful value.
application.lastresult$.audiooffset	Offset of audio data on bargein (-1 if audio was played to the end). Undefined if last played prompt was not <audio>. It is an ECMAScript number.
application.lastresult$.bargein	This is true if bargein occurred, false otherwise. It is an ECMAScript boolean.
application.lastresult$.bargeinresult	The recognized result (phrase\|score) returned by ASR upon barge-in. This is only meaningful with certain ASR engines that use special notation in their grammars to allow portions of utterances to trigger bargein. Otherwise, this is only filled if recognition-based bargein is used, in which case it will have the same values as the recognition result and confidence level.
application.lastresult$.duration	If utterance audio is created for the last recognition result, this variable will contain the duration of the utterance audio in seconds (like `application.lastresult$[i].recordingduration`). This shadow variable is only set if the `com.voicegenie.saveutterance` property is set to true.
application.lastresult$.info	ASR recognition result parameters, such as how much time was used to do recognition, from the 'info' portion of the ASR result. (Available with Watson ASR only)
application.lastresult$.interpretation.SWI_literalTimings	Makes special OSR variable, SWI_literalTimings, accessible in the VoiceXML page. See SWI_literalTimings for more details. (Available with SpeechWorks ASR only)
application.lastresult$.size	If utterance audio is created for the last recognition result, this variable will contain the size of the utterance audio in bytes (like `application.lastresult$[i].recordingsize`). This shadow variable is only set if the `com.voicegenie.saveutterance` property is set to true.
application.lastresult$.triggeredgrammar	The matched result's grammar object. This will contain a valid value any time voice input is recognized. For now, DTMF input will not result in this variable being set to a meaningful value. Note that this variable will be `undefined` in the case of a nomatch event or a timeout.
application.lastresult$.utteranceaudio	Audio file of the user utterance (like `application.lastresult$[i].recording`). This shadow variable is only set if the `com.voicegenie.saveutterance` property is set to true. This is always assigned an utterance filename (as long as saving utterances is enabled and the inputmodes property is set to either "voice" or "both"). This filename is passed to the ASR engine to create the utterance audio file. However, currently only Watson creates an utterance audio file in the events of noinput, DTMF match, or call disconnect. With other ASR engines, reference to the utteranceaudio shadow variable in those cases (where no audio file is created) will result in a bad fetch error. (However, the application.lastresult$.utteranceaudio will not be set at all, i.e. will be undefined, in the event of a noinput if the com.voicegenie.strictconformance property is set to true.)