<Gather>

The <Gather> verb transcribes speech or collects digits during a call.

Verb Attributes

Attribute
action optionalThe action attribute takes in an absolute URL. SignalWire will make a GET or POST request to this URL when entering of digits is completed. If there is no URL provided, SignalWire will re-request the URL that was previously used, which can cause an unwanted looping behavior. Be sure to provide the proper URL in order to avoid this outcome. See below for specified request parameters.
actionOnEmptyResult optionalSend a webhook to the action URL even if there is no input. By default, if no input is detected, the next TwiML instruction is executed but by setting actionOnEmptyResult to true, a callback to the action URL will be sent to continue call flow. Valid values are true or false. Default is false.
finishOnKey optionalThe set of digits, (0-9, *, #), that can end a recording. Default is #.
hints optionalA list of words and phrases, each a max of 100 characters, a caller is likely to say during a call.
input optionalThe type of input received from a caller (i.e. speech or DTMF). Values can be dtmf, speech, or dtmf speech. Default is dtmf.
language optionalThe language in which you expect your callers to speak. Default is en-US.
method optionalThe method attribute specifies whether the request to action is a GET or a POST. Valid values are GET or POST, default value is POST.
numDigits optionalThe number of digits you expect to be pressed by a caller.
partialResultCallback optionalThe URL to request to during speech recognition. No URL is specified by default.
partialResultCallbackMethod optionalThe type of HTTP request to use when requesting a partialResultCallback. Default is POST.
profanityFilter optionalTells SignalWire whether or not to filter profane language when transcribing a call. Default is true.
speechTimeout optionalThe set time, in seconds, that SignalWire will wait before ending speech recognition. If set to auto, SignalWire will automatically end speech recognition when there is a pause in speech.
timeout optionalThe number of seconds of silence or inaction that denote the end of caller input. Default is 5 seconds.

Request parameters for action URL

The action request contains the Standard Request Parameters as well as:

Parameter
Confidence stringThe score, between 0.0 and 1.0, that determines the accuracy of a transcription.
SpeechResult stringThe transcribed result of the caller's speech.
Digits stringThe buttons pressed by a caller.

Nesting

The following verbs can be nested within a <Gather>:

  • <Play>: plays an audio file, that SignalWire fetches from the URL you configured, back to the caller.
  • <Pause>: waits silently for a distinctive number of seconds.
  • <Say>: reads supplied text back to the caller.

Examples

A Simple Gather

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather/>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

response.gather()
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $response->gather();
  echo $response;
?>
using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Gather();

        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Gather

response = VoiceResponse()
response.gather()

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.gather
end

puts response.to_s

SignalWire will collect any speech or digits pressed during a call.

Nesting Within a Gather

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather action="https://example.com/process_gather.php" method="GET">
        <Say>
            Please enter your account number,
            followed by the pound sign.
        </Say>
    </Gather>
    <Say>We did not receive any input. Goodbye!</Say>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

gather = response.gather({ action: 'https://example.com/process_gather.php', method: 'GET' })
gather.say('Please enter your account number, followed by the pound sign.')
response.say('We did not receive any input. Goodbye!')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $gather = $response->gather(array(
    'action' => 'https://example.com/process_gather.php',
    'method' => 'GET'
  ));
  $gather->say('Please enter your account number, followed by the pound sign.');
  $response->say('We did not receive any input. Goodbye!');
  echo $response;
?>
using Twilio.TwiML;
using Twilio.Http;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var gather = new Gather(action: new Uri("https://example.com/process_gather.php"), method: HttpMethod.Get);
        gather.Say("Please enter your account number, followed by the pound sign.");

        response.Append(gather);
        response.Say("We did not receive any input. Goodbye!");

        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Gather, Say

response = VoiceResponse()
gather = Gather(action='https://example.com/process_gather.php', method='GET')
gather.say('Please enter your account number, followed by the pound sign.')
response.append(gather)
response.say('We did not receive any input. Goodbye!')

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.gather(action: 'https://example.com/process_gather.php', method: 'GET') do |gather|
    gather.say(message: 'Please enter your account number, followed by the pound sign.')
  end
  response.say(message: 'We did not receive any input. Goodbye!')
end

puts response.to_s

You can use the <Say> verb to prompt callers to enter the desired input. In this example, when a caller enters their account number, SignalWire will submit the result to the URL provided in the action attribute. If the caller does not enter any digits, SignalWire will prompt the 'Goodbye' statement.

Gather DTMF or Speech

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather input="speech dtmf" timeout="5" numDigits="1">
        <Say>Please press 3 or say account for account information.</Say>
    </Gather>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

gather = response.gather({ input: 'speech dtmf', timeout: 5, numDigits: 1 })
gather.say('Please press 3 or say account for account information.')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $gather = $response->gather(array(
    'input' => 'speech dtmf',
    'timeout' => 5,
    'numDigits' => 1
  ));
  $gather->say('Please press 3 or say account for account information.');
  echo $response;
?>
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var gather = new Gather(input: "speech dtmf", timeout: 5, numDigits: 1);
        gather.Say("Please press 3 or say account for account information.");

        response.Append(gather);
        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Gather, Say

response = VoiceResponse()
gather = Gather(input='speech dtmf', timeout=5, num_digits=1)
gather.say('Please press 3 or say account for account information.')
response.append(gather)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.gather(input: 'speech dtmf', timeout: 5, num_digits: 1) do |gather|
    gather.say(message: 'Please press 3 or say account for account information.')
  end
end

puts response.to_s

A caller can access their account information either through speech recognition or DTMF tones. SignalWire will wait 5 seconds before processing the information and sending the data.

Potential Issues

<Gather> doesn't receive caller input when the caller is using a VoIP phone.

Solution: Some VoIP phones have trouble sending DTMF tones. Phones typically use compressed bandwidth-conserving audio protocols that can interfere with the transmission of the digit's signal.

The Digits parameter is not sent to the <Gather> URL.

Solution: Verify that your application is not responding to the action URL with an HTTP 3xx redirect. SignalWire will follow this redirect but will not resend the Digits parameter.