The GetInput Element

    The GetInput XML element may be used to collect user input through Automatic Speech Recognition or DTMF “digit press” inputs.

    When collecting a user’s speech as input, Plivo transcribes and relays the user’s speech to the specified action URL in real-time.

    When collecting input through digit press, the digits entered by the user are relayed to the specified action URL.

    GetInput XML also supports the simultaneous detection of both Speech and Digit Press inputs.

    Note: GetInput XML is designed to replace the older GetDigits XML element, which only supports the collection of Digit Press inputs. We recommend you to use GetInput XML instead of GetDigits XML, even if you only intend to collect Digit Press inputs from users.

    Nesting Rules

    You may nest Speak XML (Text-To-Speech) and Play XML elements inside GetInput XML to prompt the user for inputs.

    This is useful for building Interactive Voice Response (IVR) experiences.

    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 expect to receive from the other end.

    Allowed values - dtmf, speech, dtmf speech.

    When set to “dtmf speech”, Plivo will listen for both speech as well as digit inputs. The input which is detected first will be relayed to the action URL.

    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.

    If no new digit input is provided within the digitEndTimeout period, digits entered until then will be processed.

    Allowed values - 2 to 10, or “auto”. Defaults to auto.

    This attribute is applicable to input types ‘dtmf’, and ‘dtmf speech’.

    speechEndTimeout StringTime, in seconds, that Plivo will wait for more speech once silence is detected before it stops speech recognition. At that point a transcription of the collected speech is relayed to the action URL.

    Allowed values - 2 to 10, or “auto”. Defaults to auto.

    This attribute is applicable to input types ‘speech’, and ‘dtmf speech’.

    finishOnKey StringA 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 # when not specified.

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

    This attribute is applicable to input types ‘dtmf’, and ‘dtmf speech’.

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

    Plivo relays the digits to the action URL as soon as the maximum number of digits specified are collected.

    Allowed values - 1 to 32. Defaults to 32.

    This attribute is applicable to input types ‘dtmf’, and ‘dtmf speech’.

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

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

    This attribute is applicable to input types ‘speech’, and ‘dtmf speech’.

    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 single words.

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

    Limits -
    Phrases per request: 500.
    Characters per request: 10000.
    Characters per phrase: 100.

    This attribute is applicable to input types ‘speech’, and ‘dtmf speech’.

    language StringThe language attribute specifies the language Plivo should recognize from the user.

    Allowed value - See list of Supported languages. Defaults to en-US.

    This attribute is applicable to input types ‘speech’, and ‘dtmf speech’.

    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.

    This attribute is applicable to input types ‘speech’, and ‘dtmf speech’.

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

    Allowed values - GET, POST. Defaults to POST.

    This attribute is applicable to input types ‘speech’, and ‘dtmf speech’.

    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.

    This attribute is applicable to input types ‘speech’, and ‘dtmf speech’.

    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.
    BilledAmountThe total amount billed for speech input transcription.

    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 newer 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 only applies to unstable speech.
    SequenceNumberIt contains a sequence number of the interim speech callback. This is present to help with the ordering of incoming callback requests.

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