<Gather>

The <Gather> element allows callers to input digits to the call using their phone's keypad which are then sent via POST or GET to a URL for processing.

There are many ways to get creative with <Gather> but its most common use case is in creating IVR menus. This is done by nesting prompts for input from the caller using the <Say> or <Play> elements. Only a single <Say> or <Play> element can be nested in a <Gather> tag.

By default an unlimited number of digits can be gathered. The <Gather> will timeout after 5 seconds pass without any new digits or once the '#' key is pressed, then the gathered digits will be submitted to the current InboundXML document. This default behavior of <Gather> can be altered using its provided element attributes.

Element Attributes

Attribute	Description
`action`optional	The URL where the flow of the call and the gathered digits will be forwarded to.
`method`optional	Method used to request the action URL. Valid values: POST, GET Default value: POST
`timeout`optional	The number of seconds `<Gather>` should wait for digits to be entered before requesting the action URL. Timeout resets with each new digit input. If a timeout event occurs the `Digits` variable passed will be empty. Valid values: integer greater than or equal to 0 Default value: 5
`finishOnKey`optional	The key a caller can press to end the `<Gather>`. Valid values: digits 0 to 9, #, or * Default value: #
`numDigits`optional	The maximum number of digits to `<Gather>`. Valid values: integer greater than or equal to 1 Default value: 1

Nesting

The <Gather> element cannot be nested within any other verbs besides the default <Response> element.

The <Say> and <Play> elements MUST be nested within the <Gather> element.

<Response>
  <Gather action='http://your-url.com/' method='GET' numDigits='4' finishOnKey='#'>
    <Say>Please enter your 4 digit pin</Say>
  </Gather>
</Response>

📘
Tip

If nested <Say> or <Play> elements are present, the timeout attribute starts after either the first key to be gathered is pressed or say/play prompt completes.

If the <Gather> verb fails to execute, the next verb below it will execute if it is present.