TwiML™ Voice: <Gather>

To collect input during a call, use the <Gather> verb in the TwiML language. This input could include speech, digits pressed on the keypad, or both.

To implement <Gather>, you can try either of the following.

• Send a plain TwiML document to Twilio using curl or an API application. At a minimum, nest the <Gather> verb inside the <Response> in the TwiML document. The following example shows this TwiML document.

  Copy code block

  1
  <?xml version="1.0" encoding="UTF-8"?>
  2
  <Response>
  3
      <Gather/>
  4
  </Response>

• Add a Twilio helper library to your programming language of choice and generate TwiML from your web application.

  <Gather> example

  Report code block

  Copy code block

  1
  const VoiceResponse = require('twilio').twiml.VoiceResponse;
  2
  
  3
  
  4
  const response = new VoiceResponse();
  5
  response.gather();
  6
  
  7
  console.log(response.toString());

  Output

  Copy output

  1
  <?xml version="1.0" encoding="UTF-8"?>
  2
  <!-- page located at http://example.com/simple_gather.xml -->
  3
  <Response>
  4
      <Gather/>
  5
  </Response>

When Twilio executes the instructions in the preceding TwiML document, it performs the <Gather> using the default attribute values.

Twilio pauses and waits for the caller to enter digits on their keypad. At this point, the caller can make one of two choices:

The generic <Gather> TwiML document lacks some capabilities. To expand on what <Gather> can do, you need to add attributes, nest other verbs, or both.

• To learn how to customize the <Gather> verb, consult its list of attributes.
• To learn how Twilio can read some text or play music for your caller while waiting for their input, consult "Nest other verbs".

The <Gather> verb supports the following attributes. Though this verb requires none of these attributes, including the action attribute prevents undesired looping behavior. A <Gather> tag can include zero or more attributes.

The action attribute specifies one URL that Twilio sends your request using HTTP.

After the caller finishes entering digits or reaches the timeout, Twilio sends a POST HTTP request to the specified URL. If you omit this attribute, Twilio calls the TwiML document making the request. This might lead to unwanted looping behavior.

This request includes the caller's data and Twilio's standard request parameters.

Twilio might add some extra attributes to its request after the <Gather> ends:

• If you gathered digits from the caller, Twilio includes the Digits attribute containing the numbers your caller entered.
• If you included speech as an input value, Twilio includes SpeechResult and Confidence parameters:
  • SpeechResult contains the transcribed result of your caller's speech.
  • Confidence contains a confidence score between 0.0 and 1.0. A higher confidence score means the potential for greater accuracy of the transcription.

Note: Your code shouldn't expect confidence as a required field. Twilio doesn't guarantee its accuracy or presence in any of the results.

After <Gather> ends, Twilio sends its request to your action URL. The current call continues using the TwiML document returned from the action URL. Twilio won't use any TwiML verbs after your <Gather> in your original TwiML.

If the caller didn't enter any digits or speech, call flow within the original TwiML document continues.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Gather>
4
        <Say>
5
            Please enter your account number,
6
            followed by the pound sign
7
        </Say>
8
    </Gather>
9
    <Say>We didn't receive any input. Goodbye!</Say>
10
</Response>

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
const gather = response.gather({
6
    action: '/process_gather.php',
7
    method: 'GET'
8
});
9
gather.say('Please enter your account number,\nfollowed by the pound sign');
10
response.say('We didn\'t receive any input. Goodbye!');
11

12
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<!-- page located at http://example.com/complex_gather.xml -->
3
<Response>
4
    <Gather action="/process_gather.php" method="GET">
5
        <Say>
6
            Please enter your account number,
7
            followed by the pound sign
8
        </Say>
9
    </Gather>
10
    <Say>We didn't receive any input. Goodbye!</Say>
11
</Response>

1
<?php
2
// page located at http://yourserver/process_gather.php
3
echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
4
echo "<Response><Say>You entered " . $_REQUEST['Digits'] . "</Say></Response>";
5
?>

Return to attributes list

The actionOnEmptyResult attribute specifies that <Gather> must send a webhook to the action URL with or without DTMF input. By default, if <Gather> times out while waiting for DTMF input, it continues to the next TwiML instruction.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Gather>
4
        <Say>
5
            Please enter your account number,
6
            followed by the pound sign
7
        </Say>
8
    </Gather>
9
    <Say>We didn't receive any input. Goodbye!</Say>
10
</Response>

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Gather actionOnEmptyResult="true" action="/gather-action">
4
        <Say>
5
            Please enter your account number,
6
            followed by the pound sign
7
        </Say>
8
    </Gather>
9
</Response>

The finishOnKey attribute specifies the value that your caller presses to submit their digits.

If you set this attribute to an empty string, <Gather> captures all caller input. After the call reaches its timeout, Twilio submits the caller's digits to the action URL.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Gather input="speech dtmf" finishOnKey="#" timeout="5">
4
    <Say>
5
      Please say something or press * to access the main menu
6
    </Say>
7
  </Gather>
8
  <Say>We didn't receive any input. Goodbye!</Say>
9
</Response>

Return to attributes list

The hints attribute specifies a list of words or phrases that Twilio should expect during recognition. Adding hints to your <Gather> improves Twilio's recognition.

Entries contain either single words or phrases. Each entry can up to 100 characters in length. Separate each word in a phrase with a space.

hints="this is a phrase I expect to hear, keyword, product name, name"

To learn which tokens and keywords your STT provider supports, click the tab for your provider.

hints="$OOV_CLASS_ALPHANUMERIC_SEQUENCE"

hints="grammar"

Return to attributes list

The input attribute specifies which types of input Twilio accepts. The types include dual-tone multi-frequency (DTMF), speech, or both.

• When this attribute value includes speech, Twilio gathers speech from the caller for a maximum duration of 60 seconds. <Gather> doesn't recognize speaking individual alphanumeric characters like "ABC123".
• When you set this attribute value to dtmf speech, Twilio gives precedence to the first input it detects. If Twilio detects speech first, it ignores the finishOnKey attribute.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
const gather = response.gather({
6
    input: 'speech',
7
    action: '/completed'
8
});
9
gather.say('Welcome to Twilio, please tell us why you\'re calling');
10

11
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<!-- page located at http://example.com/simple_gather.xml -->
3
<Response>
4
    <Gather input="speech" action="/completed">
5
           <Say>Welcome to Twilio, please tell us why you're calling</Say>
6
        </Gather>
7
</Response>

Return to attributes list

The language attribute specifies the language Twilio should recognize from your caller.

• This attribute passes through unchanged to the provider.
• This attribute value maps to specific languages in the related speechModel.
  • Google STT V2 models map to the languages specified in its Speech-to-Text V2 supported languages guide.
  • Deepgram models map to the languages specified in its Models & Languages Overview guide.
  • Google STT V1 models map to any language Twilio supports. Twilio has deprecated Google STT V1 as a language model.

Return to attributes list

The method attribute specifies the HTTP verb Twilio should use to request your action URL.

Return to attributes list

The numDigits attribute specifies how many digits you require from callers for this <Gather> instance for DTMF input.

Return to attributes list

The partialResultCallback attribute specifies a URL to which Twilio sends requests as it recognizes speech in real time. These requests contain a parameter labeled UnstableSpeechResult which contains partial transcriptions. These transcriptions may change as the speech recognition progresses.

The Twilio makes asynchronous webhooks to your partialResultCallback URL. They don't accept any TwiML documents in response. To take more actions based on this partial result, use the REST API to modify the call.

Return to attributes list

The partialResultCallbackMethod attribute specifies the HTTP verb Twilio should use to request your partialResultCallback URL.

Return to attributes list

The profanityFilter attributes specifies whether Twilio should filter profanities out of your speech transcription.

When set to true, Twilio replaces all but the initial character in each filtered profane word with asterisks like f***.

Return to attributes list

The speechModel attribute specifies which language model to apply to your <Gather> request.

• This attribute requires you to set speechTimeout to a positive integer value. Don't use auto.
• If Twilio selects your language model, it can handle failover to another provider. In practice, if Google experiences a failure, Twilio switches STT to Deepgram without any action on your part.
• If you want to select the model, you can choose either a generic model or a specific STT model.

Generic models include the following values:

Experimental models give access to the latest speech technology and machine learning research, and can provide higher accuracy for speech recognition over other available models. Available models might support features that experimental models don't.

Specific STT models include a variety from Google Speech-to-Text (STT) V2 (googlev2) or Deepgram (deepgram). If the provider has an outage, Twilio doesn't switch providers on your behalf. The following tabs display the accepted model values for each STT provider.

1
<Gather input="speech" speechModel="googlev2_telephony">
2
  <Say>Please tell us why you're calling.</Say>
3
</Gather>

1
<Gather input="speech" speechModel="deepgram_nova-2">
2
  <Say>Please tell us why you're calling.</Say>
3
</Gather>

To improve the accuracy of your speech to text recognition, set this attribute value to the specific language model best suited for your use case.

To find which works model best for your use case, consider exploring all options.

Return to attributes list

The speechTimeout specifies how long Twilio should wait after a pause in speech before stopping recognition.

• If you set speechTimeout to auto, Twilio stops recognizing speech at the first pause in speech.
• This attribute expresses its value in seconds.
• After the pause reaches this timeout, Twilio sends the speechResult to your action URL.
• If your <Gather> request includes both timeout and speechTimeout, timeout takes precedence for DTMF input and speechTimeout takes precedence for speech.

Return to attributes list

The timeout attribute specifies how long Twilio should wait for the caller provide input on the call. This includes either pressing another digit or saying another word.

• This attribute expresses its value in seconds.
• Before Twilio begins the timeout period, it waits until all nested verbs have executed.
• After the pause reaches this timeout, Twilio sends the speechResult to your action URL.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Gather input="speech dtmf" timeout="3" numDigits="1">
4
        <Say>Please press 1 or say sales for sales.</Say>
5
    </Gather>
6
</Response>

Return to attributes list

The enhanced attribute specifies that <Gather> should use the premium Google STT V1 model. When transcribing phone conversations, the premium model produces 54% fewer errors compared to the base model.

This attribute has the following limitations:

• Applies to only Google STT V1 phone_call model. Twilio ignores the enhanced attribute when set for any other model.
• Applies to the following languages: en-GB, en-US, es-ES, es-US, fr-CH, fr-FR, ja-JP, ru-RU.

The following TwiML document uses the premium phone_call model for <Gather>:

1
<Gather input="speech" enhanced="true" speechModel="phone_call" language="en-GB">
2
  <Say>Please tell us why you're calling.</Say>
3
</Gather>

Return to attributes list

You can nest the following verbs within <Gather>:

• <Pause>
• <Play>
• <Say>

When a <Gather> contains nested <Say> or <Play> verbs, the timeout begins either after the audio completes or when the caller presses their first key. If <Gather> contains multiple <Play> verbs, Twilio retrieves the contents of all files before the <Play> begins.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
const gather = response.gather({
6
    input: 'speech dtmf',
7
    timeout: 3,
8
    numDigits: 1
9
});
10
gather.say('Please press 1 or say sales for sales.');
11

12
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Gather input="speech dtmf" timeout="3" numDigits="1">
4
        <Say>Please press 1 or say sales for sales.</Say>
5
    </Gather>
6
</Response>

If you use <Play> verbs, consider hosting your media in AWS S3 in the us-east-1, eu-west-1, or ap-southeast-2 regions depending on the Twilio Region you use. No matter where you host your media files, verify your Cache Control headers. Twilio uses a caching proxy in its webhook pipeline and caches media files with cache headers. Serving media out of Twilio's cache can take 10ms or less. As we run a fleet of caching proxies, it may take multiple requests before all of the proxies have a copy of your file in cache.

When a <Gather> reaches its timeout without any caller input, call control falls to the next verb in your original TwiML document.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
const gather = response.gather({
6
    action: '/process_gather.php',
7
    method: 'GET'
8
});
9
gather.say('Enter something, or not');
10
response.redirect({
11
    method: 'GET'
12
}, '/process_gather.php?Digits=TIMEOUT');
13

14
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<!-- page located at http://example.com/gather_hints.xml -->
3
<Response>
4
    <Gather action="/process_gather.php" method="GET">
5
        <Say>Enter something, or not</Say>
6
    </Gather>
7
    <Redirect method="GET">
8
        /process_gather.php?Digits=TIMEOUT
9
    </Redirect>
10
</Response>

You might face a few common issues when working with <Gather>:

If you encounter other issues with <Gather>, reach out to our support team for assistance.

You can download all available languages as a .csv file.

• Eleven Best Practices, Tips, and Tricks for using Speech Recognition and Virtual Agent Bots with Voice Calling on the Twilio CPaaS Platform