run speech menu 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.

Runs an interactive menu that requests a short utterance, or a single digit key press from the caller. You configure it to prompt for a number of menu options and the caller is expected to respond by saying a word or pressing a single digit. For example "Say your colour, blue or red, or press one for blue or two for red."


The run speech menu properties are:

PropertyRequired/OptionalDefaultDescription
prompt required - A play action. This is the prompt that requests a digit to be selected, or word to be said.
menu options required - An array of speech menu option objects, each specifying a Dual Tone Multi Frequency (DTMF) digit, a word (a short utterance which can be more than one word), and an associated next page.
help digit optional "*" A single digit that, when pressed, will result in the menu prompt being repeated. An emtpy string signifies no help digit. Valid digits are 0123456789ABCD#*.
help word optional "help" A single word that, when said, will result in the menu prompt being repeated. An empty string signifies no help word.
seconds input timeout optional 5 An integer. The time period in seconds that the run menu action waits for a response from the user.
on input timeout messages optional "Sorry, I did not recognise anything.",
"Please listen to the instructions, and then clearly say the relevant word or press the relevant digit."
An array of play actions. This defines messages to play if no input is recognised within the input timeout period. Each play action in the array is played once for each successive timeout. When all messages have been played the run menu action finishes. Note that barge in is disabled by default for these actions.
on invalid input messages optional "Sorry, I did not recognise that.",
"Please listen to the instructions, and then clearly say the relevant word or press the relevant digit."
An array of play actions. This defines messages to play if an invalid input is detected. Each play action in the array is played once for each successive invalid input. When all messages have been played the run menu action finishes. Note that barge in is disabled by default for these actions.

The speech menu option properties are:

PropertyRequired/OptionalDefaultDescription
speech required - The word or words to be said for this option. This can be a short phrase, but the number of words in the phrase should be kept to a minimum.
digit required - The digit to be pressed for this option. Valid digits are 0123456789ABCD#*.
next page required - A web page request object that defines the web page to be requested when the associated digit or word is recognised. Setting this to null signifies that the subsequent action in the action array should be executed when this option is selected.

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 One of "GET" or "POST". The HTTP request method to use when requesting the url.

Returns

The result of the menu selection will be returned via the subsequent http request to the selected next page in action result as follows:

PropertyDescription
selected speech A string containing the word or phrase of the menu option that was selected.
selected digit A string containing the single digit of the menu option that was selected.
selected input type A string indicating how the menu option was selected. Either 'speech' or 'digit'.
  • Examples:

    • Run a simple yes/no menu using the defaults:

      "run_speech_menu" : 
      {
          "prompt" : 
          {
              "play" :
              {
                  "play_list" :
                  [
                      {
                          "text_to_say" : "Please say yes or no. Or press 1 for yes and 2 for no."
                      }
                  ]
              }
          },
          "menu_options" : 
          [
              {
                  "digit"  : "1",
                  "speech" : "yes",
                  "next_page" : 
                  {
                      "url" : "optionyespage"
                  }
              },
              {
                  "digit"  : "2",
                  "speech" : "no"
                  "next_page" : 
                  {
                      "url" : "optionnopage"
                  }
              }
          ]
      }
      

      The selected option is specified in the request for the next page:

      "action_result" :
      {
          "action" : "run_speech_menu",
          "result" :
          {
              "selected_speech" : "no",
              "selected_digit" : "2",
              "selected_input_type" : "speech"
          }
      }
      
    • Run a menu with three options, specifying non-default parameters:

      "run_menu" : 
      {
          "prompt" : 
          {
              "play" :
              {
                  "play_list" :
                  [
                      {
                          "file_to_play" : "voicemailmenu.wav"
                      }
                  ]
              }
          },
          "menu_options" : 
          [
              {
                  "digit"  : "1",
                  "speech" : "one",
                  "next_page" : 
                  {
                      "url" : "voicemailoption1page"
                  }
              },
              {
                  "digit"  : "2",
                  "speech" : "two",
                  "next_page" : 
                  {
                      "url" : "voicemailoption2page"
                  }
              },
              {
                  "digit"  : "3",
                  "speech" : "three",
                  "next_page" : 
                  {
                      "url" : "voicemailoption3page"
                  }
              }
          ],
          "help_digit" : "#",
          "help_word"  : "repeat",
          "seconds_input_timeout" : 10,
          "on_input_timeout_messages" :
          [
              {
                  "play" :
                  {
                      "play_list" :
                      [   
                          {
                              "text_to_say" : "I didn't catch your entry."
                          }
                      ]
                  },
                  "play" :
                  {
                      "play_list" :
                      [   
                          {
                              "text_to_say" : "Please select an option."
                          }
                      ]
                  },
                  "play" :
                  {
                      "play_list" :
                      [   
                          {
                              "file_to_play" : "oneMoreTime.wav"
                          }
                      ]
                  }
              }
          ],
          "on_invalid_input_messages" : 
          [
              {
                  "play" :
                  {
                      "play_list" :
                      [   
                          {
                              "text_to_say" : "That wasn't one of the options. Please try again."
                          }
                      ]
                  },
                  "play" :
                  {
                      "play_list" :
                      [   
                          {
                              "file_to_play" : "oneMoreTime.wav"
                          }
                      ]
                  }
              }
          ]
      }
      

      The following may be returned when an option is selected:

      "action_result" :
      {
          "action" : "run_speech_menu",
          "result" :
          {
              "selected_speech" : "three",
              "selected_digit" : "3",
              "selected_input_type" : "digit"
          }
      }
      
  • API Reference:

    class RunSpeechMenu : TelephonyAction

    Represents a run speech menu action.

    Constructors:

    RunSpeechMenu(Play prompt, List<SpeechMenuOption> options);
    

    Members:

    char HelpDigit;
    String HelpWord;
    int SecondsInputTimeout;
    List<Play> OnInputTimeoutMessages;
    List<Play> OnInvalidInputMessages;
    
    class SpeechMenuOption

    Represents a single option that can be selected in a menu.

    Constructors:

    SpeechMenuOption(String speech, char digit, WebPageRequest nextPage);
    
    class WebPageRequest

    Represents a request to a web page.

    Constructors:

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

    Members:

    String Method;
    
    class RunSpeechMenuResult : ActionResult

    Represents the result of a run speech menu action.

    Members:

    String SelectedSpeech;
    char SelectedDigit;
    String SelectedInputType;
    

    Examples:

    • Run a simple yes/no menu using the default parameters:

      Play prompt = Play.SayText("Please say yes or no, or press 1 for yes or 2 for no.");
      List<SpeechMenuOption> options = new List<SpeechMenuOption>();
      options.Add(new SpeechMenuOption("yes", '1', new WebPageRequest("OptionYesPage.aspx")));
      options.Add(new SpeechMenuOption("no", '2', new WebPageRequest("OptionNoPage.aspx")));
      actions.Add(new RunSpeechMenu(prompt, options));
      

      The selection is specified in the request for the next page:

        RunSpeechMenuResult menuResult = (RunSpeechMenuResult)myRequest.InstanceInfo.ActionResult;
        if (menuResult.SelectedSpeech.Equals("one"))
        {
           ...
        }
      
    • Run a menu with three options specifying all parameters:

      Play prompt = Play.PlayFile("voicemailmenu.wav");
      List<SpeechMenuOption> options = new List<SpeechMenuOption>();
      options.Add(new SpeechMenuOption("one", '1', new WebPageRequest("VoicemailOption1Page.aspx")));
      options.Add(new SpeechMenuOption("two", '2', new WebPageRequest("VoicemailOption2Page.aspx")));
      options.Add(new SpeechMenuOption("three", '3', new WebPageRequest("VoicemailOption3Page.aspx")));
      RunSpeechMenu runSpeechMenuAction = new RunSpeechMenu(prompt, options);
      
      runSpeechMenuAction.HelpDigit = '#';
      runSpeechMenuAction.HelpWord = "help";
      runSpeechMenuAction.SecondsDigitTimeout = 10;
      
      // Set up some new info messages for no entry and invalid entry
      runSpeechMenuAction.OnInputTimeoutMessages = new List<Play>();
      runSpeechMenuAction.OnInputTimeoutMessages.Add(Play.SayText("I didn't catch your entry."));
      runSpeechMenuAction.OnInputTimeoutMessages.Add(Play.SayText("Please say or select an option."));
      runSpeechMenuAction.OnInputTimeoutMessages.Add(Play.PlayFile("oneMoreTime.wav"));
      runSpeechMenuAction.OnInvalidInputMessages = new List<Play>();
      runSpeechMenuAction.OnInvalidInputMessages.Add(Play.SayText("That wasn't one of the options. Please try again."));
      runSpeechMenuAction.OnInvalidInputMessages.Add(Play.PlayFile("oneMoreTime.wav"));
      
      actions.Add(runSpeechMenuAction);
      
  • API Reference:

    Class RunSpeechMenu Inherits TelephonyAction

    Represents a run speech menu action.

    Constructors:

    New(prompt As RestAPIWrapper.Play, options As List(Of RestAPIWrapper.SpeechMenuOption) )
    

    Members:

    HelpDigit As Char
    HelpWord As String
    SecondsDigitTimeout As Integer
    OnInputTimeoutMessages As List(Of RestAPIWrapper.Play)
    OnInvalidInputMessages As List(Of RestAPIWrapper.Play) 
    
    Class SpeechMenuOption

    Represents a single option that can be selected in a menu.

    Constructors:

    New(speech as String, digit As Char, nextpage As RestAPIWrapper.WebPageRequest)
    
    Class WebPageRequest

    Represents a request to a web page.

    Constructors:

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

    Members:

    Method As String
    
    Class RunSpeechMenuResult Inherits RestAPIWrapper.ActionResult

    Represents the result of a run speech menu action.

    Members:

    SelectedSpeech As String
    SelectedDigit As Char
    SelectedInputType As String
    

    Examples:

    • Run a simple yes/no menu using the default parameters:

      Dim prompt As Play = Play.SayText("Please say yes or no, or press 1 for yes or 2 for no.")
      Dim options As List(Of SpeechMenuOption) = New List(Of SpeechMenuOption)
      options.Add(New SpeechMenuOption("yes", "1", New WebPageRequest("OptionYesPage.aspx")))
      options.Add(New SpeechMenuOption("no", "2", New WebPageRequest("OptionNoPage.aspx")))
      actions.Add(New SpeechRunMenu(prompt, options))
      

      The selection is specified in the request for the next page:

        Dim menuResult As RunSpeechMenuResult = myRequest.InstanceInfo.ActionResult
        Dim selection As String = menuResult.SelectedSpeech
        ...
      
    • Run a menu with three options specifying all parameters:

      Dim prompt As Play = Play.PlayFile("voicemailmenu.wav")
      Dim options As List(Of SpeechMenuOption)  = New List(Of SpeechMenuOption)
      options.Add(New SpeechMenuOption("one", "1", New WebPageRequest("VoicemailOption1Page.aspx")))
      options.Add(New SpeechMenuOption("two", "2", New WebPageRequest("VoicemailOption2Page.aspx")))
      options.Add(New SpeechMenuOption("three", "3", New WebPageRequest("VoicemailOption3Page.aspx")))
      Dim runSpeechMenuAction As RunSpeechMenu = New RunSpeechMenu(prompt, options)
      
      runSpeechMenuAction.HelpDigit = "#"
      runSpeechMenuAction.HelpWord = "Help"
      runSpeechMenuAction.SecondsDigitTimeout = 10
      
      ' Set up some new info messages for no entry and invalid entry
      runSpeechMenuAction.OnInputTimeoutMessages = New List(Of Play)
      runSpeechMenuAction.OnInputTimeoutMessages.Add(Play.SayText("I didn't catch your entry."))
      runSpeechMenuAction.OnInputTimeoutMessages.Add(Play.SayText("Please select an option."))
      runSpeechMenuAction.OnInputTimeoutMessages.Add(Play.PlayFile("oneMoreTime.wav"))
      runSpeechMenuAction.OnInvalidInputMessages = New List(Of Play)
      runSpeechMenuAction.OnInvalidInputMessages.Add(Play.SayText("That wasn't one of the options. Please try again."))
      runSpeechMenuAction.OnInvalidInputMessages.Add(Play.PlayFile("oneMoreTime.wav"))
      
      actions.Add(runSpeechMenuAction)
      
  • API Reference:

    class RunSpeechMenu extends TelephonyAction

    Represents a run speech menu action.

    Constructors:

    RunSpeechMenu(Play prompt, List<SpeechMenuOption> options);
    

    Members:

    setHelpDigit(char helpDigit);
    setHelpWord(String helpWord);
    setSecondsDigitTimeout(int secondsTimeout);
    setOnInputTimeoutMessages(List<Play> messages);
    setOnInvalidInputMessages(List<Play> messages);
    
    class SpeechMenuOption

    Represents a single option that can be selected in a menu.

    Constructors:

    SpeechMenuOption(String speech, char digit, WebPageRequest nextPage);
    
    class WebPageRequest

    Represents a request to a web page.

    Constructors:

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

    Members:

    setMethod(String method);
    
    class RunSpeechMenuResult extends ActionResult

    Represents the result of a run speech menu action.

    Members:

    String getSelectedSpeech();
    char getSelectedDigit();
    String getSelectedInputType();
    

    Examples:

    • Run a simple yes/no menu using the default parameters:

      Play prompt = Play.sayText("Please say yes or no, or press 1 for yes or 2 for no.");
      List<SpeechMenuOption> options = new ArrayList<SpeechMenuOption>();
      options.add(new SpeechMenuOption("yes", '1', new WebPageRequest("optionYesPage")));
      options.add(new SpeechMenuOption("no", '2', new WebPageRequest("optionNoPage")));
      actions.add(new SpeechRunMenu(prompt, options));
      

      The selection is specified in the request for the next page:

      public void doGet(HttpServletRequest request, HttpServletResponse response) 
      {
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        RunSpeechMenuResult menuResult = (RunSpeechMenuResult)ourRequest.getInstanceInfo().getActionResult();
        if (menuResult.getSelectedSpeech().equals("one"))
          ...
      }
      
    • Run a menu with three options specifying all parameters:

      Play prompt = Play.playFile("voicemailmenu.wav")
      List<SpeechMenuOption> options = new ArrayList<SpeechMenuOption>();
      options.add(new SpeechMenuOption("one", '1', new WebPageRequest("VoicemailOption1Page")));
      options.add(new SpeechMenuOption("two", '2', new WebPageRequest("VoicemailOption2Page")));
      options.add(new SpeechMenuOption("three", '3', new WebPageRequest("VoicemailOption3Page")));
      RunSpeechMenu runSpeechMenuAction = new RunSpeechMenu(prompt, options);
      
      runSpeechMenuAction.setHelpDigit('#');
      runSpeechMenuAction.setHelpWord("help");
      runSpeechMenuAction.setSecondsDigitTimeout(10);
      
      // Set up some new info messages for no entry and invalid entry
      List<Play> onInputTimeoutMessages = new ArrayList<Play>();
      onInputTimeoutMessages.add(Play.sayText("I didn't catch your entry."));
      onInputTimeoutMessages.add(Play.sayText("Please select an option."));
      onInputTimeoutMessages.add(Play.playFile("oneMoreTime.wav"));
      runSpeechMenuAction.setOnInputTimeoutMessages(onInputTimeoutMessages);
      
      List<Play> onInvalidInputMessages = new ArrayList<Play>();
      onInvalidInputMessages.add(Play.sayText("That wasn't one of the options. Please try again."));
      onInvalidInputMessages.add(Play.playFile("oneMoreTime.wav"));
      runSpeechMenuAction.setOonInvalidInputMessages(onInvalidInputMessages);
      
      actions.add(runSpeechMenuAction);
      
  • API Reference:

    class RunMenu

    Represents a run menu action.

    Constructors:

    RunSpeechMenu()
    

    Members:

    def append_menu_option(digit, speech, next_page) # next_page is a WebPage object, see Redirect() for details
    def set_menu_options(digits, speech_list, next_page) # next_page is a WebPage object
    def on_prompt_play(play_action) # A Play object, see Play() for details
    def set_help_digit(help_digit)
    def set_help_word(help_word)
    def set_seconds_input_timeout(seconds_input_timeout)
    def append_on_input_timeout_message(play_action) # A Play object
    def append_on_invalid_input_message(play_action) # A Play object
    

    Examples:

    • Run a simple yes/no menu using the default parameters:

      from aculab.telephony_rest_api import *
      
      my_actions = Actions(token='Usage example 1: RunSpeechMenu')
      
      my_menu = RunSpeechMenu()
      my_menu.on_prompt_play(Play(text_to_say='Please say yes or no. Or press 1 for yes or 2 for no.'))
      my_menu.append_menu_option('1', 'yes', WebPage(url='option_yes_page'))
      my_menu.append_menu_option('2', 'no', WebPage(url='option_no_page'))
      my_actions.add(my_menu)
      
      response_body = my_actions.get_json()
      
    • Run a menu with three options specifying all parameters:

      from aculab.telephony_rest_api import Actions, Play, RunSpeechMenu
      
      my_actions = Actions(token='Usage example 2: RunSpeechMenu')
      
      my_menu = RunSpeechMenu()
      my_menu.on_prompt_play(Play(file_to_play='voicemailmenu.wav'))
      
      my_menu.append_menu_option('1',  'one', WebPage(url='voicemail_option1_page'))
      my_menu.append_menu_option('2',  'two', WebPage(url='voicemail_option2_page'))
      my_menu.append_menu_option('3',  'three', WebPage(url='voicemail_option3_page'))
      
      my_menu.set_help_digit('#')
      my_menu.set_help_word('repeat')
      my_menu.set_seconds_input_timeout(10)
      
      my_menu.append_on_input_timeout_message(Play(text_to_say='I didn't catch your entry.'))
      my_menu.append_on_input_timeout_message(Play(text_to_say='Please select an option.'))
      my_menu.append_on_input_timeout_message(Play(file_to_play='oneMoreTime.wav'))
      my_menu.append_on_invalid_input_message(Play(text_to_say='That wasn't one of the options. Please try again.'))
      my_menu.append_on_invalid_input_message(Play(file_to_play='oneMoreTime.wav'))
      my_actions.add(my_menu)
      
      response_body = my_actions.get_json()
      
  • API Reference:

    The RunSpeechMenu class

    Introduction

    Represents a run speech menu action.

    Class synopsis

    class RunSpeechMenu extends ActionBase {
    
        /* Methods */
        public __construct(Play $prompt)
        public void addSpeechMenuOption(string $speech, string $digit, string $next_page = null, string $method = null)
        public void setHelpDigit(string $helpDigit)
        public void setHelpWord(string $helpWord)
        public void setInputTimeout(int $seconds)
        public void setOnInputTimeoutMessages(MessageList $messages)
        public void setOnInvalidInputMessages(MessageList $messages)
    }
    
    The MessageList class

    Introduction

    Represents a list of messages.

    Class synopsis

    class MessageList {
    
        /* Methods */
        public __construct()
        public void addMessage(Play $play)
    }
    
    The RunSpeechMenuResult class

    Introduction

    Represents the result of a run speech menu action.

    Class synopsis

    class RunSpeechMenuResult extends ActionResult {
    
        /* Methods */
        public string getSelectedDigit()
        public string getSelectedSpeech()
        public string getSelectedInputType()
        
        /* inherited methods */
        public string getAction()
        public boolean getInterrupted()
    }
    

    Examples:

    • Run a simple yes/no menu using the defaults:

      $mp = new Aculab\TelephonyRestAPI\Play();
      $mp->addText('Please say yes or no. Or press 1 for yes and 2 for no.');
      $menu = new Aculab\TelephonyRestAPI\RunSpeechMenu($mp);
      $menu->addSpeechMenuOption('yes', '1', 'optionyespage');
      $menu->addSpeechMenuOption('no', '2', 'optionnopage');
      $actions->add($menu);
      

      Obtain the selected option from the action's next page request:

      $info = InstanceInfo::getInstanceInfo();
      $speechMenuResult = $info->getActionResult();
      $selectedInputType = $speechMenuResult->getSelectedInputType();
      $selectedDigit = $speechMenuResult->getSelectedDigit();
      $selectedSpeech = $speechMenuResult->getSelectedSpeech();
      
    • Run a menu with three options, specifying non-default parameters:

      $mp = new Aculab\TelephonyRestAPI\Play();
      $mp->addFile('voicemailmenu.wav');
      $menu = new Aculab\TelephonyRestAPI\RunMenu($mp);
      $menu->addSpeechMenuOption('one', '1', 'voicemailOption1Page');
      $menu->addSpeechMenuOption('two', '2', 'voicemailOption2Page');
      $menu->addSpeechMenuOption('three', '3', 'voicemailOption3Page');
      $menu->setHelpDigit('#');
      $menu->setHelpWord('repeat');
      $menu->setSecondsInputTimeout(10);
      
      $onInputTimeoutMessages = new Aculab\TelephonyRestAPI\MessageList();
      $onInputTimeoutMessages->addMessage(Aculab\TelephonyRestAPI\Play::sayText('I didn't catch your entry.'));
      $onInputTimeoutMessages->addMessage(Aculab\TelephonyRestAPI\Play::sayText('Please select an option.'));
      $onInputTimeoutMessages->addMessage(Aculab\TelephonyRestAPI\Play::playFile('oneMoreTime.wav'));
      $menu->setOnInputTimeoutMessages($onInputTimeoutMessages);
      
      $onInvalidInputMessages = new Aculab\TelephonyRestAPI\MessageList();
      $onInvalidInputMessages->addMessage(Aculab\TelephonyRestAPI\Play::sayText('That wasn't one of the options. Please try again.'));
      $onInvalidInputMessages->addMessage(Aculab\TelephonyRestAPI\Play::playFile('oneMoreTime.wav'));
      $menu->setOnInvalidInputMessages($onInvalidInputMessages);
      
      $actions->add($menu);
      

      Obtain the selected option from the action's next page request:

      $info = InstanceInfo::getInstanceInfo();
      $speechMenuResult = $info->getActionResult();
      $selectedInputType = $speechMenuResult->getSelectedInputType();
      $selectedDigit = $speechMenuResult->getSelectedDigit();
      $selectedSpeech = $speechMenuResult->getSelectedSpeech();