Skip to main content

<Gather>

Collects DTMF (keypress) input from the caller. When the caller presses digits, Exotel POSTs them to your action URL and you return the next ExoML response.

Attributes​

AttributeRequiredDefaultDescription
actionNoCurrent URLURL to POST the collected digits to
methodNoPOSTHTTP method for the action request: GET or POST
numDigitsNo—Stop collecting after this many digits
timeoutNo5Seconds to wait for input before timing out
finishOnKeyNo#Key that terminates input early. Set to empty string "" to disable
maxDigitsNo—Alias for numDigits

Syntax​

<Gather numDigits="1" action="https://your-app.example.com/ivr" timeout="5">
<Say>Press 1 for Sales, 2 for Support, or 3 to repeat this menu.</Say>
</Gather>

Nesting​

<Gather> can contain <Say> or <Play> to prompt the caller:

<Gather numDigits="1" action="https://your-app.example.com/route">
<Play>https://cdn.example.com/ivr-prompt.wav</Play>
</Gather>

Action URL parameters​

When input is collected, Exotel POSTs to your action URL with these additional parameters:

ParameterDescription
DigitsPressedThe digits the caller pressed
CallSidCall identifier
CallFromCaller's number
CallToYour ExoPhone
CallStatusCurrent call status

Example — multi-level IVR​

from flask import Flask, request, Response

app = Flask(__name__)

@app.route('/ivr', methods=['POST'])
def ivr():
return Response("""<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Gather numDigits="1" action="/ivr/main" timeout="5">
<Say>Press 1 for Sales. Press 2 for Support. Press 3 for Billing.</Say>
</Gather>
<Say>No input received. Goodbye.</Say>
<Hangup/>
</Response>""", mimetype='text/xml')

@app.route('/ivr/main', methods=['POST'])
def ivr_main():
digit = request.form.get('DigitsPressed', '')
routes = {
'1': '+919876540001', # Sales
'2': '+919876540002', # Support
'3': '+919876540003', # Billing
}
if digit in routes:
return Response(f"""<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Connecting you now.</Say>
<Dial>{routes[digit]}</Dial>
</Response>""", mimetype='text/xml')
else:
return Response("""<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Invalid option. Goodbye.</Say>
<Hangup/>
</Response>""", mimetype='text/xml')

Timeout handling​

If the caller doesn't press any digit within timeout seconds:

  • Exotel falls through to the next verb after <Gather> in the same <Response>
  • Your fallback verb runs (usually <Say> + <Hangup>)
<Response>
<Gather numDigits="1" action="/ivr/route" timeout="5">
<Say>Press 1 for Sales.</Say>
</Gather>
<!-- Runs only if Gather times out -->
<Say>We did not receive your input. Goodbye.</Say>
<Hangup/>
</Response>

Legs API — Gather action​

For collecting DTMF on an active leg via the Legs API:

curl -u '<api_key>:<api_token>' -X POST \
'https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs/<leg_sid>/actions' \
-H 'Content-Type: application/json' \
-d '{
"exoml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Flow><Gather numDigits=\"1\" timeout=\"5\"><StartSay>Press 1 to confirm your appointment.</StartSay></Gather></Flow>"
}'

Events emitted​

EventDescription
gather_inputCaller pressed digit(s); DigitsPressed field contains input
gather_timeoutNo digits received within the timeout window
gather_completedGather finished (either input or timeout)