Skip to main content

How to Gather User Input (IVR)

In this guide we will show you how to collect digits inputted by a user on their phone’s keypad for a period of time. Please ensure you have followed our earlier guide on how to make an outbound call with Bandwidth.

You can gather a user’s input to create an interactive voice response (IVR) system.

Gathering User Input

The <Gather> verb is used to collect digits inputted by the user.

The gather is terminated when one of these conditions is met:

  • The user presses any one of the terminatingDigits (if specified)
  • The user has pressed at least one key and more than interDigitTimeout seconds have elapsed
  • Any nested audio has ended and firstDigitTimeout seconds have elapsed without the user pressing any digits
  • The user presses maxDigits digits
  • If the gatherUrl attribute is specified, the Gather event is sent to the gatherUrl upon completion of the gather. BXML returned by that callback are then executed. If gatherUrl is specified, verbs following the <Gather> will be ignored.

If no gatherUrl attribute is specified, the gathered digits are discarded and execution of verbs following the <Gather> continues.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<SpeakSentence>Input a digit to hear it read back to you.</SpeakSentence>
<Gather gatherUrl="/digitsCallback" maxDigits="1"/>
</Response>

And endpoint /digitsCallback should return:

//NOTE: This section of the application may look different depending on how your endpoints receive callback events

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<SpeakSentence>You input the number {digit}</SpeakSentence>
</Response>

The above number prompts the caller to input a number, after which the gather ends and a <SpeakSentence> says the pressed number back to the caller.

Advanced IVR System

To further enhance your IVR system, additional verbs can be nested inside of a <Gather> tag. These include playing media and text to speech. In this new example, the sentence "Please press a digit" will be said at the start of the call and after each press, instead of only at the beginning of the call.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Gather gatherUrl="/gatherCallback" repeatCount="3">
<SpeakSentence>Please listen to the menu of options.</SpeakSentence>
<PlayAudio>http://audio.test/englishMenuOptions.mp3</PlayAudio>
<PlayAudio>http://audio.test/spanishMenuOptions.mp3</PlayAudio>
</Gather>
</Response>

And endpoint /gatherCallback should return:

//NOTE: This section of the application may look different depending on how your endpoints receive callback events

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<SpeakSentence>You input the number {digit}</SpeakSentence>
</Response>

In this example, there is one <SpeakSentence> and two <PlayAudio> nested within the gather. If, after playing, the caller doesn't press a button, the audio will replay two more times.

Where to next?

Now that you have learnt how to build an IVR tree, check out some of the available actions in the following guides: