By using the Aculab site, you agree with our use of cookies.

run menu Action

Runs an interactive menu that accepts a single digit key press from the caller. You can configure a prompt and a number of menu options and the caller is expected to respond by pressing a single digit. For example "Press one for blue or two for red."

language wrappers and examples

The run menu properties are:

PropertyRequired/OptionalDefaultDescription
menu optionsrequiredAn array of menu option objects, each specifying a Dual Tone Multi Frequency (DTMF) digit and an associated next page.
promptoptional-A play action. This is the prompt that requests a digit to be selected.
help digitoptional"*"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#*.
seconds digit timeoutoptional5An integer. The time period in seconds that the run menu action waits for a digit to be selected.
on digit timeout messagesoptional"Sorry, I did not hear that.",
"Please listen to the instructions and then use your telephone keypad to enter a valid number."
An array of play actions. This defines messages to play if no digit is pressed within the digit timeout period. Each play action in the array is played once for each successive timeout. When all messages have been played the action finishes. Note that barge in is disabled by default for these actions.
on invalid digit messagesoptional"Sorry, that was not a valid number.",
"Please listen to the instructions and enter a valid number."
An array of play actions. This defines messages to play if an invalid digit is pressed. Each play action in the array is played once for each successive invalid digit. When all messages have been played the run menu action finishes. Note that barge in is disabled by default for these actions.

Remarks

run menu supports typing ahead. It inspects any digits that may have already been cached from barge in on a preceding play action. If this matches one of the menu options this action will return the selection immediately without playing the prompt.

To avoid this behaviour you can insert a clear input action after the play action.

Returns

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

PropertyAvailabilityDescription
selected digitalwaysA string containing the single digit that was selected in response to the menu prompt.



  • Examples:

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

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

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

      "action_result" :
      {
          "action" : "run_menu",
          "result" :
          {
              "selected_digit" : "2"
          }
      }
      
    • 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",
                  "next_page" : 
                  {
                      "url" : "voicemailoption1page"
                  }
              },
              {
                  "digit" : "2",
                  "next_page" : 
                  {
                      "url" : "voicemailoption2page"
                  }
              },
              {
                  "digit" : "3",
                  "next_page" : 
                  {
                      "url" : "voicemailoption3page"
                  }
              }
          ],
          "help_digit" : "#",
          "seconds_digit_timeout" : 10,
          "on_digit_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_digit_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_menu",
          "result" :
          {
              "selected_digit" : "3"
          }
      }
      
  • RunMenu Class
    Namespace: Aculab.Cloud.RestAPIWrapper
    Assembly: Aculab.Cloud.RestAPIWrapper.dll

    An action to run a menu prompting the user for a selection via a keypress.

    public class RunMenu : TelephonyAction
    {
        // Constructors
        [Obsolete] public RunMenu(Play prompt, List<MenuOption> options);
        public RunMenu(List<MenuOption> options, Play prompt = null);
    
        // Members
        public Play Prompt;
        public char HelpDigit;
        public int SecondsDigitTimeout;
        public List<Play> OnDigitTimeoutMessages;
        public List<Play> OnInvalidDigitMessages;
    }
    

    Examples:

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

      List<TelephonyAction> actions = new List<TelephonyAction>();
      
      var prompt = Play.SayText("Please press 1 for yes and 2 for no.");
      
      var menuOptions = new List<MenuOption>
      {
          new MenuOption('1', new WebPageRequest("OptionYesPage.aspx")),
          new MenuOption('2', new WebPageRequest("OptionNoPage.aspx"))
      };
      
      var runMenu = new RunMenu(menuOptions, prompt);
      
      actions.Add(runMenu);
      

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

      // Unpack the request
      var telephonyRequest = new TelephonyRequest(Request);
      
      var runMenuResult = (RunMenuResult)telephonyRequest.InstanceInfo.ActionResult;
      var selectedOption = runMenuResult.SelectedDigit;
      
    • Run a menu with three options, specifying non-default parameters:

      List<TelephonyAction> actions = new List<TelephonyAction>();
      
      var prompt = Play.PlayFile("voicemailmenu.wav");
      var menuOptions = new List<MenuOption>
      {
          new MenuOption('1', new WebPageRequest("VoicemailOption1.aspx")),
          new MenuOption('2', new WebPageRequest("VoicemailOption2.aspx")),
          new MenuOption('3', new WebPageRequest("VoicemailOption3.aspx"))
      };
      var runMenu = new RunMenu(menuOptions, prompt);
      runMenu.HelpDigit = '#';
      runMenu.SecondsDigitTimeout = 10;
      
      var digitTimeoutMessages = new List<Play>
      {
          Play.SayText("I didn't catch your entry."),
          Play.SayText("Please select an option."),
          Play.PlayFile("oneMoreTime.wav")
      };
      runMenu.OnDigitTimeoutMessages = digitTimeoutMessages;
      
      var invalidDigitMessages = new List<Play>
      {
          Play.SayText("That wasn't one of the options. Please try again."),
          Play.PlayFile("oneMoreTime.wav")
      };
      runMenu.OnInvalidDigitMessages = invalidDigitMessages;
      
      actions.Add(runMenu);
      

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

      // Unpack the request
      var telephonyRequest = new TelephonyRequest(Request);
      
      var runMenuResult = (RunMenuResult)telephonyRequest.InstanceInfo.ActionResult;
      var selectedOption = runMenuResult.SelectedDigit;
      
  • RunMenu Class
    Namespace: Aculab.Cloud.RestAPIWrapper
    Assembly: Aculab.Cloud.RestAPIWrapper.dll

    An action to run a menu prompting the user for a selection via a keypress.

    Public Class RunMenu
        Inherits TelephonyAction
    
        ' Constructors
        [Obsolete] Public Sub New (prompt As Play, options As List(Of Menuoption))
        Public Sub New (options As List(Of Menuoption), Optional prompt As Play = Nothing)
    
        ' Members
        Public Property Prompt As Play
        Public Property HelpDigit As Char
        Public Property SecondsDigitTimeout As Integer
        Public Property OnDigitTimeoutMessages As List(Of Play)
        Public Property OnInvalidDigitMessages As List(Of Play)
    End Class
    

    Examples:

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

      Dim actions = New List(Of TelephonyAction)
      
      Dim prompt = Play.SayText("Please press 1 for yes and 2 for no.")
      
      Dim menuOptions = New List(Of MenuOption)
      menuOptions.Add(New MenuOption("1", New WebPageRequest("OptionYesPage.aspx")))
      menuOptions.Add(New MenuOption("2", New WebPageRequest("OptionNoPage.aspx")))
      
      Dim runMenu = New RunMenu(menuOptions, prompt)
      
      actions.Add(runMenu)
      

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

      ' Unpack the request
      Dim telephonyRequest = New TelephonyRequest(Request)
      
      Dim runMenuResult As RunMenuResult = telephonyRequest.InstanceInfo.ActionResult
      Dim selectedOption = RunMenuResult.SelectedDigit
      
    • Run a menu with three options, specifying non-default parameters:

      Dim actions = New List(Of TelephonyAction)
      
      Dim prompt = Play.PlayFile("voicemailmenu.wav")
      Dim menuOptions = New List(Of MenuOption)
      menuOptions.Add(New MenuOption("1", New WebPageRequest("VoicemailOption1.aspx")))
      menuOptions.Add(New MenuOption("2", New WebPageRequest("VoicemailOption2.aspx")))
      menuOptions.Add(New MenuOption("3", New WebPageRequest("VoicemailOption3.aspx")))
      
      Dim runMenu = New RunMenu(menuOptions, prompt)
      runMenu.HelpDigit = "#"
      runMenu.SecondsDigitTimeout = 10
      
      Dim digitTimeoutMessages = New List(Of Play)
      digitTimeoutMessages.Add(Play.SayText("I didn't catch your entry."))
      digitTimeoutMessages.Add(Play.SayText("Please select an option."))
      digitTimeoutMessages.Add(Play.PlayFile("oneMoreTime.wav"))
      runMenu.OnDigitTimeoutMessages = digitTimeoutMessages
      
      Dim invalidDigitMessages = New List(Of Play)
      invalidDigitMessages.Add(Play.SayText("That wasn't one of the options. Please try again."))
      invalidDigitMessages.Add(Play.PlayFile("oneMoreTime.wav"))
      runMenu.OnInvalidDigitMessages = invalidDigitMessages
      
      actions.Add(runMenu)
      

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

      ' Unpack the request
      Dim telephonyRequest = New TelephonyRequest(Request)
      
      Dim runMenuResult As RunMenuResult = telephonyRequest.InstanceInfo.ActionResult
      Dim selectedOption = runMenuResult.SelectedDigit
      
  • class RunMenu extends TelephonyAction

    Represents a run menu action.

    Class synopsis:

    // Constructors:
    public RunMenu(Play prompt, List<MenuOption> options)
    public RunMenu(List<MenuOption> options)
    
    // Members:
    public void setPrompt(Play prompt)
    public void setHelpDigit(char helpDigit)
    public void setSecondsDigitTimeout(int secondsTimeout)
    public void setOnDigitTimeoutMessages(List<Play> messageList)
    public void setOnInvalidDigitMessages(List<Play> messageList)
    public JSONObject toJSONObject()
    
    class RunMenuResult extends ActionResult

    Represents the result of a run menu action.

    Class synopsis:

    // Members:
    public char getSelectedDigit()
    

    Examples:

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

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      Play prompt = Play.sayText("Please press 1 for yes and 2 for no.");
      List<MenuOption> options = new ArrayList<MenuOption>();
      options.add(new MenuOption('1', new WebPageRequest("optionyespage")));
      options.add(new MenuOption('2', new WebPageRequest("optionnopage")));
      
      actions.add(new RunMenu(prompt, options));
      

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

      TelephonyRequest ourRequest = new TelephonyRequest(request);
      RunMenuResult menuResult = (RunMenuResult)ourRequest.getInstanceInfo().getActionResult();
      char selection = menuResult.getSelectedDigit();
      
    • Run a menu with three options, specifying non-default parameters:

      List<TelephonyAction> actions = new ArrayList<TelephonyAction>();
      
      Play prompt = Play.playFile("voicemailmenu.wav");
      
      List<MenuOption> options = new ArrayList<MenuOption>();
      options.add(new MenuOption('1', new WebPageRequest("voicemailoption1page")));
      options.add(new MenuOption('2', new WebPageRequest("voicemailoption2page")));
      options.add(new MenuOption('3', new WebPageRequest("voicemailoption3page")));
      
      // Set up info messages for digit timeout
      List<Play> onDigitTimeoutMessages = new ArrayList<Play>();
      onDigitTimeoutMessages.add(Play.sayText("I didn't catch your entry."));
      onDigitTimeoutMessages.add(Play.sayText("Please select an option."));
      onDigitTimeoutMessages.add(Play.playFile("oneMoreTime.wav"));
      
      // Set up info messages for invalid digit
      List<Play> onInvalidDigitMessages = new ArrayList<Play>();
      onInvalidDigitMessages.add(Play.sayText("That wasn't one of the options. Please try again."));
      onInvalidDigitMessages.add(Play.playFile("oneMoreTime.wav"));
      
      RunMenu runMenuAction = new RunMenu(options);
      runMenuAction.setPrompt(prompt);
      runMenuAction.setHelpDigit('#');
      runMenuAction.setSecondsDigitTimeout(10);
      runMenuAction.setOnDigitTimeoutMessages(onDigitTimeoutMessages);
      runMenuAction.setOnInvalidDigitMessages(onInvalidDigitMessages);
      
      actions.add(runMenuAction);
      

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

      TelephonyRequest ourRequest = new TelephonyRequest(request);
      RunMenuResult menuResult = (RunMenuResult)ourRequest.getInstanceInfo().getActionResult();
      char selection = menuResult.getSelectedDigit();
      
  • class RunMenu

    Represents a run menu action.

    Class synopsis:

    # RunMenu object:
    RunMenu(menu_options)
    
    # Instance methods:
    RunMenu.set_prompt(play_action)
    RunMenu.set_help_digit(help_digit)
    RunMenu.set_seconds_digit_timeout(timeout)
    RunMenu.set_on_digit_timeout_messages(list_of_play_actions)
    RunMenu.set_on_invalid_digit_messages(list_of_play_actions)
    RunMenu.append_menu_option(menu_option)
    
    Run Menu Result

    The Run Menu Result is represented by a dictionary. It is found within the action result for the next page.

    Obtaining the Run Menu Result dictionary:

    my_request = TelephonyRequest(request)
    action_result = my_request.get_action_result()
    if action_result.get("action") == "run_menu":
        run_menu_result =  action_result.get("result")
    

    Examples:

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

      menu_options = []
      menu_options.append(MenuOption('1',WebPage(url='option_yes_page')))
      menu_options.append(MenuOption('2',WebPage(url='option_no_page')))
      
      run_menu_action = RunMenu(menu_options)
      run_menu_action.set_prompt(Play(text_to_say='Please press 1 for yes or 2 for no.'))
      
      my_actions.append(run_menu_action)
      

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

      my_request = TelephonyRequest(request)
      action_result = my_request.get_action_result()
      
      if action_result.get("action") == "run_menu":
      
          run_menu_result =  action_result.get("result")
          selected_digit = run_menu_result.get("selected_digit")
      
          # Your code here...
      
    • Run a menu with three options, specifying non-default parameters:

      menu_options = []
      menu_options.append(MenuOption('1',WebPage(url='voicemail_option1_page')))
      menu_options.append(MenuOption('2',WebPage(url='voicemail_option2_page')))
      menu_options.append(MenuOption('3',WebPage(url='voicemail_option3_page')))
      
      timeout_messages = []
      timeout_messages.append(Play(text_to_say="I didn't catch your entry."))
      timeout_messages.append(Play(text_to_say="Please select an option."))
      timeout_messages.append(Play(file_to_play="oneMoreTime.wav"))
      
      invalid_messages = []
      invalid_messages.append(Play(text_to_say="That wasn't one of the options. Please try again."))
      invalid_messages.append(Play(file_to_play="oneMoreTime.wav"))
      
      run_menu_action = RunMenu(menu_options)
      run_menu_action.set_prompt(Play(file_to_play='voicemailmenu.wav'))
      run_menu_action.set_help_digit('#')
      run_menu_action.set_seconds_digit_timeout(10)
      run_menu_action.set_on_digit_timeout_messages(timeout_messages)
      run_menu_action.set_on_invalid_digit_messages(invalid_messages)
      
      my_actions.append(run_menu_action)
      

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

      my_request = TelephonyRequest(request)
      action_result = my_request.get_action_result()
      
      if action_result.get("action") == "run_menu":
      
          run_menu_result =  action_result.get("result")
          selected_digit = run_menu_result.get("selected_digit")
      
          # Your code here...
      
  • The RunMenu class

    Introduction

    Represents a run menu action.

    Class synopsis

    class RunMenu extends GetNumberBase {
    
        /* methods */
        public __construct(array $opts = null)
        public self addMenuOption(string $digit, WebPageRequest|string $next_page, string $method = null)
        public self setSecondsDigitTimeout(int $secs)
    
        /* inherited methods */
        public self setPrompt(Play $prompt)
        public self setHelpDigit(string $digit)
        public self setOnDigitTimeoutMessages(MessageList $messages)
        public self setOnInvalidDigitMessages(MessageList $messages)
    }
    
    The RunMenuResult class

    Introduction

    Represents the result of a run menu action.

    Class synopsis

    class RunMenuResult extends ActionResult {
    
        /* methods */
        public string getSelectedDigit()
    
        /* 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 press 1 for yes and 2 for no.');
      $menu = new Aculab\TelephonyRestAPI\RunMenu();
      $menu->setPrompt($mp)
          ->addMenuOption('1', 'optionyespage')
          ->addMenuOption('2', 'optionnopage');
      $response->addAction($menu);
      

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

      $info = InstanceInfo::getInstanceInfo();
      $menuResult = $info->getActionResult();
      $selectedOption = $menuResult->getSelectedDigit();
      
    • Run a menu with three options, specifying non-default parameters:

      $mp = new Aculab\TelephonyRestAPI\Play();
      $mp->addFile('voicemailmenu.wav');
      $menu = new Aculab\TelephonyRestAPI\RunMenu();
      $menu->setPrompt($mp)
          ->addMenuOption('1', 'voicemailOption1Page')
          ->addMenuOption('2', 'voicemailOption2Page')
          ->addMenuOption('3', 'voicemailOption3Page')
          ->setHelpDigit('#')
          ->setSecondsDigitTimeout(10);
      
      $onDigitTimeoutMessages = new Aculab\TelephonyRestAPI\MessageList();
      $onDigitTimeoutMessages->addMessage(Aculab\TelephonyRestAPI\Play::sayText("I didn't catch your entry."));
      $onDigitTimeoutMessages->addMessage(Aculab\TelephonyRestAPI\Play::sayText('Please select an option.'));
      $onDigitTimeoutMessages->addMessage(Aculab\TelephonyRestAPI\Play::playFile('oneMoreTime.wav'));
      $menu->setOnDigitTimeoutMessages($onDigitTimeoutMessages);
      
      $onInvalidDigitMessages = new Aculab\TelephonyRestAPI\MessageList();
      $onInvalidDigitMessages->addMessage(Aculab\TelephonyRestAPI\Play::sayText("That wasn't one of the options. Please try again."));
      $onInvalidDigitMessages->addMessage(Aculab\TelephonyRestAPI\Play::playFile('oneMoreTime.wav'));
      $menu->setOnInvalidDigitMessages($onInvalidDigitMessages);
      
      $response->addAction($menu);
      

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

      $info = InstanceInfo::getInstanceInfo();
      $menuResult = $info->getActionResult();
      $selectedOption = $menuResult->getSelectedDigit();