TelAPI

InboundXML Documentation

View REST Docs

Gather Element

The <Gather> element allows callers to input digits to the call using their keypads which are then sent via POST or GET to a URL for further processing. There are many ways to get creative with <Gather> but its most common use case is in creating IVR menus. This is accomplished by nesting prompts for input from the caller using the <Say> or <Play> elements.

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, and the gathered digits will be submitted to the current InboundXML document. This default behaviour of <Gather> can be altered using its provided element attriubutes.

Element Attributes

The attributes below can be used to change some <Gather> behaviors.

Attribute Description
action
optional
URL where the flow of the call and the gathered digits will be forwarded to (if digits are input).
method
optional
Method used to request the action URL.
Default Value:
POST
Allowed Value:
POST or GET
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.
Default Value:
5
Allowed Value:
integer greater than or equal to 0
finishOnKey
optional
The key a caller can press to end the <Gather>.
Default Value:
#
Allowed Value:
the digits 0-9, #, or *
numDigits
optional
The maximum number of digits to <Gather>.
Default Value:
no limit
Allowed Value:
integer greater than or equal to 0

action URL Parameters

In addition to the default voice request parameters, this gather specific parameter is also forwarded to the action URL.

Parameter Description
Digits
optional
All gathered digits, not including finishOnKey.
Example Value:
123

Nesting

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

The <Say>, <Play>, and <Pause> elements can all be nested within the <Gather> element.

Example InboundXML Document

The InboundXML below will prompt the caller for a four digit pin and then forward the input digits to the action URL using the GET method.

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

Helper Example

Our helper libraries simplify the task of generating InboundXML while programming. The code below will output the above InboundXML example.



Tips

  • 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.