The GetInput Element Beta

    The GetInput element is used to collect input via Voice or DTMF. Voice inputs are transcribed in real-time and posted to your callback URL. Once the caller has finished entering their digits, the API submits the data to the provided callback URL.

    Then, you can play a message nested inside the GetInput element while the voice or digits is being received in the background. This is useful for creating a phone tree (IVR).

    Nesting Rules

    You can nest Speak and Play elements within the GetInput element.

    Attributes

    action StringThe input is sent to a specific URL. See the action request parameters table below for more information.

    Allowed values - a fully qualified URL.

    method StringThe HTTP method to use when invoking the action URL.

    Allowed values - GET, POST. Defaults to POST.

    inputType StringThe type of input(s) you can expect to receive from the other end.

    Allowed values - dtmf, speech, dtmf speech.

    executionTimeout integerMaximum execution time, in seconds, for which input detection will be carried out.

    If the user fails to provide input within the timeout period, the next element in the response is processed.

    This duration is counted after nested play/speak has ended.

    Allowed values - 5 to 60. Defaults to 15.

    digitEndTimeout StringTime, in seconds, allowed between consecutive digit inputs.

    Allowed values - 2 to 10 or auto. Defaults to auto.

    speechEndTimeout StringTime, in seconds, that Plivo will wait for more speech once silence is detected before it stops speech recognition.

    Allowed values - 2 to 10 or auto. Defaults to auto.

    finishOnKey String

    A digit that the user can press to submit their digits.

    Allowed values - One and only one of the following digits: 0 - 9, *, # OR <empty string>,‘none’. Defaults to #.

    If set to <empty string> or ‘none’, input capture will end based on a timeout and numDigits attribute.

    numDigits integerThe maximum number of digits to be processed in the current operation.

    Allowed values - 1 to 32. Defaults to 32.

    speechModel StringThe Automatic Speech Recognition (ASR) Model to use for transcribing the speech.

    Allowed values - default, command_and_search, phone_call. Defaults to ‘default’.

    hints StringA list of phrases to act as "hints" to the speech recognition model; these phrases can boost the probability that such words or phrases will be recognized. Phrases may be provided both as small groups of words or as a single word.

    Allowed values - A non-empty string of comma-separated phrases.

    Limits - Phrases per request: 500 Characters per request: 10000 Characters per phrase: 100
    language StringThe language attribute specifies the language Plivo should recognize from the user.

    Allowed value - en-US. Defaults to en-US.

    interimSpeechResultsCallback StringIf interimSpeechResultsCallback URL is specified, requests to this URL would be made in real-time as Plivo recognizes speech. See the interim speech result callback parameters table below for more information.

    Allowed values - a fully qualified URL.

    interimSpeechResultsCallbackMethod StringThe HTTP method to use when invoking the interimSpeechResultsCallback URL.

    Allowed values - GET, POST. Defaults to POST.

    log booleanIf true, Plivo will log digits or recognized speech by the caller. If false, logging will be disabled while processing the GetInput Element.

    Allowed values - true, false. Defaults to true.

    redirect booleanRedirect to action URL if true. If false, only request the URL and continue to the next element.

    Allowed values - true, false. Defaults to true.

    profanityFilter booleanIf true, it will filter out profane words or phrases. Words filtered out will contain their first letter and asterisks for the remaining characters (e.g. f***). The profanity filter operates on single words, it does not detect abusive or offensive speech that is a phrase or a combination of words.

    Allowed values - true, false. Defaults to false.

    Parameters sent to the Action URL

    In addition to the standard action URL request parameters, the following parameters will be sent to the Action URL specified above.

    InputTypeThe type of input detected.

    Possible values - dtmf, speech

    DigitsThe digits entered by the caller, excluding the finishOnKey digit, if used.

    This parameter will be empty if inputType is speech.

    SpeechThe transcribed result of your caller's speech.

    This parameter will be empty if inputType is dtmf.

    SpeechConfidenceScoreA confidence score between 0.0 and 1.0. The higher the confidence score, the more likely that the transcription is accurate.

    Parameters sent to Interim Speech Results Callback URL

    In addition to the standard callback URL request parameters, the following parameters would be sent to the Interim Speech Results Callback URL specified above.

    StableSpeechThe stable transcribed result of your user’s speech.
    UnstableSpeechThe unstable transcribed result of your user’s speech. This is an interim result and may change as more speech is gathered from the caller.
    StabilityAn estimate of the likelihood that the recognizer will not change its guess about the interim result. Values range from 0.0 (completely unstable) to 1.0 (completely stable). This field is only provided for unstable speech.
    SequenceNumberIt contains a sequence number of the interim speech callback.

    Example Request

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    
    from plivo import plivoxml
    element = plivoxml.ResponseElement()
    response = element.add(
        plivoxml.GetInputElement().
        set_action('https://www.foo.com/result').
        set_method('POST').
        set_input_type('speech').
        set_execution_timeout(10).
        set_digit_end_timeout(5).
        set_speech_end_timeout(2).
        set_finish_on_key('#').
        set_num_digits(2).
        set_hints('good, bad').
        set_interim_speech_results_callback('http://www.foo.com/interim_result').
        set_interim_speech_results_callback_method('POST').
        set_log(True).
        set_redirect(False).
        set_language('en-US').
        set_speech_model('default').
        add_speak(content='Tell us more about your experience', voice='Polly.Salli', language='en-US', loop=2).
        add_wait(length=10, silence=0, min_silence=10, beep=1).
        add_play(content='https://s3.amazonaws.com/plivocloud/Trumpet.mp3', loop=2)
    
    ).to_string(False)
    print(response)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    
    require 'rubygems'
    require 'plivo'
    require 'rspec'
    require 'plivo/xml/element'
    include Plivo::XML
    
    resp = Plivo::XML::Response.new
    get_input = resp.addGetInput(action:'https://www.foo.com/result', digitEndTimeout: '5',
                  executionTimeout:'10',
                  finishOnKey:'#',
                  hints:'good, bad',
                  inputType:'speech',
                  interimSpeechResultsCallback:'https://www.foo.com/interim_result',
                  interimSpeechResultsCallbackMethod:'POST',
                  language:'en-US',
                  log:'true',
                  method:'POST',
                  profanityFilter:'true',
                  redirect:'false',
                  speechEndTimeout:'2',
                  speechModel:'default')
    get_input.addSpeak('Tell us more about your experience.', voice: 'Polly.Salli' language: 'en-US')
    get_input.addWait(length: '10', beep:'true')
    get_input.addPlay('https://s3.amazonaws.com/plivocloud/Trumpet.mp3')
    xml = Plivo::XML::PlivoXML.new(resp)
    puts xml.to_xml
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    
    var plivo = require('plivo');
    var response = new plivo.Response();
    const get_input = response.addGetInput(
        {
            'action': 'https://www.foo.com/result',
            "method": 'POST',
            'inputType': 'speech',
            'executionTimeout': '10',
            'digitEndTimeout': '5',
            'speechEndTimeout': '2',
            'finishOnKey': '#',
            'speechModel': 'default',
            'hints': 'good, bad',
            'language': 'en-US',
            'interimSpeechResultsCallback': 'https://www.foo.com/interim_result',
            'interimSpeechResultsCallbackMethod': 'POST',
            'log': 'true',
            'redirect': 'false',
            'profanityFilter': 'true'
        });
    get_input.addSpeak('Tell us more about your experience');
    
    console.log(response.toXML());
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    
    <?php
    require 'vendor/autoload.php';
    use Plivo\XML\Response;
    $resp = new Response();
    $get_input = $resp->addGetInput(
                [
                    'action' => "https://www.foo.com/result",
                    'method' => "POST",
                    'digitEndTimeout' => "5",
                    'executionTimeout' => "10",
                    'finishOnKey' => "#",
                    'hints' => "good, bad",
                    'inputType' => "speech",
                    'interimSpeechResultsCallback' => "https://www.foo.com/interim_result",
                    'interimSpeechResultsCallbackMethod' => "POST",
                    'language' => "en-US",
                    'log' => "true",
                    'profanityFilter' => "true",
                    'redirect' => "false",
                    'speechEndTimeout' => "2",
                    'speechModel' => 'default'
                ]);
    $get_input->addSpeak("Tell us more about your experience.", ['language'=>"en-US", 'loop'=>"2", 'voice'=>"Polly.Salli"]);
    $get_input->addWait(['length'=>'10','beep'=>'false']);
    $get_input->addPlay("https://s3.amazonaws.com/plivocloud/Trumpet.mp3");
    echo($resp->toXML(true));
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    
    import com.plivo.api.xml.Response;
    import com.plivo.api.xml.GetInput;
    import com.plivo.api.xml.Speak;
    import com.plivo.api.exceptions.PlivoXmlException;
    
    
    class GetInputExample {
      public static void main(String [] args) throws Exception {
        Response res = new Response()
            .children (
                new GetInput()
                  .action("https://www.foo.com/result")
                  .method("POST")
                  .inputType("speech")
                  .executionTimeout(10)
                  .digitEndTimeout(5)
                  .speechEndTimeout(2)
                  .finishOnKey("#")
                  .speechModel("default")
                  .hints("good, bad")
                  .language("en-US")
                  .interimSpeechResultsCallback("https://www.foo.com/interim_result")
                  .interimSpeechResultsCallbackMethod("POST")
                  .redirect(false)
                  .log(true)
                  .profanityFilter(true)
                  .children(
                    new Speak("Tell us more about your experience")
                    )
              );
        System.out.println(response.toXmlString());
      }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    
    using System;
    using System.Collections.Generic;
    using Plivo.XML;
    
    namespace Plivo
    {
        public class Program
        {
            public void GetInputXml()
            {
                var resp = new Response();
                Plivo.XML.GetInput get_input = new
                    Plivo.XML.GetInput("",
                        new Dictionary<string, string>()
                        {
                            {"action", "https://www.foo.com/result"},
                            {"method", "POST"},
                            {"digitEndTimeout", "5"},
                            {"executionTimeout", "10"},
                            {"finishOnKey", "#"},
                            {"hints", "good, bad"},
                            {"inputType", "speech"},
                            {"interimSpeechResultsCallback", "https://www.foo.com/interim_result"},
                            {"interimSpeechResultsCallbackMethod", "POST"},
                            {"language", "en-US"},
                            {"log", "true"},
                            {"profanityFilter", "true"},
                            {"redirect", "false"},
                            {"speechEndTimeout", "2"},
                            {"speechModel", "default"},
                        });
                resp.Add(get_input);
                get_input.AddSpeak("Tell us more about your experience.",
                    new Dictionary<string, string>() { });
                resp.AddSpeak("Statement not recieved.",
                    new Dictionary<string, string>() { });
    
                var output = resp.ToString();
                Console.WriteLine(output);
            }
        }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    
    package main
    
    import (
    	"github.com/plivo/plivo-go/xml"
    )
    
    func main() {
    	println(xml.ResponseElement{
    		Contents: []interface{}{
    			new(xml.GetInputElement).
    				SetAction("https://www.foo.com/result").
    				SetMethod("POST").
    				SetInputType("speech").
    				SetExecutionTimeout(10).
    				SetDigitEndTimeout(5).
    				SetSpeechEndTimeout(2).
    				SetFinishOnKey("#").
    				SetSpeechModel("default").
    				SetLanguage("en-us").
    				SetHints("good, bad").
    				SetInterimSpeechResultsCallback("https://www.foo.com/interim_result").
    				SetInterimSpeechResultsCallbackMethod("POST").
    				SetRedirect(true).
    				SetLog(true).
    				SetProfanityFilter(true).
    				SetContents([]interface{}{new(xml.SpeakElement).
    					SetContents("Tell us more about your experience").
    					SetVoice("WOMAN").
    					SetLanguage("en-US").
    					SetLoop(1)}),
    		},
    	}.String())
    }