<Gather>The <Gather> verb collects digits that a caller enters into his or her telephone
keypad. When the caller is done entering data, Twilio submits that data to the provided
'action' URL in an 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> verb while waiting for input. This allows you to read menu
options to the caller while letting her enter a menu selection at any time. After the first
digit is received the audio will stop playing.
The <Gather> verb supports the following attributes that modify its behavior:
| Attribute Name | Allowed Values | Default Value |
|---|---|---|
| action | relative or absolute URL | current document URL |
| method | GET, POST | POST |
| timeout | positive integer | 5 seconds |
| finishOnKey | any digit, #, * | # |
| numDigits | integer >= 1 | unlimited |
The 'action' attribute takes an absolute or relative URL as a value. When the caller has finished entering digits Twilio will make a GET or POST request to this URL including the parameters below. If no 'action' is provided, Twilio will by default make a POST request to the current document's URL.
After making this request, Twilio will continue the current call using the TwiML received
in your response. Keep in mind that by default Twilio will re-request
the current document's URL, which can lead to unwanted looping behavior if you're not careful.
Any TwiML verbs occuring after a <Gather> are unreachable, unless the caller enters no digits.
If the 'timeout' is reached before the caller enters any digits, or if the caller enters the
'finishOnKey' value before entering any other digits, Twilio will not make a request
to the 'action' URL but instead continue processing the current TwiML document with the
verb immediately following the <Gather>.
Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the 'action' URL:
| Parameter | Description |
|---|---|
| Digits | The digits the caller pressed, excluding the finishOnKey digit if used. |
The 'method' attribute takes the value 'GET' or 'POST'. This tells Twilio whether to request the 'action' URL via HTTP GET or POST. This attribute is modeled after the HTML form 'method' attribute. 'POST' is the default value.
The 'timeout' attribute sets the limit in seconds that Twilio will wait for the caller to press another digit before moving on and making a request to the 'action' URL. For example, if 'timeout' is '10', Twilio will wait ten seconds for the caller to press another key before submitting the previously entered digits to the 'action' URL. Twilio waits until completing the execution of all nested verbs before beginning the timeout period.
The 'finishOnKey' attribute lets you choose one value that submits the
received data when entered. For example, if you set 'finishOnKey' to '#' 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' value is not sent. The allowed values are the digits 0-9, '#'
, '*' and the empty string (set 'finishOnKey' to ''). If the empty string is used, <Gather> captures
all input and no key will end the <Gather> when pressed. In this case Twilio will
submit the entered digits to the 'action' URL only after the timeout has been reached.
The default 'finishOnKey' value is '#'. The value can only be a single character.
The 'numDigits' attribute lets you set the number of digits you are expecting, and submits the data to the 'action' URL once the caller enters that number of digits. For example, one might set 'numDigits' to '5' and ask the caller to enter a 5 digit zip code. When the caller enters the fifth digit of '94117', Twilio will immediately submit the data to the 'action' URL.
You can nest the following verbs within <Gather>:
But you can't nest <Gather> within any other verbs.
This is the simplest case for a <Gather>. When Twilio executes this TwiML
the application will pause for up to five seconds, waiting for the caller to
enter digits on her keypad.
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/simple_gather.xml -->
<Response>
<Gather/>
</Response>
<Say> or <Play> verbIn this more complex example we add the 'action' and 'method' attributes.
After the caller enters digits on the keypad, Twilio sends them in a request to the 'action' URL.
We also add a nested <Say> verb.
This means that input can be gathered at any time during <Say>.
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/complex_gather.xml -->
<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>
<?php // page located at http://example.com/process_gather.php echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"; echo "<Response><Say>You entered " . $_REQUEST['Digits'] . "</Say></Response>"; ?>
<Say> verb will stop speaking and wait for digits, '#' sign, or a timeout.<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.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"?>
<!-- page located at http://example.com/gather_hints.xml -->
<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".
<Gather> isn't receiving caller input when using a VoIP phone.