Twilio

Gather Verb

The <Gather> verb collects digits entered by a caller into their telephone keypad. When the caller is done entering data, Twilio submits that data to a provided URL, as either a HTTP GET or POST request, just like a web browser submits data from an HTML form.

If no input is received before timeout, <Gather> falls through to the next verb in the TwiML document.

You may optionally nest <Say> and <Play> verbs within a <Gather> verbs while waiting for input. This allows you to read menu options to caller while letting them enter a menu selection at any time. After the first digit is received, the audio will stop playing.

Nouns

<Gather> does not have any expected "noun" body values.

Form Parameters

When <Gather> finishes receiving input from a caller, it submits the following parameter to the action URL.

Verb Attributes

action

The action attribute takes an absolute or relative URL as an argument.
When a caller completes entering data, Twilio will make a GET or POST request to this URL with the form parameter "Digits". If no action is provided, the default value is the URL of the of the current document.

method

The method attribute takes the value GET or POST. This tells Twilio whether to submit the action URL as a GET or POST method. This attribute is modeled after the HTML form method attribute. POST is the default value.

timeout

The timeout attribute sets the limit in seconds that <Gather> waits for the caller to press another digit. For example, if timeout="10", Twilio would wait 10 seconds for the caller to press a key before submitting the results to the action URL.

finishOnKey

The finishOnKey attribute lets you choose one value that submits the received data when entered. For example, if you set finishOnKey="#", and the user enters 1234#, Twilio will immediately stop waiting for more input when the # is received and will submit Digits=1234 to the action URL. Note that the finishOnKey digit is not sent. The allowed values are the numbers 0-9, # , * and the empty string (finishOnKey=""). If the empty string is sent, <Gather> captures all input and no key will end the <Gather> when pressed. The default is #.
The value must only be a single character.

numDigits

The numDigits attribute lets you set the number of digits you are expecting, and submits the data to the action URL when that number is reached. For example, one might set numDigits="5" and ask the caller to enter their 5 digit zip code.
When the caller enters the fifth digit of 94117, Twilio will immediately submit the data to its action URL.

Nesting Rules

The <Gather> verb can be nested in the following elements:

• <Response>

The following elements can be nested within <Gather>

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

Examples

Example 1: Default behavior of Gather

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

This is the simplest case for a <Gather>. When Twilio executes this verb the application will pause for up to 5 seconds, waiting for the caller to enter digits on their keypad.

• If they enter digits followed by a # symbol, Twilio submits those Digits as a POST back to the pages URL, http://example.com/simple_gather.xml
• If they enter digits followed by 5 seconds of silence, Twilio submits those Digits as a POST back to the pages URL, http://example.com/simple_gather.xml
• If they don't enter any digits and 5 seconds passes, Twilio does not submit to the URL, but instead moves on to the next verb in the file.
  If there are no more verbs, Twilio hangs up

Example 2: Action/method and nested audio verb

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather action="/process_gather.php" method="GET">
        <Say>
            Please enter your account number, 
            followed by the pound sign
        </Say>
    </Gather>
    <Say>We didn't receive any input. Goodbye!</Say>
</Response>

This is a more complex case. First, we have added the action and method attributes. When digits are pressed on the keypad, they are submitted to the action URL.
Second, we have added a nested <Say> verb. This means that input can be gathered at any time during the <Say>.

• If the caller enters a digit during the speaking of the text, the <Say> verb will stop speaking and wait for digits, '#' sign, or a timeout.
• If <Gather> tag times out without input, the <Say> verb will complete and the <Gather> verb will exit without submitting. Twilio will then process the next verb in the document, which in this case is a <Say> verb which informs the caller that no input was received.
• If the caller enters 12345 and then hits # or allows five seconds to pass, Twilio will submit the digits as a GET request to http://yourserver/process_gather.php?Digits=12345.

Hints and Advanced Uses

• When there are nested <Say> and <Play> verbs, the timeout begins after either the audio completes, or the first key is pressed.

• When a <Gather> times out without user input, it will not submit to its action url, but will instead fall through to the next verb. If you wish to have the application submit on a timeout, use the <Redirect> verb:

  <?xml version="1.0" encoding="UTF-8"?>
  <Response>
      <Gather action="/process_gather.php" method="GET">
          <Say>Enter something, or not</Say>
      </Gather>
      <Redirect method="GET">
          /process_gather.php?Digits=TIMEOUT
      </Redirect>
  </Response>
  

  When <Gather> times out, Twilio moves on to the next verb, in this case <Redirect>. The <Redirect> verb instructs Twilio to make a new GET request to "/process_gather.php?Digits=TIMEOUT".

Troubleshooting

• Problem: <Gather> isn't receiving caller input when using a VoIP phone.
  Solution: Some VoIP phones have trouble sending DTMF digits. This is usually because these phones use compressed, bandwidth conserving audio protocols that interfere with the transmission of the digit's signal. Consult your phone's documentation on DTMF problems.