right  Talk To Us!

run menu Action

Runs an interactive menu that requests 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 pressing a single digit. For example "Press one for blue or two for red."


The run menu properties are:

PropertyRequired/OptionalDefaultDescription
prompt required - A play action. This is the prompt that requests a digit to be selected.
menu options required - An array of menu option objects, each specifying a Dual Tone Multi Frequency (DTMF) digit 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#*.
seconds digit timeout optional 5 An integer. The time period in seconds that the run menu action waits for a digit to be selected.
on digit timeout messages optional "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 run menu action finishes. Note that barge in is disabled by default for these actions.
on invalid digit messages optional "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.

The menu option properties are:

PropertyRequired/OptionalDefaultDescription
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 is pressed. 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 digit A string containing the single digit that was selected in response to the menu prompt.
 See also: Simple Run Menu, Voice Broadcast, Voicemail

  • 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"
    }
}

  • API Reference:

    class RunMenu : TelephonyAction

    Represents a run menu action.

    Constructors:

    RunMenu(Play prompt, List<MenuOption> options);

    Members:

    char HelpDigit;
int SecondsDigitTimeout;
List<Play> OnDigitTimeoutMessages;
List<Play> OnInvalidDigitMessages;
    class MenuOption

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

    Constructors:

    MenuOption(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 RunMenuResult : ActionResult

    Represents the result of a run menu action.

    Members:

    char SelectedDigit;

    Examples:

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

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

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

        RunMenuResult menuResult = (RunMenuResult)myRequest.InstanceInfo.ActionResult;
  char selection = menuResult.SelectedDigit;
  ...

    • Run a menu with three options specifying all parameters:

      Play prompt = Play.PlayFile("voicemailmenu.wav");
List<MenuOption> options = new List<MenuOption>();
options.Add(new MenuOption('1', new WebPageRequest("VoicemailOption1Page.aspx")));
options.Add(new MenuOption('2', new WebPageRequest("VoicemailOption2Page.aspx")));
options.Add(new MenuOption('3', new WebPageRequest("VoicemailOption3Page.aspx")));
RunMenu runMenuAction = new RunMenu(prompt, options);

runMenuAction.HelpDigit = '#';
runMenuAction.SecondsDigitTimeout = 10;

// Set up some new info messages for no entry and invalid entry
runMenuAction.OnDigitTimeoutMessages = new List<Play>();
runMenuAction.OnDigitTimeoutMessages.Add(Play.SayText("I didn't catch your entry."));
runMenuAction.OnDigitTimeoutMessages.Add(Play.SayText("Please select an option."));
runMenuAction.OnDigitTimeoutMessages.Add(Play.PlayFile("oneMoreTime.wav"));
runMenuAction.OnInvalidDigitMessages = new List<Play>();
runMenuAction.OnInvalidDigitMessages.Add(Play.SayText("That wasn't one of the options. Please try again."));
runMenuAction.OnInvalidDigitMessages.Add(Play.PlayFile("oneMoreTime.wav"));

actions.Add(runMenuAction);

  • API Reference:

    Class RunMenu Inherits TelephonyAction

    Represents a run menu action.

    Constructors:

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

    Members:

    HelpDigit As Char
SecondsDigitTimeout As Integer
OnDigitTimeoutMessages As List(Of RestAPIWrapper.Play)
OnInvalidDigitMessages As List(Of RestAPIWrapper.Play)
    Class MenuOption

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

    Constructors:

    New(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 RunMenuResult Inherits RestAPIWrapper.ActionResult

    Represents the result of a run menu action.

    Members:

    SelectedDigit As Char

    Examples:

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

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

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

        Dim menuResult As RunMenuResult = myRequest.InstanceInfo.ActionResult
  Dim selection As Char = menuResult.SelectedDigit
  ...

    • Run a menu with three options specifying all parameters:

      Dim prompt As Play = Play.PlayFile("voicemailmenu.wav")
Dim options As List(Of MenuOption)  = New List(Of MenuOption)
options.Add(New MenuOption("1", New WebPageRequest("VoicemailOption1Page.aspx")))
options.Add(New MenuOption("2", New WebPageRequest("VoicemailOption2Page.aspx")))
options.Add(New MenuOption("3", New WebPageRequest("VoicemailOption3Page.aspx")))
Dim runMenuAction As RunMenu = New RunMenu(prompt, options)

runMenuAction.HelpDigit = "#"
runMenuAction.SecondsDigitTimeout = 10

' Set up some new info messages for no entry and invalid entry
runMenuAction.OnDigitTimeoutMessages = New List(Of Play)
runMenuAction.OnDigitTimeoutMessages.Add(Play.SayText("I didn't catch your entry."))
runMenuAction.OnDigitTimeoutMessages.Add(Play.SayText("Please select an option."))
runMenuAction.OnDigitTimeoutMessages.Add(Play.PlayFile("oneMoreTime.wav"))
runMenuAction.OnInvalidDigitMessages = New List(Of Play)
runMenuAction.OnInvalidDigitMessages.Add(Play.SayText("That wasn't one of the options. Please try again."))
runMenuAction.OnInvalidDigitMessages.Add(Play.PlayFile("oneMoreTime.wav"))

actions.Add(runMenuAction)

  • API Reference:

    class RunMenu extends TelephonyAction

    Represents a run menu action.

    Constructors:

    RunMenu(Play prompt, List<MenuOption> options);

    Members:

    setHelpDigit(char helpDigit);
setSecondsDigitTimeout(int secondsTimeout);
setOnDigitTimeoutMessages(List<Play> messages);
setOnInvalidDigitMessages(List<Play> messages);
    class MenuOption

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

    Constructors:

    MenuOption(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 RunMenuResult extends ActionResult

    Represents the result of a run menu action.

    Members:

    char getSelectedDigit();

    Examples:

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

      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));

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

      public void doGet(HttpServletRequest request, HttpServletResponse response) 
{
  TelephonyRequest ourRequest = new TelephonyRequest(request);
  RunMenuResult menuResult = (RunMenuResult)ourRequest.getInstanceInfo().getActionResult();
  char selection = menuResult.getSelectedDigit();
  ...
}

    • Run a menu with three options specifying all parameters:

      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")));
RunMenu runMenuAction = new RunMenu(prompt, options);

runMenuAction.setHelpDigit('#');
runMenuAction.setSecondsDigitTimeout(10);

// Set up some new info messages for no entry and invalid entry
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"));
runMenuAction.setOnDigitTimeoutMessages(onDigitTimeoutMessages);

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"));
runMenuAction.setOonInvalidDigitMessages(onInvalidDigitMessages);

actions.add(runMenuAction);

  • API Reference:

    class RunMenu

    Represents a run menu action.

    Constructors:

    RunMenu()

    Members:

    def append_menu_option(digit, next_page) # next_page is a WebPage object, see Redirect() for details
def set_menu_options(digits, 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_seconds_digit_timeout(seconds_digit_timeout)
def append_on_digit_timeout_message(play_action) # A Play object
def append_on_invalid_digit_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: RunMenu')

my_menu = RunMenu()
my_menu.on_prompt_play(Play(text_to_say='Please press 1 for yes or 2 for no.'))
my_menu.append_menu_option('1', WebPage(url='option_yes_page'))
my_menu.append_menu_option('2', 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, RunMenu

my_actions = Actions(token='Usage example 2: RunMenu')

my_menu = RunMenu()
my_menu.on_prompt_play(Play(file_to_play='voicemailmenu.wav'))

my_menu.append_menu_option('1',  WebPage(url='voicemail_option1_page'))
my_menu.append_menu_option('2',  WebPage(url='voicemail_option2_page'))
my_menu.append_menu_option('3',  WebPage(url='voicemail_option3_page'))

my_menu.set_help_digit('#')
my_menu.set_seconds_digit_timeout(10)

my_menu.append_on_digit_timeout_message(Play(text_to_say='I didn't catch your entry.'))
my_menu.append_on_digit_timeout_message(Play(text_to_say='Please select an option.'))
my_menu.append_on_digit_timeout_message(Play(file_to_play='oneMoreTime.wav'))
my_menu.append_on_invalid_digit_message(Play(text_to_say='That wasn't one of the options. Please try again.'))
my_menu.append_on_invalid_digit_message(Play(file_to_play='oneMoreTime.wav'))
my_actions.add(my_menu)

response_body = my_actions.get_json()

  • API Reference:

    The RunMenu class

    Introduction

    Represents a run menu action.

    Class synopsis

    class RunMenu extends ActionBase {

    /* Methods */
    public __construct(Play $prompt)
    public void addMenuOption(string $digit, string $next_page = null, string $method = null)
    public void setHelpDigit(string $helpDigit)
    public void setDigitTimeout(int $seconds)
    public void setOnDigitTimeoutMessages(MessageList $messages)
    public void setOnInvalidDigitMessages(MessageList $messages)
}
    The MessageList class

    Introduction

    Represents a list of messages.

    Class synopsis

    class MessageList {

    /* Methods */
    public __construct()
    public void addMessage(Play $play)
}
    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($mp);
$menu->addMenuOption('1', 'optionyespage');
$menu->addMenuOption('2', 'optionnopage');
$actions->add($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($mp);
$menu->addMenuOption('1', 'voicemailOption1Page');
$menu->addMenuOption('2', 'voicemailOption2Page');
$menu->addMenuOption('3', 'voicemailOption3Page');
$menu->setHelpDigit('#');
$menu->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);

$actions->add($menu);

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

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

Contact Aculab

+44 (0) 1908 273800 (UK)

+1 (781) 352 3550 (USA)

This email address is being protected from spambots. You need JavaScript enabled to view it.

This email address is being protected from spambots. You need JavaScript enabled to view it.

This email address is being protected from spambots. You need JavaScript enabled to view it.