The GetInput element

    You can use the GetInput XML element to collect user input through automatic speech recognition or DTMF “digit press” inputs.

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

    When collecting input through digit press, Plivo relays the digits entered to the specified action URL.

    The GetInput XML element supports simultaneous detection of both speech and digit press inputs.

    Note: The GetInput XML element is designed to replace Plivo’s older GetDigits XML element, which only supports the collection of digit press inputs. We recommend you use GetInput instead of GetDigits even if you only intend to collect digit press input from users.

    Nesting elements

    You can nest Speak XML (text-to-speech) and Play XML elements inside GetInput XML to prompt users for inputs. This is useful for building interactive voice response (IVR) experiences.

    Attributes

    action StringCallback-retry configurable

    The input is sent to a specific URL. See the “parameters sent to the action URL” table below for more information.

    Allowed values: a fully qualified URL

    method String

    The HTTP method to use when invoking the action URL.

    Allowed values: GET, POST
    Defaults to POST.

    inputType String

    The type of input(s) you expect to receive.

    Allowed values: dtmf, speech, dtmf speech

    When set to dtmf speech, Plivo listens for both speech and digit inputs. The input that’s detected first is relayed to the action URL.

    executionTimeout integer

    Maximum execution time, in seconds, for which input detection is carried out. If the user fails to provide input within the timeout period, the next element in the response will be processed. This duration is counted after nested Play/Speak elements have ended.

    Allowed values: 5 to 60
    Defaults to 15.

    digitEndTimeout String

    Time, 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 String

    Time, in seconds, that Plivo waits 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 String

    A digit that the user can press to submit digits.

    Allowed values: One and only one of  0–9, *, #, <empty string>, none
    Defaults to #.

    If set to <empty string> or none, input capture will end based on a timeout or the 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 is 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 String

    A 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: 10,000
    Characters per phrase: 100

    This attribute is applicable to input types speech and dtmf speech.

    language String

    Specifies the language Plivo should recognize from the user.

    Allowed values: See list of supported languages
    Defaults to en-US.

    This attribute is applicable to input types speech and dtmf speech.

    interimSpeechResultsCallback StringCallback-retry configurable

    If interimSpeechResultsCallback URL is specified, requests to this URL are made in real-time as Plivo recognizes speech.

    See the “parameters sent to the interimSpeechResultsCallback URL” table below for more information.

    Allowed values: a fully qualified URL

    This attribute is applicable to input types speech and dtmf speech.

    interimSpeechResultsCallbackMethod String

    The 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 boolean

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

    Allowed values: true, false
    Defaults to true.

    redirect boolean

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

    Allowed values: true, false
    Defaults to true.

    profanityFilter boolean

    If true, filters out profane words. Words filtered out are transcribed with their first letter and asterisks for the remaining characters (e.g. f***). The profanity filter operates on single words; it doesn’t detect abusive or offensive speech that’s 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, these parameters are sent to the action URL specified.

    InputType

    The type of input detected.

    Allowed values: dtmf, speech

    DigitsThe digits entered by the caller, excluding the finishOnKey input, if used. This parameter will be empty if inputType is speech.
    SpeechThe transcribed result of the 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 the interimSpeechResultsCallback URL

    In addition to the standard callback URL request parameters, these parameters are sent to the interim speech results callback URL.

    StableSpeechThe stable transcribed result of the user’s speech.
    UnstableSpeechThe newer unstable transcribed result of the 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.
    SequenceNumberContains a sequence number of the interim speech callback, to help with ordering 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('https://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).
    					AddSpeak("Tell us more about your experience").
    					SetVoice("WOMAN").
    					SetLanguage("en-US").
    					SetLoop(1)}),
    		},
    	}.String())
    }