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:

PropertyRequired/OptionalDefaultDescription
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:

PropertyRequired/OptionalDefaultDescription
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:

PropertyRequired/OptionalDefaultDescription
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:

PropertyDescription
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'.
 See also: Simple Get Input
  • 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();
      }