Run Menu | Aculab

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:

Property	Required/Optional	Default	Description
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:

Property	Required/Optional	Default	Description
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:

Property	Required/Optional	Default	Description
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:

Property	Description
selected digit	A string containing the single digit that was selected in response to the menu prompt.

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:

Example 1
Example 2

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:

Example 1
Example 2

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:

Example 1
Example 2

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:

Example 1
Example 2

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:

Example 1
Example 2

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.

Cloud documentation

Returns

Examples:

API Reference:

Constructors:

Members:

Constructors:

Constructors:

Members:

Members:

Examples:

API Reference:

Constructors:

Members:

Constructors:

Constructors:

Members:

Members:

Examples:

API Reference:

Constructors:

Members:

Constructors:

Constructors:

Members:

Members:

Examples:

API Reference:

Constructors:

Members:

Examples:

API Reference:

Introduction

Class synopsis

Introduction

Class synopsis

Introduction

Class synopsis

Examples:

Contact Aculab