get number Action

Prompts the caller to enter a number and waits for it to be entered. You configure the prompt and how many digits are required, or you configure the digit that signifies the end of the number. The caller is expected to respond by pressing one or more digits.


The get number properties are:

PropertyRequired/OptionalDefaultDescription
prompt required - A play action. This is the prompt that requests the digit(s).
digit count optional 0 The number of digits to enter. 0 signifies an unlimited number of digits, in which case end digit must be set.
end digit optional "#" A single digit that, when pressed, will indicate the end of the number. An empty string signifies no end digit, in which case digit count must not be zero. Valid digits are 0123456789ABCD#*.
valid digits optional "0123456789" A string that represents the set of digits that are deemed to be valid. Note that the help digit and end digit are also valid entries in addition to those set here. Any valid Dual Tone Multi Frequency (DTMF) digit can be included in this string. Valid digits are 0123456789ABCD#*.
help digit optional "*" A single digit that, when pressed, will result in the 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 action waits for each digit to be entered.
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 get number 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 (a digit that is not defined in valid digits). Each play action in the array is played once for each successive invalid digit. When all messages have been played the get number action finishes. Note that barge in is disabled by default for these actions.
next page optional null A web page request object that defines the web page to be requested once the get number action has completed successfully. The digits entered will be sent to this page. If no page is specified then the subsequent action in the action array will be executed and the digits entered will be lost.

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

Returns

The result of the get number action will be returned via the subsequent http request to the next pagein action result as follows:

PropertyDescription
entered number A string of the digits that were entered in response to the prompt. The end digit, if entered, is not returned in this string.
  • Examples:

    • Get a variable length number using the defaults (ending with a '#'):

      "get_number" : 
      {
          "prompt" : 
          {
              "play" :
              {
                  "play_list" :
                  [
                      {
                          "text_to_say" : "Please enter your number followed by a hash."
                      }
                  ]
              }
          },
          "next_page" : 
          {
              "url" : "usenumberpage"
          }
      }
      

      The following may be returned when a number is successfully entered followed by '#':

      "action_result" :
      {
          "action" : "get_number",
          "result" :
          {
              "entered_number" : "0287368394"
          }
      }
      
    • Get a 16 digit number using the defaults:

      "get_number" : 
      {
          "prompt" : 
          {
              "play" :
              {
                  "play_list" :
                  [
                      {
                          "text_to_say" : "Please enter your 16 digit number"
                      }
                  ]
              }
          },
          "digit_count" : 16,
          "end_digit" : "",
          "next_page" : 
          {
              "url" : "usenumberpage"
          }
      }
      

      The following may be returned when a number is successfully entered:

      "action_result" :
      {
          "action" : "get_number",
          "result" :
          {
              "entered_number" : "8825620287368394"
          }
      }
      
    • Get a 4 digit number containing digits 1-8:

      "get_number" : 
      {
          "prompt" : 
          {
              "play" :
              {
                  "play_list" :
                  [
                      {
                          "text_to_say" : "Please enter 4 digits between 1 and 8"
                      }
                  ]
              }
          },
          "digit_count" : 4,
          "end_digit" : "",
          "valid_digits" : "12345678",
          "next_page" : 
          {
              "url" : "usenumberpage"
          }
      }
      

      The following may be returned when a 4 digit number is successfully entered:

      "action_result" :
      {
          "action" : "get_number",
          "result" :
          {
              "entered_number" : "6816"
          }
      }
      
    • Get a variable length number containing digits 0-9, ending with a '#':

      "get_number" : 
      {
          "prompt" : 
          {
              "play" :
              {
                  "play_list" :
                  [
                      {
                          "text_to_say" : "Please enter your id followed by a hash"
                      }
                  ]
              }
          },
          "digit_count" : 0,
          "end_digit" : "#",
          "help_digit" : "*",
          "seconds_digit_timeout" : 10,
          "on_digit_timeout_messages" : 
          [
              {  
                  "play" : 
                  {
                      "play_list" :
                      [
                          "file_to_play" : "silencemessage1.wav"
                      ]
                  }
              },
              {  
                  "play" : 
                  {
                      "play_list" :
                      [
                          "file_to_play" : "silencemessage2.wav"
                      ]
                  }
              }
          ],
          "on_invalid_digit_messages" : 
          [
              {
                  "play" : 
                  {
                      "play_list" :
                      [
                          "text_to_say" : "Please enter only numeric digits followed by a hash"
                      ]
                  }
              },
              {
                  "play" : 
                  {
                      "play_list" :
                      [
                          "text_to_say" : "No really!",
                          "text_to_say" : "Please enter only numeric digits followed by a hash"
                      ]
                  }
              }
          ],
          "next_page" : 
          {
              "url" : "usenumberpage"
          }
      }
      

      The following may be returned when a number is successfully entered followed by a '#':

      "action_result" :
      { 
          "action" : "get_number",
          "result" :
          {
              "entered_number" : "716723"
          }
      }
      
  • API Reference:

    class GetNumber : TelephonyAction

    Represents a get number action.

    Constructors:

    GetNumber(Play prompt);
    GetNumber(Play prompt, WebPageRequest nextPage);
    GetNumber(Play prompt, WebPageRequest nextPage, int digitCount);
    GetNumber(Play prompt, WebPageRequest nextPage, char endDigit);
    

    Members:

    int DigitCount;
    char EndDigit;
    String ValidDigits;
    char HelpDigit;
    int SecondsDigitTimeout;
    List<Play> OnDigitTimeoutMessages;
    List<Play> OnInvalidDigitMessages;
    WebPageRequest NextPage;
    
    class WebPageRequest

    Represents a request to a web page.

    Constructors:

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

    Members:

    String Method;
    
    class GetNumberResult : ActionResult

    Represents the result of a get number action.

    Members:

    String EnteredNumber;
    

    Examples:

    • Get a variable length number using the defaults (ending with a '#'):

      Play prompt = Play.SayText("Please enter your number followed by a hash.");
      actions.Add(new GetNumber(prompt, new WebPageRequest("UseNumberPage.aspx")));
      

      The following may be returned when a number is successfully entered followed by '#':

      GetNumberResult numberResult = (GetNumberResult)ourRequest.InstanceInfo.ActionResult;
      String enteredNumber = numberResult.EnteredNumber;
      ...
      
    • Get a 16 digit number using the defaults:

      Play prompt = Play.SayText("Please enter your 16 digit number.");
      actions.Add(new GetNumber(prompt, new WebPageRequest("UseNumberPage.aspx"), 16));
      
    • Get a 4 digit number containing digits 1-8:

      Play prompt = Play.SayText("Please enter 4 digits between 1 and 8.");
      GetNumber getNumberAction = new GetNumber(prompt, new WebPageRequest("UseNumberPage.aspx"), 4);
      getNumberAction.ValidDigits = "12345678";
      actions.Add(getNumberAction);
      
    • Get a variable length number containing digits 0-9, ending with a '#':

      Play prompt = Play.SayText("Please enter your id followed by a hash.");
      GetNumber getNumberAction = new GetNumber(prompt, new WebPageRequest("UseNumberPage.aspx"));
      getNumberAction.ValidDigits = "0123456789";
      getNumberAction.SecondsDigitTimeout = 10;
      
      // Set up the messages to play if the caller does not
      // enter a number or enters an invalid digit.
      getNumberAction.OnDigitTimeoutMessages = new List<Play>();
      getNumberAction.OnDigitTimeoutMessages.Add(Play.SayText("Please enter a number."));
      getNumberAction.OnDigitTimeoutMessages.Add(Play.SayText("This is your final chance to enter a number."));
      getNumberAction.OnInvalidDigitMessages = new List<Play>();
      getNumberAction.OnInvalidDigitMessages.Add(Play.PlayFile("invalidentry.wav"));
      
      actions.Add(getNumberAction);
      
  • API Reference:

    Class GetNumber Inherits TelephonyAction

    Represents a get number action.

    Constructors:

    New(prompt As RestAPIWrapper.Play)
    New(prompt As RestAPIWrapper.Play, nextPage As RestAPIWrapper.WebPageRequest)
    New(prompt As RestAPIWrapper.Play, nextPage As RestAPIWrapper.WebPageRequest, digitCount As Integer)
    New(prompt As RestAPIWrapper.Play, nextPage As RestAPIWrapper.WebPageRequest, endDigit As Char)
    

    Members:

    DigitCount As Integer
    EndDigit As Char
    ValidDigits As String
    HelpDigit As Char
    SecondsDigitTimeout As Integer
    OnDigitTimeoutMessages As List(Of RestAPIWrapper.Play)
    OnInvalidDigitMessages As List(Of RestAPIWrapper.Play)
    NextPage As RestAPIWrapper.WebPageRequest
    
    Class WebPageRequest

    Represents a request to a web page.

    Constructors:

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

    Members:

    Method As String
    
    Class GetNumberResult Inherits RestAPIWrapper.ActionResult

    Represents the result of a get number action.

    Members:

    EnteredNumber As String
    

    Examples:

    • Get a variable length number using the defaults (ending with a '#'):

      Dim prompt As Play = Play.SayText("Please enter your number followed by a hash.")
      actions.Add(New GetNumber(prompt, New WebPageRequest("UseNumberPage.aspx")))
      

      The following may be returned when a number is successfully entered followed by '#':

      Dim numberResult As GetNumberResult = ourRequest.InstanceInfo.ActionResult
      Dim enteredNumber As String = numberResult.EnteredNumber
      ...
      
    • Get a 16 digit number using the defaults:

      Dim prompt As Play = Play.SayText("Please enter your 16 digit number.")
      actions.Add(New GetNumber(prompt, New WebPageRequest("UseNumberPage.aspx"), 16))
      
    • Get a 4 digit number containing digits 1-8:

      Dim prompt As Play = Play.SayText("Please enter 4 digits between 1 and 8.")
      Dim getNumberAction As GetNumber = New GetNumber(prompt, New WebPageRequest("UseNumberPage.aspx"), 4)
      getNumberAction.ValidDigits = "12345678"
      actions.Add(getNumberAction)
      
    • Get a variable length number containing digits 0-9, ending with a '#':

      Dim prompt As Play = Play.SayText("Please enter your id followed by a hash.")
      Dim getNumberAction As GetNumber = New GetNumber(prompt, New WebPageRequest("UseNumberPage.aspx"))
      getNumberAction.ValidDigits = "0123456789"
      getNumberAction.SecondsDigitTimeout = 10
      
      ' Set up the messages to play if the caller does not
      ' enter a number or enters an invalid digit.
      ' Set up some new info messages for no entry and invalid entry
      getNumberAction.OnDigitTimeoutMessages = New List(Of Play)
      getNumberAction.OnDigitTimeoutMessages.Add(Play.SayText("Please enter a number."))
      getNumberAction.OnDigitTimeoutMessages.Add(Play.SayText("This is your final chance to enter a number."))
      getNumberAction.OnInvalidDigitMessages = New List(Of Play)
      getNumberAction.OnInvalidDigitMessages.Add(Play.PlayFile("invalidentry.wav"))
      
      actions.Add(getNumberAction)
      
  • API Reference:

    class GetNumber extends TelephonyAction

    Represents a get number action.

    Constructors:

    GetNumber(Play prompt);
    GetNumber(Play prompt, WebPageRequest nextPage);
    GetNumber(Play prompt, WebPageRequest nextPage, int digitCount);
    GetNumber(Play prompt, WebPageRequest nextPage, char endDigit);
    

    Members:

    setDigitCount(int digitCount);
    setEndDigit(char endDigit);
    setValidDigits(String validDigits);
    setHelpDigit(char helpDigit);
    setSecondsDigitTimeout(int secondsTimeout);
    setOnDigitTimeoutMessages(List<Play> messages);
    setOnInvalidDigitMessages(List<Play> messages);
    setNextPage(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 GetNumberResult extends ActionResult

    Represents the result of a get number action.

    Members:

    String getEnteredNumber();
    

    Examples:

    • Get a variable length number using the defaults (ending with a '#'):

      Play prompt = Play.sayText("Please enter your number followed by a hash.");
      actions.add(new GetNumber(prompt, new WebPageRequest("UseNumberPage")));
      

      The following may be returned when a number is successfully entered followed by '#':

      public void doGet(HttpServletRequest request, HttpServletResponse response) 
      {
        TelephonyRequest ourRequest = new TelephonyRequest(request);
        GetNumberResult numberResult = (GetNumberResult)ourRequest.getInstanceInfo().getActionResult();
        string enteredNumber = numberResult.getEnteredNumber();
        ...
      
    • Get a 16 digit number using the defaults:

      Play prompt = Play.sayText("Please enter your 16 digit number.");
      actions.add(new GetNumber(prompt, new WebPageRequest("UseNumberPage"), 16));
      
    • Get a 4 digit number containing digits 1-8:

      Play prompt = Play.sayText("Please enter 4 digits between 1 and 8.");
      GetNumber getNumberAction = new GetNumber(prompt, new WebPageRequest("UseNumberPage"), 4);
      getNumberAction.setValidDigits("12345678");
      actions.add(getNumberAction);
      
    • Get a variable length number containing digits 0-9, ending with a '#':

      Play prompt = Play.sayText("Please enter your id followed by a hash.");
      GetNumber getNumberAction = new GetNumber(prompt, new WebPageRequest("UseNumberPage"));
      getNumberAction.setValidDigits("0123456789");
      getNumberAction.setSecondsDigitTimeout(10);
      
      // Set up the messages to play if the caller does not
      // enter a number or enters an invalid digit.
      List<Play> onDigitTimeoutMessages = new ArrayList<Play>();
      onDigitTimeoutMessages.add(Play.sayText("Please enter a number."));
      onDigitTimeoutMessages.add(Play.sayText("This is your final chance to enter a number."));
      getNumberAction.setOnDigitTimeoutMessages(onDigitTimeoutMessages);
      
      List<Play> onInvalidDigitMessages = new ArrayList<Play>();
      onInvalidDigitMessages.add(Play.playFile("invalidentry.wav"));
      getNumberAction.setOnInvalidDigitMessages(onInvalidDigitMessages);
      
      actions.add(getNumberAction);
      
  • API Reference:

    class GetNumber

    Represents a get_number action.

    Constructors:

    GetNumber()
    

    Members:

    def set_valid_digits(valid_digits)
    def set_digit_count(digit_count)
    def set_end_digit(end_digit)
    def set_help_digit(help_digit)
    def set_next_page(next_page) # A WebPage object, see Redirect() for details
    def on_prompt_play(play_action) # A Play object, see Play() for details
    def set_seconds_digit_timeout(seconds_digit_timeout)
    def append_on_digit_timeout_message(play_action)
    def append_on_invalid_digit_message(play_action)
    

    Examples:

    • Get a variable length number using the defaults (ending with a '#'):

      from aculab.telephony_rest_api import *
      
      my_actions = Actions('Usage example 1: GetNumber.')
      my_number = GetNumber()
      
      my_number.on_prompt_play(Play(text_to_say='Please enter your number followed by a hash.'))
      my_number.set_next_page(WebPage(url='use_number_page'))
      my_actions.add(my_number)
      
      response_body = my_actions.get_json()
      
    • Get a 16 digit number using the defaults:

      from aculab.telephony_rest_api import *
      
      my_actions = Actions('Usage example 2: GetNumber.')
      my_number = GetNumber()
      
      my_number.on_prompt_play(Play(text_to_say='Please enter your 16 digit number.'))
      my_number.set_end_digit('')
      my_number.set_digit_count(16)
      my_number.set_next_page(WebPage(url='use_number_page'))
      my_actions.add(my_number)
      
      response_body = my_actions.get_json()
      
    • Get a 4 digit number containing digits 1-8:

      from aculab.telephony_rest_api import *
      
      my_actions = Actions('Usage example 3: GetNumber.')
      my_number = GetNumber()
      
      my_number.on_prompt_play(Play(text_to_say='Please enter 4 digits between 1 and 8.'))
      my_number.set_digit_count(4)
      my_number.set_end_digit('')
      my_number.set_valid_digits('12345678')
      my_number.set_next_page(WebPage(url='use_number_page'))
      my_actions.add(my_number)
      
      response_body = my_actions.get_json()
      
    • Get a variable length number containing digits 0-9, ending with a '#':

      from aculab.telephony_rest_api import *
      
      my_actions = Actions('Usage example 4: GetNumber.')
      my_number = GetNumber()
      
      my_number.on_prompt_play(Play(text_to_say='Please enter your id followed by a hash.'))
      my_number.set_digit_count(4)
      my_number.set_end_digit('#')
      my_number.set_help_digit('*')
      my_number.set_seconds_digit_timeout(10)
      my_number.set_next_page(WebPage(url='use_number_page'))
      
      # set up the messages to play if the caller does not enter a number or enters an invalid digit. 
      # These will replace all the default messages.
      my_number.append_on_digit_timeout_message(Play(file_to_play='silencemessage1.wav'))
      my_number.append_on_digit_timeout_message(Play(file_to_play='silencemessage2.wav'))
      my_number.append_on_invalid_digit_message(Play(text_to_say='Please enter only numeric digits followed by a hash.'))
      play_action = Play(text_to_say='No really!')
      play_action.append_text(text_to_say='Please enter only numeric digits followed by a hash.')
      my_number.append_on_invalid_digit_message(play_action)
      my_actions.add(my_number)
      
      response_body = my_actions.get_json()
      
  • API Reference:

    The GetNumber class

    Introduction

    Represents a get number action.

    Class synopsis

    class GetNumber extends ActionBase {
    
        /* Methods */
        public __construct(Play $prompt)
        public void setValidDigits(string $digits)
        public void setDigitCount(int $count)
        public void setEndDigit(string $endDigit)
        public void setNextPage(string $nextPage, 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 GetNumberResult class

    Introduction

    Represents the result of a get number action.

    Class synopsis

    class GetNumberResult extends ActionResult {
    
        /* Methods */
        public string getEnteredNumber()
        
        /* inherited methods */
        public string getAction()
        public boolean getInterrupted()
    }
    

    Examples:

    • Get a variable length number using the defaults (ending with a '#'):

      $prompt = Aculab\TelephonyRestAPI\Play::sayText("Please enter your number followed by a hash.");
      $getnum = new Aculab\TelephonyRestAPI\GetNumber($prompt);
      $getnum->setNextPage('usenumberpage');
      $actions->add($getnum);
      

      Obtain the number entered from the action's next page request:

      $info = InstanceInfo::getInstanceInfo();
      $numberResult = $info->getActionResult();
      $enteredNumber = $numberResult->getEnteredNumber();
      
    • Get a 16 digit number using the defaults:

      $prompt = Aculab\TelephonyRestAPI\Play::sayText("Please enter your 16 digit number.");
      $getnum = new Aculab\TelephonyRestAPI\GetNumber($prompt);
      $getnum->setNextPage('usenumberpage');
      $getnum->setDigitCount(16);
      $getnum->setEndDigit('');
      $actions->add($getnum);
      

      Obtain the number entered from the action's next page request:

      $info = InstanceInfo::getInstanceInfo();
      $numberResult = $info->getActionResult();
      $enteredNumber = $numberResult->getEnteredNumber();
      
    • Get a 4 digit number containing digits 1-8:

      $prompt = Aculab\TelephonyRestAPI\Play::sayText("Please enter 4 digits between 1 and 8.");
      $getnum = new Aculab\TelephonyRestAPI\GetNumber($prompt);
      $getnum->setNextPage('usenumberpage');
      $getnum->setDigitCount(4);
      $getnum->setEndDigit('');
      $getnum->setValidDigits('12345678');
      $actions->add($getnum);
      

      Obtain the number entered when action's next page is requested:

      $info = InstanceInfo::getInstanceInfo();
      $numberResult = $info->getActionResult();
      $enteredNumber = $numberResult->getEnteredNumber();
      
    • Get a variable length number containing digits 0-9, ending with a '#':

      $prompt = Aculab\TelephonyRestAPI\Play::sayText("Please enter your id followed by a hash.");
      
      $getnum = new Aculab\TelephonyRestAPI\GetNumber($prompt);
      $getnum->setNextPage('usenumberpage');
      $getnum->setSecondsDigitTimeout(10);
      
      // Set up the messages to play if the caller does not
      // enter a number or enters an invalid digit.
      $timeout = new Aculab\TelephonyRestAPI\MessageList();
      $timeout->addMessage(Aculab\TelephonyRestAPI\Play::playFile('silencemessage1.wav'));
      $timeout->addMessage(Aculab\TelephonyRestAPI\Play::playFile('silencemessage2.wav'));
      $getnum->setOnDigitTimeoutMessages($timeout);
      
      $invalid = new Aculab\TelephonyRestAPI\MessageList();
      $invalid->addMessage(Aculab\TelephonyRestAPI\Play::sayText('Please enter only numeric digits followed by a hash'));
      $message = Aculab\TelephonyRestAPI\Play::sayText('No really!');
      $message->addText('Please enter only numeric digits followed by a hash')
      $invalid->addMessage($message);
      $getnum->setOnInvalidDigitMessages($invalid);
      
      $actions->add($getnum);
      

      Obtain the number entered from the action's next page request:

      $info = InstanceInfo::getInstanceInfo();
      $numberResult = $info->getActionResult();
      $enteredNumber = $numberResult->getEnteredNumber();