Run Speech Menu

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:

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

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

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 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'.

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:

Example 1
Example 2

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:

Example 1
Example 2

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:

Example 1
Example 2

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:

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: 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:

Example 1
Example 2

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