Get Input | Aculab

get input Action

This action is no longer supported in Version 1 REST API. A new implementation of this action is supported using a natural language recogniser in Version 2 of the REST API.

Prompts the caller for input, either by saying a word or phrase or entering digits and waits for a response. You configure the prompt and the words to be recognised by specifying the expected grammar, using Aculab Speech Grammar Format (ASGF) and a period to wait for the words to be recognised. The caller is expected to respond by saying one or more of the words in the grammar or by pressing one or more valid digits.

The get input properties are:

Property	Required/Optional	Default	Description
prompt	required	-	A `play` action. This is the prompt that requests the user to say certain words or phrases or enter digits.
speech recognition grammar	required	-	A definition of any words and grammar that is to be recognised in ASGF syntax.
seconds speech recognition timeout	optional	30	The time period in seconds that the action waits for speech recognition to complete.
wait for prompt end	optional	true	Whether speech recognition is started after the prompt has been played. If false the speech recognition starts immediately before the prompt starts playing.
digit input enabled	optional	true	Whether digit input is enabled in addition to speech recognition.
digit input options	optional		A `digit input options` object that determines which digits are valid and other options associated with digit input.
on input timeout messages	optional	"Sorry, I did not recognise anything.", "Please listen to the instructions and then clearly say the relevant word or phrase."	An array of `play` actions. This defines messages to play if valid speech is not recognised within the timeout period. Each `play` action in the array is played once for each successive timeout. When all messages have been played the get input action finishes.
on invalid input messages	optional	"Sorry, I did not recognise that.", "Please listen to the instructions and clearly say the relevant word or phrase."	An array of `play` actions. This defines messages to play if speech is detected that is not part of the grammar or invalid digits are pressed. Each `play` action in the array is played once for each successive invalid input. When all messages have been played the get input action finishes.
help digit	optional	"*"	A single digit that, when pressed, will result in the prompt being repeated. An emtpy string signifies no help digit. Valid digits are 0123456789ABCD#*.
next page	optional	null	A `web page request` object that defines the web page to be requested once the get input action has completed successfully. The recognised words or digits entered will be sent to this page. If no page is specified then the subsequent action in the action array will be executed and the recognised words or digits entered will be lost.

digit input options defines which digits can be input, how the digit input is completed and a timeout for successive digit entry:

Property	Required/Optional	Default	Description
digit count	optional	0	The number of digits to enter. 0 signifies an unlimited number of digits, in which case `end digit` must be set.
end digit	optional	"#"	A single digit that, when pressed, will indicate the end of the number. An empty string signifies no end digit, in which case `digit count` must not be zero. Valid digits are 0123456789ABCD#*.
valid digits	optional	"0123456789"	A string that represents the set of digits that are deemed to be valid. Note that the `help digit` and `end digit` are also valid entries in addition to those set here. Any valid Dual Tone Multi Frequency (DTMF) digit can be included in this string. Valid digits are 0123456789ABCD#*.
seconds digit timeout	optional	5	An integer. The time period in seconds that the action waits for each digit to be entered.

web page request defines how a specific web page is requested:

Property	Required/Optional	Default	Description
url	required	-	The address of the web page to request.
method	optional	POST	"GET" or "POST". The HTTP request method to use when requesting the `url`.

Returns

The result of the get input action will be returned via the subsequent http request to the next page in action result as follows:

Property	Description
input	A string containing the speech that was recognised or digits that were entered on the telephone keypad in response to the prompt. For entered digits, the `end digit`, if entered, is not returned in this string.
input type	A string indicating how the string `input` was obtained. Either 'speech' or 'digits'.

Examples:

Get a single digit number using the pre-defined grammar and default settings:

"get_input" : 
{
    "prompt" : 
    {
        "play" :
        {
            "play_list" :
            [
                {
                    "text_to_say" : "Please say a single digit from zero to nine, or press a single digit followed by the hash key."
                }
            ]
        }
    },
    "speech_recognition_grammar" : "//OneDigit",
    "next_page" : 
    {
        "url" : "useinputpage"
    }
}

The following may be returned when a spoken number is successfully recognised:

"action_result" :
{
    "action" : "get_input",
    "result" :
    {
        "input_type": "speech",
        "input" : "seven"
    }
}

The following may be returned if a digit is pressed on the telephone keypad followed by '#':

"action_result" :
{
    "action" : "get_input",
    "result" :
    {
        "input_type": "digits",
        "input" : "7"
    }
}

Get a single digit number using a formatted grammar and disallowing digit presses:

"get_input" : 
{
    "prompt" : 
    {
        "play" :
        {
            "play_list" :
            [
                {
                    "text_to_say" : "Please say a digit from one to six."
                }
            ]
        }
    },
    "speech_recognition_grammar" : "one | two | three | four | five | six;",
    "digit_input_enabled" : false,
	"next_page" : 
    {
        "url" : "useinputpage"
    }
}

The following may be returned when a spoken number is successfully recognised:

"action_result" :
{
    "action" : "get_input",
    "result" :
    {
        "input_type": "speech",
        "input" : "five"
    }
}

Get a four digit number using the pre-defined grammar and setting some digit input options:

"get_input" : 
{
    "prompt" : 
    {
        "play" :
        {
            "play_list" :
            [
                {
                    "text_to_say" : "Please say a four digit number."
                }
            ]
        }
    },
    "speech_recognition_grammar" : "//FourDigits",
    "digit_input_options" :
    {
        "digit_count" : 4,
        "seconds_digit_timeout" : 10
    }
    "next_page" : 
    {
        "url" : "useinputpage"
    }
}

The following may be returned when a spoken four digit number is successfully recognised:

"action_result" :
{
    "action" : "get_input",
    "result" :
    {
        "input_type": "speech",
        "input" : "six eight one six"
    }
}

The following may be returned when a four digit number is entered on the telephone keypad:

"action_result" :
{
    "action" : "get_input",
    "result" :
    {
        "input_type": "digits",
        "input" : "6816"
    }
}

Get a four digit number using the pre-defined grammar. Allow the caller to speak during the prompt. Set some digit input options:

"get_input" : 
{
    "prompt" : 
    {
        "play" :
        {
            "play_list" :
            [
                {
                    "text_to_say" : "Please say a four digit number."
                }
            ]
        }
    },
    "speech_recognition_grammar" : "//FourDigits",
    "digit_input_options" :
    {
        "digit_count" : 4,
        "seconds_digit_timeout" : 10
    }
    "wait_for_prompt_end": false,
    "next_page" : 
    {
        "url" : "useinputpage"
    }
}

The following may be returned when a spoken four digit number is successfully recognised:

"action_result" :
{
    "action" : "get_input",
    "result" :
    {
		"input_type": "speech",
        "input" : "six eight one six"
    }
}

The following may be returned when a four digit number is entered on the telephone keypad:

"action_result" :
{
    "action" : "get_input",
    "result" :
    {
        "input_type": "digits",
        "input" : "6816"
    }
}

Get a four digit number using the pre-defined grammar. Allow the caller to speak during the prompt. Set some digit input options and set custom error messages:

"get_input" : 
{
    "prompt" : 
    {
        "play" :
        {
            "play_list" :
            [
                {
                    "text_to_say" : "Please say a four digit number."
                }
            ]
        }
    },
    "speech_recognition_grammar" : "//FourDigits",
    "digit_input_options" :
    {
        "digit_count" : 4,
        "seconds_digit_timeout" : 10
    }
    "wait_for_prompt_end": false,
    "on_input_timeout_messages" : 
    [
        {  
            "play" : 
            {
                "play_list" :
                [
                    {
                        "file_to_play" : "silencemessage1.wav"
                    }
                ]
            }
        },
        {  
            "play" : 
            {
                "play_list" :
                [
                    {
                        "file_to_play" : "silencemessage2.wav"
                    }  
                ]
            }
        }
    ],
    "on_invalid_input_messages" : 
    [
        {
            "play" : 
            {
                "play_list" :
                [
                    {
                        "text_to_say" : "Please say your digits or enter them on the telephone keyboard."
                    }
                ]
            }
        },
        {
            "play" : 
            {
                "play_list" :
                [
                    {
                        "text_to_say" : "No really!"
                    },
                    {
                        "text_to_say" : "Please say your digits or enter them on the telephone keyboard."
                    }
                ]
            }
        }
    ],    
    "next_page" : 
    {
        "url" : "useinputpage"
    }
}

The following may be returned when a spoken four digit number is successfully recognised:

"action_result" :
{
    "action" : "get_input",
    "result" :
    {
        "input_type": "speech",
        "input" : "six eight one six"
    }
}

The following may be returned when a four digit number is entered on the telephone keypad:

"action_result" :
{
    "action" : "get_input",
    "result" :
    {
        "input_type": "digits",
        "input" : "6816"
    }
}

API Reference:

class GetInput : TelephonyAction

Represents a get input action.

Constructors:

GetInput(Play prompt, SpeechRecognitionGrammar grammar);
GetInput(Play prompt, SpeechRecognitionGrammar grammar, int secondsSpeechRecognitionTimeout);
GetInput(Play prompt, SpeechRecognitionGrammar grammar, int secondsSpeechRecognitionTimeout, WebPageRequest nextPage);

Members:

SpeechRecognitionGrammar Grammar;
int SecondsSpeechRecognitionTimeout;
bool WaitForPromptEnd;
bool DigitInputEnabled;
DigitInputOptions DigitInputOptions;
List<Play> OnInputTimeoutMessages;
List<Play> OnInvalidInputMessages;
char HelpDigit;
WebPageRequest NextPage;

class SpeechRecognitionGrammar

Represents a grammar specification that determines what the speech recognition will recognise.

Constructors:

SpeechRecognitionGrammar(String customGrammarSpecification);

Members:

String GrammarSpecification;

static SpeechRecognitionGrammar CreateFromAlternatives(String[] alternatives);
static SpeechRecognitionGrammar PredefinedGrammar(String predefinedGrammarName);

These predefined helper objects define some useful predefined grammar strings:
static OneDigit;
static TwoDigits;
static ThreeDigits;
static FourDigits;
static FiveDigits;
static OneToThirtyOne;
static SixteenToNinetyNine;
static ZeroToNinetyNine;

class DigitInputOptions

Represents a set of options that determine how digits are detected.

Constructors:

DigitInputOptions(int digitCount);
DigitInputOptions(char endDigit);
DigitInputOptions(int digitCount, char endDigit, String validDigits);
DigitInputOptions(int digitCount, char endDigit, String validDigits, int secondsDigitTimeout);

Members:

int DigitCount;
char EndDigit;
String ValidDigits;
int SecondsDigitTimeout;

class WebPageRequest

Represents a request to a web page.

Constructors:

WebPageRequest(String url);
WebPageRequest(String url, String method);

Members:

String Method;

class GetInputResult : ActionResult

Represents the result of a get input action.

Members:

String Input;
String InputType;

Examples:

Get a single digit number using the pre-defined grammar and default settings:

Play prompt = Play.SayText("Please say single digit from zero to nine, or press a digit followed by the hash key.");
actions.Add(new GetInput(prompt, SpeechRecognitionGrammar.OneDigit, 5, new WebPageRequest("UseInputPage.aspx")));

The following may be returned when a spoken number is successfully recognised:

GetInputResult inputResult = (GetInputResult)ourRequest.InstanceInfo.ActionResult;
if (inputResult.InputType.Equals("speech"))
	String input = inputResult.Input;
	...

The following may be returned when a digit is pressed on the telephone keypad followed by '#':

GetInputResult inputResult = (GetInputResult)ourRequest.InstanceInfo.ActionResult;
if (inputResult.InputType.Equals("digits"))
	String input = inputResult.Input;
	...

Get a single digit number using a formatted grammar and disallowing digit presses:

Play prompt = Play.SayText("Please say a digit from one to six.");

String[] alternatives = new String[] { "one", "two", "three", "four", "five", "six" };
SpeechRecognitionGrammar grammar = SpeechRecognitionGrammar.CreateFromAlternatives(alternatives);
GetInput getInputAction = new GetInput(prompt, grammar, 5, new WebPageRequest("UseInputPage.aspx"));

getInputAction.DigitInputEnabled = false;

actions.Add(getInputAction);

Get a four digit number using the pred-defined grammar and setting some digit input options:

Play prompt = Play.SayText("Please say a four digit number.");
GetInput getInputAction = new GetInput(prompt, SpeechRecognitionGrammar.FourDigits, 10, new WebPageRequest("UseInputPage.aspx"));

getInputAction.DigitInputOptions = new DigitInputOptions(4);
getInputAction.DigitInputOptions.SecondsDigitTimeout = 10;

actions.Add(getInputAction);

Get a four digit number using the pred-defined grammar. Allow the caller to speak during the prompt. Set some digit input options:

Play prompt = Play.SayText("Please say a four digit number.");
GetInput getInputAction = new GetInput(prompt, SpeechRecognitionGrammar.FourDigits, 10, new WebPageRequest("UseInputPage.aspx"));

getInputAction.WaitForPromptEnd = false;

getInputAction.DigitInputOptions = new DigitInputOptions(4);
getInputAction.DigitInputOptions.SecondsDigitTimeout = 10;

actions.Add(getInputAction);

Get a four digit number using the pred-defined grammar. Allow the caller to speak during the prompt. Set some digit input options and some custom messages:

Play prompt = Play.SayText("Please say a four digit number.");
GetInput getInputAction = new GetInput(prompt, SpeechRecognitionGrammar.FourDigits, 10, new WebPageRequest("UseInputPage.aspx"));

getInputAction.WaitForPromptEnd = false;

getInputAction.DigitInputOptions = new DigitInputOptions(4);
getInputAction.DigitInputOptions.SecondsDigitTimeout = 10;

// Set up the messages to play if the caller does not
// say or enter a number or says or enters an invalid one.
getInputAction.OnInputTimeoutMessages = new List<Play>();
getInputAction.OnInputTimeoutMessages.Add(Play.PlayFile("silencemessage1.wav"));
getInputAction.OnInputTimeoutMessages.Add(Play.PlayFile("silencemessage2.wav"));

getInputAction.OnInvalidInputMessages = new List<Play>();
getInputAction.OnInvalidInputMessages.Add(Play.SayText("Please say your digits or enter them on the telephone keyboard."));
Play finalMessage = Play.SayText("No really!");
finalMessage.AddText("Please say your digits or enter them on the telephone keyboard.");
getInputAction.OnInvalidInputMessages.Add(finalMessage);

actions.Add(getInputAction);

API Reference:

Class GetInput Inherits RestAPIWRapper.TelephonyAction

Represents a get input action.

Constructors:

New(prompt As RestAPIWRapper.Play, grammar As RestAPIWRapper.SpeechRecognitionGrammar)
New(prompt As RestAPIWRapper.Play, grammar As RestAPIWRapper.SpeechRecognitionGrammar, _
	secondsSpeechRecognitionTimeout as Integer)
New(prompt As RestAPIWRapper.Play, grammar As RestAPIWRapper.SpeechRecognitionGrammar, _ 
	secondsSpeechRecognitionTimeout as Integer, nextPage As RestAPIWRapper.WebPageRequest)

Members:

Grammar As RestAPIWRapper.SpeechRecognitionGrammar
SecondsSpeechRecognitionTimeout As Integer
WaitForPromptEnd As Boolean
DigitInputEnabled As Boolean
DigitInputOptions As RestAPIWRapper.DigitInputOptions
OnInputTimeoutMessages As List(Of RestAPIWRapper.Play)
OnInvalidInputMessages As List(Of RestAPIWRapper.Play)
HelpDigit As Char
NextPage As RestAPIWRapper.WebPageRequest

Class SpeechRecognitionGrammar

Represents a grammar specification that determines what the speech recognition will recognise.

Constructors:

New(customGrammarSpecification As String)

Members:

GrammarSpecification As String

Shared CreateFromAlternatives(alternatives As String()) As RestAPIWRapper.SpeechRecognitionGrammar
Shared PredefinedGrammar(predefinedGrammarName As String) As RestAPIWRapper.SpeechRecognitionGrammar

These predefined helper objects define some useful predefined grammar strings:
Shared OneDigit As RestAPIWRapper.SpeechRecognitionGrammar
Shared TwoDigits As RestAPIWRapper.SpeechRecognitionGrammar
Shared ThreeDigits As RestAPIWRapper.SpeechRecognitionGrammar
Shared FourDigits As RestAPIWRapper.SpeechRecognitionGrammar
Shared FiveDigits As RestAPIWRapper.SpeechRecognitionGrammar
Shared OneToThirtyOne As RestAPIWRapper.SpeechRecognitionGrammar
Shared SixteenToNinetyNine As RestAPIWRapper.SpeechRecognitionGrammar
Shared ZeroToNinetyNine As RestAPIWRapper.SpeechRecognitionGrammar

Class DigitInputOptions

Represents a set of options that determine how digits are detected.

Constructors:

New(digitCount As Integer)
New(endDigit As Char)
New(digitCount As Integer, endDigit As Char, validDigits As String)
New(digitCount As Integer, endDigit As Char, validDigits As String, secondsDigitTimeout As Integer)

Members:

DigitCount As Integer
EndDigit As Char
ValidDigits As String
SecondsDigitTimeout As Integer

Class WebPageRequest

Represents a request to a web page.

Constructors:

New(url As String)
New(url As String, method As String)

Members:

String Method;

Class GetInputResult Inherits RestAPIWRapper.ActionResult

Represents the result of a get input action.

Members:

Input As String
InputType As String

Examples:

Get a single digit number using the pre-defined grammar and default settings:

Dim prompt As Play = Play.SayText("Please say a single digit from zero to nine, or press a digit followed by the hash key.")
actions.Add(New GetInput(prompt, SpeechRecognitionGrammar.OneDigit, 5, New WebPageRequest("UseInputPage.aspx")))

The following may be returned when a spoken number is successfully recognised:

Dim inputResult As GetInputResult = ourRequest.InstanceInfo.ActionResult
If inputResult.InputType.Equals("speech") Then
	Dim input As String = inputResult.Input
	...
End If

The following may be returned when a digit is pressed on the telephone keypad, followed by '#':

Dim inputResult As GetInputResult = ourRequest.InstanceInfo.ActionResult
If inputResult.InputType.Equals("digits") Then
	Dim input As String = inputResult.Input
	...
End If

Get a single digit number using a formatted grammar and disallowing digit presses:

Dim prompt As Play = Play.SayText("Please say a digit from one to six.")
Dim alternatives() as String = { "one", "two", "three", "four", "five", "six" }
Dim grammar as SpeechRecognitionGrammar = SpeechRecognitionGrammar.CreateFromAlternatives(alternatives)
Dim getInputAction As GetInput = New GetInput(prompt, grammar, 5, New WebPageRequest("UseInputPage.aspx"))

getInputAction.DigitInputEnabled = False

actions.Add(getInputAction)

Get a four digit number using the pred-defined grammar and setting some digit input options:

Dim prompt As Play = Play.SayText("Please say a four digit number.")
Dim getInputAction As GetInput = New GetInput(prompt, SpeechRecognitionGrammar.FourDigits, _
	10, New WebPageRequest("UseInputPage.aspx"))

getInputAction.DigitInputOptions = New DigitInputOptions(4)
getInputAction.DigitInputOptions.SecondsDigitTimeout = 10

actions.Add(getInputAction)

Get a four digit number using the pred-defined grammar. Allow the caller to speak during the prompt. Set some digit input options:

Dim prompt As Play = Play.SayText("Please say a four digit number.")
Dim getInputAction As GetInput = New GetInput(prompt, SpeechRecognitionGrammar.FourDigits, _
	10, New WebPageRequest("UseInputPage.aspx"))

getInputAction.WaitForPromptEnd = False

getInputAction.DigitInputOptions = New DigitInputOptions(4)
getInputAction.DigitInputOptions.SecondsDigitTimeout = 10

actions.Add(getInputAction)

Get a four digit number using the pred-defined grammar. Allow the caller to speak during the prompt. Set some digit input options and some custom messages:

Dim prompt As Play = Play.SayText("Please say a four digit number.")
Dim getInputAction As GetInput = New GetInput(prompt, SpeechRecognitionGrammar.FourDigits, _
	10, New WebPageRequest("UseInputPage.aspx"))

getInputAction.WaitForPromptEnd = False

getInputAction.DigitInputOptions = New DigitInputOptions(4)
getInputAction.DigitInputOptions.SecondsDigitTimeout = 10

' Set up the messages to play if the caller does not
' say or enter a number or says or enters an invalid one.
getInputAction.OnInputTimeoutMessages = New List(Of Play)
getInputAction.OnInputTimeoutMessages.Add(Play.PlayFile("silencemessage1.wav"))
getInputAction.OnInputTimeoutMessages.Add(Play.PlayFile("silencemessage2.wav"))

getInputAction.OnInvalidInputMessages = New List(Of Play)
getInputAction.OnInvalidInputMessages.Add(Play.SayText("Please say your digits or enter them on the telephone keyboard."))
Play finalMessage = Play.SayText("No really!")
finalMessage.AddText("Please say your digits or enter them on the telephone keyboard.")
getInputAction.OnInvalidInputMessages.Add(finalMessage)

actions.Add(getInputAction)

API Reference:

class GetInput extends TelephonyAction

Represents a get input action.

Constructors:

GetInput(Play prompt, SpeechRecognitionGrammar grammar);
GetInput(Play prompt, SpeechRecognitionGrammar grammar, int secondsSpeechRecognitionTimeout);
GetInput(Play prompt, SpeechRecognitionGrammar grammar, int secondsSpeechRecognitionTimeout, WebPageRequest nextPage);

Members:

setSecondsSpeechRecognitionTimeout(int seconds);
setWaitForPromptEnd(boolean waitForPromptEnd);
setDigitInputEnabled(boolean enabled);
setDigitInputOptions(DigitInputOptions options);
setOnInputTimeoutMessages(List<Play> messages);
setOnInvalidInputMessages(List<Play> messages);
setHelpDigit(char helpDigit);
setNextPage(WebPageRequest nextPage);

class SpeechRecognitionGrammar

Represents a grammar specification that determines what the speech recognition will recognise.

Constructors:

SpeechRecognitionGrammar(String customGrammarSpecification);

Members:

String GrammarSpecification;

static SpeechRecognitionGrammar createFromAlternatives(String[] alternatives);
static SpeechRecognitionGrammar getPredefinedGrammar(String predefinedGrammarName);

These predefined helper objects define some useful predefined grammar strings:
static OneDigit;
static TwoDigits;
static ThreeDigits;
static FourDigits;
static FiveDigits;
static OneToThirtyOne;
static SixteenToNinetyNine;
static ZeroToNinetyNine;

class DigitInputOptions

Represents a set of options that determine how digits are detected.

Constructors:

DigitInputOptions(int digitCount);
DigitInputOptions(char endDigit);
DigitInputOptions(int digitCount, char endDigit, String validDigits);
DigitInputOptions(int digitCount, char endDigit, String validDigits, int secondsDigitTimeout);

Members:

setDigitCount(int count);
setEndDigit(char digit);
setValidDigits(String validDigits);
setSecondsDigitTimeout(int seconds);

class WebPageRequest

Represents a request to a web page.

Constructors:

WebPageRequest(String url);
WebPageRequest(String url, String method);

Members:

setMethod(String method);

class GetInputResult extends ActionResult

Represents the result of a get input action.

Members:

String getInput();
String getInputType();

Examples:

Get a single digit number using the pre-defined grammar and default settings:

Play prompt = Play.sayText("Please say a single digit from zero to nine, or press a digit followed by the hash key.");
actions.add(new GetInput(prompt, SpeechRecognitionGrammar.OneDigit, 5, new WebPageRequest("UseInputPage")));

The following may be returned when a spoken number is successfully recognised:

GetInputResult inputResult = (GetInputResult)ourRequest.getInstanceInfo().getActionResult();
if (inputResult.getInputType().equals("speech"))
	String input = inputResult.getInput();
	...

The following may be returned when a digit is pressed on the telephone keypad followed by '#':

GetInputResult inputResult = (GetInputResult)ourRequest.getInstanceInfo().getActionResult();
if (inputResult.getInputType().equals("digits"))
	String input = inputResult.getInput();
	...

Get a single digit number using a formatted grammar and disallowing digit presses:

Play prompt = Play.sayText("Please say a digit from one to six.");

String[] alternatives = new String[] { "one", "two", "three", "four", "five", "six" };
SpeechRecognitionGrammar grammar = SpeechRecognitionGrammar.createFromAlternatives(alternatives);
GetInput getInputAction = new GetInput(prompt, grammar, 5, new WebPageRequest("UseInputPage"));

getInputAction.setDigitInputEnabled(false);

actions.add(getInputAction);

Get a four digit number using the pred-defined grammar and setting some digit input options:

Play prompt = Play.sayText("Please say a four digit number.");
GetInput getInputAction = new GetInput(prompt, SpeechRecognitionGrammar.FourDigits, 10, new WebPageRequest("UseInputPage"));

DigitInputOptions digitOptions = new DigitInputOptions(4);
digitOptions.setSecondsDigitTimeout(10);
getInputAction.setDigitInputOptions(digitOptions);

actions.add(getInputAction);

Get a four digit number using the pred-defined grammar. Allow the caller to speak during the prompt. Set some digit input options:

Play prompt = Play.sayText("Please say a four digit number.");
GetInput getInputAction = new GetInput(prompt, SpeechRecognitionGrammar.FourDigits, 10, new WebPageRequest("UseInputPage"));

getInputAction.setWaitForPromptEnd(false);

DigitInputOptions digitOptions = new DigitInputOptions(4);
digitOptions.setSecondsDigitTimeout(10);
getInputAction.setDigitInputOptions(digitOptions);

actions.add(getInputAction);

Get a four digit number using the pred-defined grammar. Allow the caller to speak during the prompt. Set some digit input options and some custom messages:

Play prompt = Play.sayText("Please say a four digit number.");
GetInput getInputAction = new GetInput(prompt, SpeechRecognitionGrammar.FourDigits, 10, new WebPageRequest("UseInputPage"));

getInputAction.setWaitForPromptEnd(false);

DigitInputOptions digitOptions = new DigitInputOptions(4);
digitOptions.setSecondsDigitTimeout(10);
getInputAction.setDigitInputOptions(digitOptions);

// Set up the messages to play if the caller does not
// say or enter a number or says or enters an invalid one.
List<Play> onInputTimeoutMessages = new ArrayList<Play>();
onInputTimeoutMessages.add(Play.playFile("silencemessage1.wav"));
onInputTimeoutMessages.add(Play.playFile("silencemessage2.wav"));
getInputAction.setOnInputTimeoutMessages(onInputTimeoutMessages);

List<Play> onInvalidInputMessages = new ArrayList<Play>();
onInvalidInputMessages.add(Play.sayText("Please say your digits or enter them on the telephone keyboard."));
Play finalMessage = Play.sayText("No really!");
finalMessage.addText("Please say your digits or enter them on the telephone keyboard.");
onInvalidInputMessages.add(finalMessage);
getInputAction.setOnInvalidInputMessages(onInvalidInputMessages);

actions.add(getInputAction);

API Reference:

class GetInput

Represents a get_input action.

Constructors:

GetInput()

Members:

def on_prompt_play(play_action) # A Play object, see Play() for details
def set_grammar(speech_recognition_grammar) # string or pre-defined grammar
def set_wait_for_prompt_end(wait_for_prompt_end)
def set_digit_input_enabled(digit_input_enabled)
def set_help_digit(help_digit)
def set_digit_options(digit_options) # A DigitInputOptions object
def set_seconds_speech_recognition_timeout(seconds_speech_recognition_timeout)
def set_next_page(next_page) # A WebPage object, see Redirect() for details
def append_on_input_timeout_message(play_action)
def append_on_invalid_input_message(play_action)

class DigitInputOptions

Digit options. Used by GetInput, passed to set_digit_options()

Constructors:

DigitInputOptions()

Members:

def set_valid_digits(valid_digits)
def set_digit_count(digit_count)
def set_end_digit(end_digit):
def set_seconds_digit_timeout(seconds_digit_timeout)

Examples:

Get a single digit number using the pre-defined grammar and default settings:

from aculab.telephony_rest_api import *

my_actions = Actions('Usage example 1: GetInput.')
my_input = GetInput()

my_input.on_prompt_play(Play(text_to_say='Please say a number from zero to nine.'))
my_input.set_grammar(GetInput.Grammars.OneDigit)
my_input.set_next_page(WebPage(url='use_number_page'))
my_actions.add(my_input)

response_body = my_actions.get_json()

Get a single digit number using the pre-defined grammar and disallowing digit inputs:

from aculab.telephony_rest_api import *

my_actions = Actions('Usage example 1: GetInput.')
my_input = GetInput()

my_input.on_prompt_play(Play(text_to_say='Please say a number from zero to nine.'))
my_input.set_grammar(GetInput.Grammars.OneDigit)
my_input.set_digit_input_enabled(False)
my_input.set_next_page(WebPage(url='use_number_page'))
my_actions.add(my_input)

response_body = my_actions.get_json()

Get a four digit number using the pre-defined grammar and setting some digit options:

from aculab.telephony_rest_api import *

my_actions = Actions('Usage example 1: GetInput.')
my_input = GetInput()

my_input.on_prompt_play(Play(text_to_say='Please say your four digit number.'))
my_input.set_grammar(GetInput.Grammars.FourDigits)

my_digit_options = DigitInputOptions()
my_digit_options.set_digit_count(4)
my_digit_options.set_seconds_digit_timeout(10)

my_input.set_digit_options(my_digit_options)
my_input.set_next_page(WebPage(url='use_number_page'))
my_actions.add(my_input)

response_body = my_actions.get_json()

Get a four digit number using the pre-defined grammar. Allow the caller to speak during the prompt. Set some digit options:

from aculab.telephony_rest_api import *

my_actions = Actions('Usage example 1: GetInput.')
my_input = GetInput()

my_input.on_prompt_play(Play(text_to_say='Please say your four digit number.'))
my_input.set_grammar(GetInput.Grammars.FourDigits)

my_digit_options = DigitInputOptions()
my_digit_options.set_digit_count(4)
my_digit_options.set_seconds_digit_timeout(10)

my_input.set_digit_options(my_digit_options)
my_input.set_wait_for_prompt_end(False)
my_input.set_next_page(WebPage(url='use_number_page'))
my_actions.add(my_input)

response_body = my_actions.get_json()

Get a four digit number using the pre-defined grammar. Allow the caller to speak during the prompt. Set some digit options. Set custom error messages:

from aculab.telephony_rest_api import *

my_actions = Actions('Usage example 1: GetInput.')
my_input = GetInput()

my_input.on_prompt_play(Play(text_to_say='Please say your four digit number.'))
my_input.set_grammar(GetInput.Grammars.FourDigits)

my_digit_options = DigitInputOptions()
my_digit_options.set_digit_count(4)
my_digit_options.set_seconds_digit_timeout(10)

my_input.set_digit_options(my_digit_options)
my_input.set_wait_for_prompt_end(False)

my_input.append_on_input_timeout_message(Play(file_to_play='silencemessage1.wav'))
my_input.append_on_input_timeout_message(Play(file_to_play='silencemessage2.wav'))
my_input.append_on_invalid_input_message(Play(text_to_say='Please say your digits or enter them on the telephone keyboard.'))
play_action = Play(text_to_say='No really!')
play_action.append_text(text_to_say='Please say your digits or enter them on the telephone keyboard.')
my_input.append_on_invalid_input_message(play_action)

my_input.set_next_page(WebPage(url='use_number_page'))
my_actions.add(my_input)

response_body = my_actions.get_json()

API Reference:

The GetInput class

Introduction

Represents a get input action.
The $grammar of the constructor is either a full string, an array of alternative grammar strings or one of the predefined constants.

Class synopsis

class GetInput extends ActionBase {

    /* Constants */
    const ONEDIGIT = '//OneDigit'
    const TWODIGITS = '//TwoDigits'
    const THREEDIGITS = '//ThreeDigits'
    const FOURDIGITS = '//FourDigits'
    const FIVEDIGITS = '//FiveDigits'
    const ONETOTHIRTYONE = '//OneToThirtyOne'
    const SIXTEENTONINETYNINE = '//SixteenToNinetyNine'
    const ZEROTONINETYNINE = '//ZeroToNinetyNine'
    const YESORNO = '//YesOrNo'

    /* Methods */
    public __construct(Play $prompt, mixed $grammar)
    public void setSpeechRecognitionTimeout(int $seconds)
    public void setWaitForPromptEnd(boolean $wait)
    public void setDigitInputEnabled(boolean $enabled)
    public void setDigitInputOptions(int $digitCount = 0, string $endDigit = null, string $validDigits = null, int $digitTimeoutSeconds = -1)
    public void setOnInputTimeoutMessages(MessageList $messages)
    public void setOnInvalidInputMessages(MessageList $messages)
    public void setNextPage(string $nextPage, string $method = null)
    public void setHelpDigit(string $helpDigit)
}

The MessageList class

Introduction

Represents a list of messages.

Class synopsis

class MessageList {

    /* Methods */
    public __construct()
    public void addMessage(Play $play)
}

The GetInputResult class

Introduction

Represents the result of a get input action.

Class synopsis

class GetInputResult extends ActionResult {

    /* Methods */
    public string getInputType()
    public string getInput()
    
    /* inherited methods */
    public string getAction()
    public boolean getInterrupted()
}

Examples:

Get a single digit number using the pre-defined grammar and default settings:

$prompt = Aculab\TelephonyRestAPI\Play::sayText("Please say a single digit from zero to nine, or press a digit followed by the hash key.");
$getInput = new Aculab\TelephonyRestAPI\GetInput($prompt, GetInput::ONEDIGIT);
$getInput->setNextPage('useinputpage');
$actions->add($getInput);

The following may be returned when a spoken number is successfully recognised:

$info = InstanceInfo::getInstanceInfo();
$inputResult = $info->getActionResult();
if ($inputResult->getInputType() === 'speech') {
    $input = $inputResult->getInput();
}

The following may be returned if a digit is pressed on the telephone keypad, followed by '#':

$info = InstanceInfo::getInstanceInfo();
$inputResult = $info->getActionResult();
if ($inputResult->getInputType() === 'digits') {
    $input = $inputResult->getInput();
}

Get a single digit number using a formatted grammar and disallowing digit presses:

$prompt = Aculab\TelephonyRestAPI\Play::sayText("Please say a digit from one to six.");
$getInput = new Aculab\TelephonyRestAPI\GetInput($prompt, array('one', 'two', 'three', 'four', 'five', 'six'));
$getInput->setNextPage('useinputpage');
$getInput->setEnableDigitInput(false);
$actions->add($getInput);

The following may be returned when a spoken number is successfully recognised:

$info = InstanceInfo::getInstanceInfo();
$inputResult = $info->getActionResult();
if ($inputResult->getInputType() === 'speech') {
    $input = $inputResult->getInput();
}

Get a four digit number using the pre-defined grammar and setting some digit input options:

$prompt = Aculab\TelephonyRestAPI\Play::sayText("Please say a four digit number.");
$getInput = new Aculab\TelephonyRestAPI\GetInput($prompt, GetInput::FOURDIGITS);
$getInput->setNextPage('useinputpage');
$getInput->setDigitInputOptions(4, null, null, 10);
$actions->add($getInput);

The following may be returned when a spoken number is successfully recognised:

$info = InstanceInfo::getInstanceInfo();
$inputResult = $info->getActionResult();
if ($inputResult->getInputType() === 'speech') {
    $input = $inputResult->getInput();
}

The following may be returned if a digit is pressed on the telephone keypad:

$info = InstanceInfo::getInstanceInfo();
$inputResult = $info->getActionResult();
if ($inputResult->getInputType() === 'digits') {
    $input = $inputResult->getInput();
}

Get a four digit number using the pre-defined grammar. Allow the caller to speak during the prompt. Set some digit input options:

$prompt = Aculab\TelephonyRestAPI\Play::sayText("Please say a four digit number.");
$getInput = new Aculab\TelephonyRestAPI\GetInput($prompt, GetInput::FOURDIGITS);
$getInput->setNextPage('useinputpage');
$getInput->setDigitInputOptions(4, null, null, 10);
$getInput->setWaitForPromptEnd(false);
$actions->add($getInput);

The following may be returned when a spoken number is successfully recognised:

$info = InstanceInfo::getInstanceInfo();
$inputResult = $info->getActionResult();
if ($inputResult->getInputType() === 'speech') {
    $input = $inputResult->getInput();
}

The following may be returned if a digit is pressed on the telephone keypad:

$info = InstanceInfo::getInstanceInfo();
$inputResult = $info->getActionResult();
if ($inputResult->getInputType() === 'digits') {
    $input = $inputResult->getInput();
}

Get a four digit number using the pre-defined grammar. Allow the caller to speak during the prompt. Set some digit input options and set custom error messages:

$prompt = Aculab\TelephonyRestAPI\Play::sayText("Please say a four digit number.");
$getInput = new Aculab\TelephonyRestAPI\GetInput($prompt, GetInput::FOURDIGITS);
$getInput->setNextPage('useinputpage');
$getInput->setDigitInputOptions(4, null, null, 10);
$getInput->setWaitForPromptEnd(false);

// Set up the error messages.
$timeout = new Aculab\TelephonyRestAPI\MessageList();
$timeout->addMessage(Aculab\TelephonyRestAPI\Play::playFile('silencemessage1.wav'));
$timeout->addMessage(Aculab\TelephonyRestAPI\Play::playFile('silencemessage2.wav'));
$getInput->setOnInputTimeoutMessages($timeout);

$invalid = new Aculab\TelephonyRestAPI\MessageList();
$invalid->addMessage(Aculab\TelephonyRestAPI\Play::sayText('Please say your digits or enter them on the telephone keyboard.'));
$message = Aculab\TelephonyRestAPI\Play::sayText('No really!');
$message->addText('Please say your digits or enter them on the telephone keyboard.')
$invalid->addMessage($message);
$getInput->setOnInvalidInputMessages($invalid);

$actions->add($getInput);

The following may be returned when a spoken number is successfully recognised:

$info = InstanceInfo::getInstanceInfo();
$inputResult = $info->getActionResult();
if ($inputResult->getInputType() === 'speech') {
    $input = $inputResult->getInput();
}

The following may be returned if a digit is pressed on the telephone keypad:

$info = InstanceInfo::getInstanceInfo();
$inputResult = $info->getActionResult();
if ($inputResult->getInputType() === 'digits') {
    $input = $inputResult->getInput();
}

Cloud documentation

Returns

Examples:

Contact Aculab