Input

Overview

The Input object is a configurable dialog component that plays an Output to request information from the caller and assigns the caller’s input to one or more Variable or Layer objects. The input can be either DTMF or recognized voice input in the voice and video channel, or text in the text and Web channel.

The Object Definition below covers the configuration of the Input object with VoiceObjects Desktop. For information on how to define this object type using VoiceObjectsXML, refer to the VoiceObjectsXML Definition paragraph.

The Input object belongs to the object category Components.

Dialog Flow Scenario

The first dialog flow example describes a simple input dialog requesting a phone number.

Object – Caller	Dialog Flow
	Please say your 10-digit phone number, or enter it using your telephone keypad.
Caller	703 432 7564

The second dialog flow example is taken from a flight booking application.

Object – Caller	Dialog Flow
	Would you like arrival or departure information?
Caller	Departure

The third dialog flow example is taken from the same flight booking application, and shows a single input for multiple information items (origin and destination of a flight).

Object – Caller	Dialog Flow
	From where to where would you like to travel?
Caller	I want to fly from San Francisco to New York City.

Object Definition

The Definition of the Input object provides the following sections:

· Input Request
To specify the outputs that ask the caller for input.

· Grammar
To define the inputs to be accepted.

· Result Handling
To specify where to store the caller input.

· Options
To configure processing options.

For further details regarding additional object configuration refer to Pre-/Postprocessing, Event Handling, Navigation, Tuning, and Properties in this Object Reference.

Input Request

The Input Request holds an embedded Output object and is used to ask the caller for the required input specified in the Initial section, as well as to define modified outputs for event cases in the Event Reprompt section (which is only processed in the voice and video channel). The output can be defined by entering plain text or by linking any combination of text, Output, Variable, Collection, Expression, Layer, Script, Audio, Video, and Silence objects. In the voice and video channel, plain text will by synthesized by the TTS engine of the media platform (if available). In the text and Web channel, the text will be displayed on the screen of the mobile device.

For further details refer to the Output object in this Object Reference.

For a detailed description of how to use the reprompting mechanism, refer to Chapter 8 – Advanced Event Handling in the Design Guide.

Grammar

The Grammar section defines the grammar specifying the utterances that can be recognized as input. In the voice and video channel, the grammar can define voice and/or DTMF utterances and is interpreted by the speech and DTMF recognition engines of the media platform. In the text and Web channel, the grammar can be used to reduce the possible text input to a short list of alternatives.

@8 Tip: To develop dynamic speech or DTMF grammars effectively you can use a grammar tool like NuGram IDE, which provides a complete set of Eclipse tools to author, test, and debug speech or DTMF recognition grammars. For further details and a free download refer to the Nu Echo Website (www.grammarserver.com) or the VoiceObjects Developer Portal (http://developers.voiceobjects.com/partners/).

8 Caution: At least one Grammar item must be defined in this section to get a valid Input object definition. If no grammar is defined at all, or all Grammar items are disabled at call time due to layer evaluation, the Input object will not work.

In the example above, possible inputs are arrival information and departure information.

In the voice and video channel, the grammar can be implemented through an embedded definition or an external file, or be dynamically generated at call time. The grammar format that needs to be used depends on the requirements of the media platform. The example here uses the VoiceObjects text-to-grammar (TTG) format, which is translated into a real grammar by the server at call time.

8 Caution: Some media platforms do not support slot assignments in DTMF grammars. These platforms always return the DTMF keys pressed, but no semantic interpretation. If you use TTG for DTMF grammars, this will be handled by the server, i.e. in this case slot assignments will work as usual. If you use external, or inline but non-TTG grammars, you need to be aware of this restriction. See Appendix A – Media Platform Drivers in the Deployment Guide to find out how your media platform handles this.

In the text and Web channel, the grammar must be defined as a TTG grammar in the Voice/Text section of the Grammar object. A TTG grammar can also be generated dynamically at call time, though. If more than one Grammar item is active at call time, only the first one will be interpreted.
Grammars are typically used in these channels to reduce the possible text input to a short list of alternatives. If the number of utterances defined in the TTG grammar is small enough, it is best practice to display the grammar as a set of alternatives, so that the caller can simply choose a predefined entry instead of typing it in. If the TTG grammar defines utterances and explicit slot values, the utterances are being displayed. The server applies a default selection of presentation style if no value for the tuning parameter Presentation – Input (see below) is defined. By default, if the number of utterances is >= 1 and <=5, the server shows the grammar as a menu of labeled items in the text channel, or a list of hyperlinks in the Web channel for single-slot Input objects. In case of a multi-slot Input object in the Web channel, the grammar is shown as radio buttons by default. If it is >= 6 and <= 20, the grammar is also shown as a menu of labeled items in the text channel but as a drop-down list in the Web channel. If it is above 20, the grammar is not displayed; instead the callers must type their answer manually. In this case, the server maps the caller’s response to the slot values defined in the TTG grammar (if any) if the response matches one of the utterances of the grammar. If not, the response itself is used as the slot value. (Note that the mapping of utterances to slot values is case-sensitive). If you do not want to rely on this automatic decision of how to show the grammar, use the tuning parameter Presentation – Input to customize the behavior. This parameter can be set to one of text (for text fields), password (for text fields in password mode), menu (for a list of hyperlinks), list (for drop-down lists), or radio (for radio buttons) in the Web channel, and to text (for free text input) or menu (for a list of options) in the text channel. In case of multi-slot Input objects in the Web channel, a special notation allows the definition of an input presentation style per slot. This is described in the section on Result Handling.

In the Web channel, the number of characters to be entered in a text or password field can be limited. Use the tuning parameter Presentation – Input Maximum Length to define this limit, either for all slots, or on a per-slot basis. To define the length per slot, the value of the parameter must be a comma-separated list of numbers with slot names in parentheses. Example: If you want to limit the length for the slot named Age to 3 and that of a slot PIN to 5, define this: 3(Age), 5 (PIN). This can be defined in a Module object and inherited by Input objects, or defined locally. Note that a new definition of this parameter always overwrites all of an inherited value.

i8 Note: The text and Web channels, as opposed to voice and video, allow free input of text, since no recognition needs to take place (which only works on predefined grammars). This means that the Input object conceptually does not require a grammar to be defined. But since a grammar must be defined to create a valid Input object, use the question mark symbol “?” as the TTG definition to tell the server that free input is allowed. In this case, any response coming back from the caller will be used as the slot value.

For further details on the Grammar object refer to the section on Grammar in this Object Reference.

For more information on the distinction between voice and DTMF grammars and on the system layer input mode, which can influence both prompt and grammar selection, refer to Chapter 9 – How to Use Different Input Modes in the Design Guide.

@8 Tip: For the ability to validate free-form utterances in the text and Web channel, refer to the section Utterance Validation in the description of the Grammar object.

Result Handling

In the Result Handling section, Result Handling Items are defined that assign grammar slot values to Variable or Layer objects.

8 Caution: At least one Result Handling Item must be defined. An empty result handling definition results in an invalid Input object that cannot be processed correctly by the server.

In voice and video applications, slots are the standard mechanism used in speech recognition grammars to return what is often called the semantic interpretation or representation of the caller input.

In many cases, callers have a variety of options to say essentially the same thing. In response to a question “Is this correct?” the caller might say “Yes, that is correct”, “Sure”, “Yeah, that’s right”, etc. All of these mean the same thing, namely yes. Thus it makes sense to map all of them to a single representation that can then be interpreted by the rest of the dialog flow. Slots provide exactly these representations. Different grammar formats define slots in different ways. For further details refer to the Grammar object in this Object Reference.

In addition to the slot value the grammar can define a pronunciation value. This value is meant to instruct the server to use either the same intonation or rhythm that the caller used or the same synonyms, in case the application reads back the input to the caller. This only applies to Variable objects, so pronunciation values cannot be set for Layer objects. The pronunciation pattern can be attached to the slot value by separating it from the actual value using the double-pipe symbol “||”. If no such pattern is defined, the variable’s pronunciation value will be empty. In addition, the pronunciation value is set to the empty string whenever the Variable object is part of an operation that changes its actual value, e.g. through the use of Expression objects. The pronunciation value will automatically be used as the value to format in case a Format object is applied that uses one of the predefined TTA types. In case of a custom formatting algorithm, see Appendix B – How to Use the Formatting Bus in the Administration Guide.
As an example, consider an Input object with a slot named sltPhone that asks for the caller’s phone number. If the caller speaks the number in groups of 2 digits, the grammar can assign this grouping to the pronunciation value of sltPhone. If the caller for instance says “twenty-two, sixty-three, fourty-four”, the value of the sltPhone slot could be 226344||22 63 44. The part before the double-pipe symbol will become the actual variable value, whereas the part thereafter will become the pronunciation value. When reading back this number in a later output and applying the formatting type TTA – Words/Numbers to the Variable object, the system would read back the number in the same way, achieving an increased intelligibility towards the caller.
For more information on the pronunciation value of a Variable object, refer to Variable and Format in this Object Reference.

The Input object fully supports both single-slot and multi-slot inputs. In single-slot inputs, callers are asked for exactly one information item as in “From which airport do you want to travel?” In multi-slot inputs, callers can provide multiple information items in a single utterance, e.g. the origin and destination airport in “I want to fly from San Francisco to Boston”. The corresponding slot values (e.g. SFO for San Francisco and BOS for Boston) are then filled into the variables specified in the Result Handling of the Input object.

i8 Note: Spaces in slot values are trimmed, and space clusters (more than one space character) are reduced to one space character.

If a certain slot is not filled in the grammar by the caller’s utterance (e.g. the caller said “I want to fly to Boston” only), the variables corresponding to the undefined slots are filled with an empty string. During the dialog flow you can check for this e.g. by using the ISNULL() function provided within the Expression object (or alternatively by just using the variable itself as a precondition; see the Variable object for a description of how variable values are interpreted as Boolean conditions). This enables you to easily build dialogs that allow callers to provide as much information at a time as they want, and that dynamically and elegantly ask for any missing information.

i8 Note: Multi-slot inputs are not supported in the text channel. Any additional slot definition but the first one will be ignored in this channel. In the Web channel, however, multiple slots are displayed as multiple input fields. The style chosen for each slot (text, menu, or radio) depends on the number of utterances defined in the grammar for that slot, which is described in the section on Grammar. Using the tuning parameter Presentation – Input, an explicit presentation style can be defined per slot, overriding the automatic style selection applied by the server. To define a style per slot, the value of the parameter must be a comma-separated list of styles with slot names in parentheses. Example: If you want to use a text field for the slot named Age and a radio-button group for Gender, define this: text (Age), radio (Gender). This can be defined in a Module object and inherited by Input objects, or defined locally. Note that a new definition of this parameter always overwrites all of an inherited value.
By default, there is no label displayed in front of the input fields/radio button groups/drop-down lists. To be able to specify such a label, apply the tuning parameter Presentation – Slot Label. The value of the parameter must again be a comma-separated list of labels with slot names in parentheses. Example: If you want to show Gender: with a line break in front of your radio button-style slot named Gender, define this: Gender:|(Gender). The pipe symbol “|” works the same way as in Output objects; it gets replaced with the <br/> element. Alternatively, you can also use <br/> or any other markup directly in a label.

In voice and video applications, media platforms typically return additional information regarding the most recent recognition result, such as recognition confidence or the actual caller utterance. There are two different ways to access this kind of information. The first one is to use the function LASTRESULT() within an Expression object, which returns information on last confidence, utterance, input mode, and semantic interpretation and can easily be assigned e.g. to a variable for further processing:

If, on the other hand, you are only interested in the values of a specific Input object, you can use result handling:

The example shown here retrieves both the slot value sltReferenceNumber containing the recognized number as well as the recognition confidence value assigned by the media platform (a value between 0 and 1, indicating how sure the media platform is that the recognition result is correct). This confidence value may then be used e.g. to initiate a confirmation of the input if it falls below a certain threshold.

In general, media platform variables can be accessed by referencing them between hash signs (#). Typical values of interest are:

· #application.lastresult$.confidence#
A number between 0 and 1, with 0 indicating lowest confidence and 1 indicating highest confidence.

· #application.lastresult$.utterance#
Provides the actual string of words recognized by the media platform, as opposed to the derived slot value. For example, the slot value 123 may be returned for both the utterances one two three and one hundred twenty three.

· #application.lastresult$.inputmode#
Provides the mode used by the caller to make this input; can be either dtmf or voice.

i8 Note: In order to function correctly, an Input object needs to have at least one “normal” slot in addition to media platform value references using the “#” notation. Note also that media platform variables are not supported in the text and Web channel. The LASTRESULT function will still return values for the utterance and confidence (always 1), though.

In voice, video and Web applications, the Slot name must correspond to the names used in the grammar. In text applications, the slot name can be left empty.

N-Best Handling
Speech recognizers typically do not return a single hypothesis about what the caller said, but a whole array of hypotheses, all usually with different confidence values.

To access the different results, use the system function LASTRESULT(), as described within the Expression object in this Object Reference. The size of the array (the number of hypotheses returned) varies depending on the grammar and the setting of Max N-Best, a tuning parameter that can be set in the Tuning definition of various objects. The default value of this parameter is 1; so in order to be able to work with N-best results, set Max N-Best to a value greater than 1. The number of results returned is always between 1 and Max N-Best. For further details, refer to Tuning in this Object Reference.

N-Best handling is not supported in the text or Web channel.

Grammars without slot assignments
Some grammars do not return named slots, e.g. the built-in grammars provided by many media platforms. To make use of such grammars, it is possible to have a single entry in the Result Handling without a slot name. The value returned by the grammar is then assigned to the variable specified in the Variable field. This single nameless slot may be combined with any number of entries using the “#” notation described above.

When using text-to-grammar style grammars (see the Grammar object), the default slot is sltTTG for all media platforms certified with the VoiceObjects platform (note, though, that it is possible to define a different slot name through a media platform driver if required). For reasons of convenience, you can also leave this specific slot out when defining the result handling. This is also the case in the text and Web channel, where TTG is the only format supported.

i8 Note: The format in which utterances are returned when no named slot is present differs between the media platforms. Some platforms insert spaces between items in the utterance, while others do not.

Remove spaces from slots
In case the slot return value contains spaces which need to be removed, typically between digits in a digit sequence, select the checkbox Remove Spaces in the respective Result Handling Item section (in Desktop for Web use the context menu on the corresponding Slot field instead):

Before assigning the slot values to the Variable or Layer object of the respective result handling item, the server will remove all space characters.

Note that activating this feature in the context menu is only possible after defining a slot name or linking a Variable or Layer object.

Options

The Options section of the Input editor specifies the following processing options:

Enable auto-advance on No Input enables auto-advance in case no response from the caller is detected (only supported in the voice and video channel). If the check box is selected, a No Input event finishes the processing of the Input object and proceeds to the next object in the dialog flow instead of processing the event handling specifications. By default, the check box is clear.

Enable auto-advance on No Match enables auto-advance in case the caller says something that cannot be matched with the grammar (only supported in the voice and video channel). If the check box is selected, a No Match event finishes the processing of the Input object and proceeds to the next object in the dialog flow instead of processing the event handling specifications. By default, the check box is clear.

i8 Note: These options are for your convenience only. The same effect can be achieved by specifying a No Input or No Match event handling for level 1 and Continuation set to Proceed. If you want to proceed on the first No Input or No Match event, you may use these options. If you want to proceed at a later event occurrence level, specify appropriate event handling. Using a dedicated event handler also allows you to process any object before proceeding, e.g. play a prompt through an Output object.

Mask caller input for System DB logging encrypts the caller input before writing it to the system database via Infostore, the logging component of VoiceObjects Server. This is useful for sensitive data, like PINs, which mustn’t be stored as plain text for security reasons.
The default setting False indicating that the data is not encrypted. True indicates that data is encrypted in such a way that while the original value cannot be recovered, different input values still produce different encrypted values so that subsequent analyses are possible. Complete indicates that the values are completely masked by a single static string. (By default the string “***MASKED***” is used; it can be configured in components_VOServer.xml using the <maskUserInputComplete> element.)

Increased Dialog Timeout specifies a timeout value that is applied for this object in case it is higher than the current dialog timeout in a session. If it is lower, the setting is ignored. It is mainly applicable in the text and Web channel, where the dialog timeout of a service should be set to a relatively low value, e.g. 40 seconds, to keep the number of concurrent sessions low, as they usually run into the server timeout due to technical reasons. Use this setting to increase the timeout temporarily for objects that are likely to require more time to respond to, e.g. when the caller has to type in an address.

Grammar Control specifies whether this Input object should support grammar-driven application control. By default the value is Default, indicating that the current value of the corresponding dialog context setting GRAMMARCONTROL is used.
Grammar control allows the caller both to branch out to a different part of the application bypassing the current dialog step, and to correct misrecognition from a previous Input object in case it was implicitly confirmed by the system in a following input state. Technically, this feature allows setting Variable/Layer objects and/or making the server process a different object. To make use of it, a grammar must be defined in addition to the currently active grammar for this Input object. The new grammar must fill a slot called vogrammarcontrol with instructions for the server on objects to jump to and variables/layers to fill. The instructions are defined as the value of this slot. Assignments and jump commands are separated using the semi-colon.

To assign a value to a Variable object, use the syntax varXXX=YYY, where XXX is the reference ID of an existing Variable object, and YYY the value. To assign the empty string to a variable, use the notation varXXX=undefined.
To set a Layer object to a different state, use the syntax layXXX=YYY, where XXX is the reference ID of an existing Layer object, and YYY the desired state ID.

To define jump instructions, one gosub=XXX and one goto=YYY command can be defined, none of which are mandatory. XXX can be one or more (separated by commas) reference IDs of objects to be processed as sub-dialogs; after processing them the server returns to the current object or processes the goto command, if given. YYY can be one reference ID of the object to be processed, after which processing should stop. If no goto command is used in the vogrammarcontrol slot, a continuation can be defined, the value of which can be return (the default) and proceed. Proceed makes the server go on with the next object in the flow, after having processed any variable/layer assignments and/or gosub instruction. Return, the default, instructs the server to re-process the current object. This is required to implement implicit correction.

As an example, consider the following use case:

System: Welcome to Prime Insurance. Do you want information on car insurance, life insurance, or health insurance?

Caller: Life insurance please.

System: Life insurance, okay. First, please tell me your age.

Caller: Actually... do you have car insurance for my Ford?

System: Sure! What model of Ford do you drive?

To realize this, a grammar as shown in the following excerpt must be defined in the Input object Ask for age and Grammar Control must be set to true:

<item>

      <ruleref id=”Filler”/>
      car insurance for my
      <ruleref id=”CarMake”/>
      <tag>
         vogrammarcontrol='varCarManufacturer='+$CarMake+';
                          gosub=ConfOutput,CarInsurance;
                          goto=Root'
      </tag>

<item>

...

The string varCarManufacturer='+$CarMake+', which will result in something like varCarManufacturer=Ford at call time, tells the server to set the Variable object with reference ID CarManufacturer to the value Ford. The string gosub=ConfOutput,CarInsurance makes the server process the Output object ConfOutput, followed by the Module object CarInsurance. The string goto=Root finally instructs the server to jump to the Module object with reference ID Root. If this was left out the server would continue with reprocessing the object where the caller left off, which is not what is wanted in this example.

A second example shows how to implement implicit correction. Consider the following dialog:

System: Prime Car Insurance, always at your service. What’s the make and model of the car you drive?

Caller: Ford.

System: And what model of Volvo do you drive?

Caller: No, Ford!

System: I’m sorry. So what model of Ford do you drive?

To realize this, the grammar could set the vogrammarcontrol slot to the following value:

vogrammarcontrol='varCarManufacturer=Ford;gosub=ApologyOutput;continuation=return'

This will make the server re-assign the Variable CarManufacturer and reprocess the current object (which is Ask for Model), resulting in the desired behavior.

Record utterances specifies whether utterances made in this object are to be recorded (True) or not (False), given that utterance recording is switched on for this session. Always indicates that utterances in this object are always recorded when utterance recording is enabled on the service, regardless of statistical filtering. By default the value is Default, indicating that the current value of the corresponding dialog context setting RECORDUTTERANCES is used.

Recording scope defines the scope in which recordings will be made. If set to Recognition, only those utterances will be recorded that were successfully recognized (including the activation of hyperlinks). If set to No Match, only those utterances will be recorded that triggered a No Match event. If set to All, any recording will be stored. If set to Default, the current value of the corresponding dialog context setting RECORDINGSCOPE is used. By default the value is Default.

Due to the nature of recordings, the feature of recording utterances is only available in the voice and video channel. For more information on this refer to Chapter 6 – Recording of Utterances in the Deployment Guide.

VoiceObjectsXML Definition

The Input object is represented by the VoiceObjectsXML element <input>. It has five attributes and ten children.

In addition, the element has the standard attributes described in the XDK Guide.

The <input> element uses the embedded <resultHandling> and <item> elements.

Input

Attributes

· autoAdvanceNoInput
Defines whether the dialog should automatically advance to the next object in case of a No Input event. Either true or false. If not specified, defaults to false.

· autoAdvanceNoMatch
Defines whether the dialog should automatically advance to the next object in case of a No Match event. Either true or false. If not specified, defaults to false.

· maskCallerInput
Defines whether the input made by the caller should be masked when writing it to Infostore. This is recommended for sensitive data such as e.g. banking account numbers or PINs.
One of true, false, or complete. If not specified, defaults to false.

· recordUtterances
Defines whether to use utterance recording. One of true, false, always, default. If not specified, defaults to default.

· recordingScope
Defines the scope for utterance recording. One of all, noMatch, recognition, default. If not specified, defaults to default.

· increasedDialogTimeout
Defines the increased dialog timeout in seconds. If not specified, the setting from the dialog context is applied at call time.

Children

· <expression usage=”precondition”> or
<variable usage=”precondition”> or
<collection usage=”precondition”> or
<script usage=”precondition”>
Defines the precondition for the Input object.

· <sequence usage=”preprocessing”>
Defines the preprocessing sequence for the Input object.

· <output type=”initial”>
Defines the “initial” section of the embedded output.

· <output type=”reprompt”>
Defines the “event reprompt” section of the embedded output.

· <grammar>
Defines the grammar to be used for accepting caller input.

· <resultHandling> [required]
Defines the slot returns (including related values such as confidence) and their assignment to variables.

· <eventHandling>
Defines the event handling for the Input object.

· <customNavigation>
Defines the custom navigation for the Input object.

· <tuning>
Defines the tuning settings for the Input object.

· <sequence usage=”postprocessing”>
Defines the postprocessing sequence for the Input object.

Example

<text>Please let us know which car you drive.</text>

</outputItem>

</output>

<text>We need to know which car you drive. Please say the
manufacturer, followed by the model.</text>

</outputItem>

</output>

</resultHandling>

</input>

ResultHandling

Children

· +<item>
Defines the list of result handling items. The attributes alias and object need to be defined in each item.

Example

</resultHandling>

Item

Attributes

· object
Defines a reference to an object.

· alias
Defines the slot name. For TTG grammars, this is sltTTG by default.

· removeSpaces
Defines whether space characters will be removed from slot return values before being assigned to the Variable or Layer object. Either true or false. If not specified, defaults to false.

Example

Object Interoperability

The following table contains all object types that can reference an Input object:

Icon	Object Name	Use Case Example
	Module	An Input object can be used within the embedded sequence of a Module object.
	Sequence	Most commonly, an Input object is used within a sequence in a dialog flow.
	Menu	An Input object can be used as the destination object within a Menu item.
	Confirmation	An Input object is frequently used as the destination object within a Correction item inside a Confirmation object.
	If	An Input object can be used in either the THEN item or the ELSE item of an If object.
	Case	An Input object can be used in any WHEN item and the ELSE item of a Case object.
	Loop	An Input object can be used within the embedded sequence of a Loop object.
	Goto	An Input object can be referenced via a Goto object.
	Hyperlink	An Input object can be the destination of a Hyperlink object.

Object Naming Conventions

In order to leverage the capabilities of the integrated documentation of VoiceObjects it is important to provide intuitive and self-explanatory object names and descriptions.

The name of an Input object should indicate which type of input is requested from the caller. The short description should contain a brief explanation of the slots that are filled by the input. The table below lists three examples:

Name	Description
Ask for phone number	Requests a phone number from the caller and places it in the variable Phone Number.
Confirm transaction	Replays the transaction to be performed and asks for an explicit yes/no confirmation. The response is stored in the variable Yes/No Answer as yes or no.
Ask for car make and model	Multi-slot input asking for both maker and model of a car. Results are stored in Car make and Car model. It is possible to say only the make, in which case Car model will be empty.