Gather

The Gather verb is used to collect digits for some period of time.

Text Content

There is no text content available to be set for the <Gather> verb.

Attributes

Attribute	Description
gatherUrl	(optional) URL to send Gather event to and request new BXML. May be a relative URL.
gatherMethod	(optional) The HTTP method to use for the request to `gatherUrl`. GET or POST. Default value is POST.
gatherFallbackUrl	(optional) A fallback url which, if provided, will be used to retry the Gather event callback delivery in case `gatherUrl` fails to respond.
gatherFallbackMethod	(optional) The HTTP method to use to deliver the Gather event callback to `gatherFallbackUrl`. GET or POST. Default value is POST.
username	(optional) The username to send in the HTTP request to `gatherUrl`.
password	(optional) The password to send in the HTTP request to `gatherUrl`.
fallbackUsername	(optional) The username to send in the HTTP request to `gatherFallbackUrl`.
fallbackPassword	(optional) The password to send in the HTTP request to `gatherFallbackUrl`.
tag	(optional) A custom string that will be sent with this and all future callbacks unless overwritten by a future `tag` attribute or `<Tag>` verb, or cleared. May be cleared by setting `tag=""` Max length 256 characters.
terminatingDigits	(optional) When any of these digits are pressed, it will terminate the Gather. Default value is `""`, which disables this feature.
maxDigits	(optional) Max number of digits to collect. Default value is 50. Range: decimal values between 1 - 50.
interDigitTimeout	(optional) Time (in seconds) allowed between digit presses before automatically terminating the Gather. Default value is 5. Range: decimal values between 1 - 60.
firstDigitTimeout	(optional) Time (in seconds) to pause after any audio from nested `<SpeakSentence>` or `<PlayAudio>` verb is played (in seconds) before terminating the Gather. Default value is 5. Range: decimal values between 0 - 60.
repeatCount	(optional) The number of times the audio prompt should be played if no digits are pressed. For example, if this value is `3`, the nested audio clip will be played a maximum of three times. The delay between repetitions will be equal to `firstDigitTimeout`. Default value is 1. `repeatCount` * number of verbs must not be greater than 20.

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

The user presses a terminating digit (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.

Nestable Verbs

The following verbs may be nested inside of a <Gather> tag. If using a repeat count of one, up to 20 verbs can be nested. Refer to repeatCount attribute if using a value greater than 1.

Verb	Description
SpeakSentence	(optional/) Using the SpeakSentence inside the Gather verb will speak the text until a digit is received.
PlayAudio	(optional/) Using the PlayAudio inside the Gather verb will play the media until a digit is received.

Webhooks Received

Callback	Can reply with more BXML
Gather	Yes

Examples

Simple gather

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <Gather gatherUrl="https://gather.url/nextBXML" firstDigitTimeout="10" terminatingDigits="#">
      <SpeakSentence voice="kate">Please press a digit.</SpeakSentence>
   </Gather>
</Response>

SpeakSentence speakSentence = new SpeakSentence("Please press a digit.").builder()
         .locale(TtsLocale.EN_UK)
         .gender(TtsGender.FEMALE)
         .build();

Gather gather = new Gather().builder()
        .gatherUrl("https://gather.url/nextBxml")
        .terminatingDigits("#")
        .firstDigitTimeout(10d)
        .children(List.of(speakSentence))
        .build();

Response response = new Response()
         .with(gather);

System.out.println(response.toBXML());

SpeakSentence speakSentence = new SpeakSentence
{
    Sentence = "Please press a digit.",
    Voice = "kate"
};

Gather gather = new Gather
{
    GatherUrl = "https://gather.url/nextBXML",
    TerminatingDigits = "#",
    FirstDigitTimeout = 10,
    SpeakSentence = speakSentence
};

Response response = new Response();
response.Add(gather);

Console.WriteLine(response.ToBXML());

speak_sentence = Bandwidth::Bxml::SpeakSentence.new('Please press a digit.', { voice: 'kate' })
gather = Bandwidth::Bxml::Gather.new([speak_sentence], {
  gather_url: 'https://gather.url/nextBXML',
  terminating_digits: '#',
  first_digit_timeout: 10
})
response = Bandwidth::Bxml::Response.new([gather])

p response.to_bxml

const speakSentence = new Bxml.SpeakSentence('Please press a digit.', {
    voice: 'kate'
});
const gather = new Bxml.Gather(
    {
        gatherUrl: 'https://gather.url/nextBXML',
        terminatingDigits: '#',
        firstDigitTimeout: 10
    },
    [speakSentence]
);
const response = new Bxml.Response(gather);

console.log(response.toBxml());

speak_sentence = SpeakSentence(
    text="Please press a digit.",
    voice="kate"
)

gather = Gather(
    gather_url="https://gather.url/nextBXML",
    terminating_digits="#",
    first_digit_timeout=10
    audio_verbs=[speak_sentence]
)

response = Response()
response.add_verb(gather)

print(response.to_bxml())

$speakSentence = new BandwidthLib\Voice\Bxml\SpeakSentence("Please press a digit.");
$speakSentence->voice("kate");

$gather = new BandwidthLib\Voice\Bxml\Gather();
$gather->gatherUrl("https://gather.url/nextBXML");
$gather->terminatingDigits("#");
$gather->firstDigitTimeout(10);
$gather->speakSentence($speakSentence);

$response = new BandwidthLib\Voice\Bxml\Response();
$response->addVerb($gather);

echo $response->toBxml();

Gather with Repeated Audio Prompt

<Response>
   <Gather gatherUrl="https://gather.url/nextBXML" repeatCount="5" maxDigits="1">
      <SpeakSentence>I am going to keep asking you to press a digit.</SpeakSentence>
   </Gather>
</Response>

SpeakSentence speakSentence = new SpeakSentence("I am going to keep asking you to press a digit.");

Gather gather = new Gather().builder()
        .gatherUrl("https://gather.url/nextBxml")
        .repeatCount(5)
        .maxDigits(1)
        .children(List.of(speakSentence))
        .build();

Response response = new Response()
         .with(gather);

System.out.println(response.toBXML());

SpeakSentence speakSentence = new SpeakSentence
{
    Sentence = "I am going to keep asking you to press a digit."
};

Gather gather = new Gather
{
    GatherUrl = "https://gather.url/nextBXML",
    RepeatCount = 5,
    MaxDigits = 1,
    SpeakSentence = speakSentence
};

Response response = new Response();
response.Add(gather);

Console.WriteLine(response.ToBXML());

speak_sentence = Bandwidth::Bxml::SpeakSentence.new('I am going to keep asking you to press a digit.')
gather = Bandwidth::Bxml::Gather.new([speak_sentence], {
  gather_url: 'https://gather.url/nextBXML',
  repeat_count: 5,
  max_digits: 1
})
response = Bandwidth::Bxml::Response.new([gather])

p response.to_bxml

const speakSentence = new Bxml.SpeakSentence(
    'I am going to keep asking you to press a digit.'
);
const gather = new Bxml.Gather(
    {
        gatherUrl: 'https://gather.url/nextBXML',
        repeatCount: 5,
        maxDigits: 1
    },
    [speakSentence]
);
const response = new Bxml.Response(gather);

console.log(response.toBxml());

speak_sentence = SpeakSentence(
    text="I am going to keep asking you to press a digit."
)

gather = Gather(
    gather_url="https://gather.url/nextBXML",
    repeat_count=5,
    max_digits=1,
    audio_verbs=[speak_sentence]
)

response = Response()
response.add_verb(gather)

print(response.to_bxml())

$speakSentence = new BandwidthLib\Voice\Bxml\SpeakSentence("I am going to keep asking you to press a digit.");

$gather = new BandwidthLib\Voice\Bxml\Gather();
$gather->gatherUrl("https://gather.url/nextBXML");
$gather->repeatCount(5);
$gather->maxDigits(1);
$gather->speakSentence($speakSentence);

$response = new BandwidthLib\Voice\Bxml\Response();
$response->addVerb($gather);

echo $response->toBxml();

Gather with Multiple Nested Verbs

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather gatherUrl="https://gather.url/nextBXML">
        <SpeakSentence>First Sentence.</SpeakSentence>
        <PlayAudio>https://audio.url/audio1.wav</PlayAudio>
        <PlayAudio>https://audio.url/audio2.mp3</PlayAudio>
        <SpeakSentence>Second Sentence.</SpeakSentence>
    </Gather>
</Response>

SpeakSentence speakSentence = new SpeakSentence("First sentence.");

SpeakSentence speakSentence2 = new SpeakSentence("Second sentence.");

PlayAudio playAudio = new PlayAudio().builder()
        .audioUri("https://audio.url/audio1.wav")
        .build();

PlayAudio playAudio2 = new PlayAudio().builder()
        .audioUri("https://audio.url/audio2.mp3")
        .build();

Gather gather = new Gather().builder()
        .gatherUrl("https://gather.url/nextBxml")
        .children(List.of(speakSentence, playAudio, speakSentence2, playAudio2))
        .build();

Response response = new Response()
         .with(gather);

System.out.println(response.toBXML());

Gather gather = new Gather
{
    GatherUrl = "https://gather.url/nextBXML",
    AudioProducers = new List<IAudioProducer>(){
        new SpeakSentence
        {
            Sentence = "First Sentence."
        },
        new PlayAudio
        {
            Url = "https://audio.url/audio1.wav"
        },
        new PlayAudio
        {
            Url = "https://audio.url/audio2.mp3"
        },
        new SpeakSentence
        {
            Sentence = "Second Sentence."
        }
    }
};

Response response = new Response();
response.Add(gather);

Console.WriteLine(response.ToBXML());

speak_sentence_1 = Bandwidth::Bxml::SpeakSentence.new('First Sentence.')
play_audio_1 = Bandwidth::Bxml::PlayAudio.new('https://audio.url/audio1.wav')
play_audio_2 = Bandwidth::Bxml::PlayAudio.new('https://audio.url/audio2.mp3')
speak_sentence_2 = Bandwidth::Bxml::SpeakSentence.new('Second Sentence.')
gather = Bandwidth::Bxml::Gather.new([speak_sentence_1, play_audio_1, play_audio_2, speak_sentence_2], {
  gather_url: 'https://gather.url/nextBXML'
})
response = Bandwidth::Bxml::Response.new([gather])

p response.to_bxml

const speakSentence1 = new Bxml.SpeakSentence('First Sentence.');
const playAudio1 = new Bxml.PlayAudio('https://audio.url/audio1.wav');
const playAudio2 = new Bxml.PlayAudio('https://audio.url/audio2.mp3');
const speakSentence2 = new Bxml.SpeakSentence('Second Sentence.');
const gather = new Bxml.Gather(
    {
        gatherUrl: 'https://gather.url/nextBXML'
    },
    [speakSentence1, playAudio1, playAudio2, speakSentence2]
);
const response = new Bxml.Response(gather);

console.log(response.toBxml());

speak_sentence_1 = SpeakSentence(
    text="First Sentence."
)

play_audio_1 = PlayAudio(
    audio_uri="https://audio.url/audio1.wav"
)

play_audio_2 = PlayAudio(
    audio_uri="https://audio.url/audio2.mp3"
)

speak_sentence_2 = SpeakSentence(
    text="Second Sentence."
)

gather = Gather(
    gather_url="https://gather.url/nextBXML",
    audio_verbs=[speak_sentence_1, play_audio_1, play_audio_2, speak_sentence_2]
)

response = Response()
response.add_verb(gather)

print(response.to_bxml())

$speakSentence1 = new BandwidthLib\Voice\Bxml\SpeakSentence("First Sentence.");

$playAudio1 = new BandwidthLib\Voice\Bxml\PlayAudio("https://audio.url/audio1.wav");

$playAudio2 = new BandwidthLib\Voice\Bxml\PlayAudio("https://audio.url/audio2.mp3");

$speakSentence2 = new BandwidthLib\Voice\Bxml\SpeakSentence("Second Sentence.");

$gather = new BandwidthLib\Voice\Bxml\Gather();
$gather->gatherUrl("https://gather.url/nextBXML");
$gather->speakSentence($speakSentence1);
$gather->playAudio($playAudio1);
$gather->playAudio($playAudio2);
$gather->speakSentence($speakSentence2);

$response = new BandwidthLib\Voice\Bxml\Response();
$response->addVerb($gather);

echo $response->toBxml();

Text Content​

Attributes​

Nestable Verbs​

Webhooks Received​

Examples​

Simple gather​

Gather with Repeated Audio Prompt​

Gather with Multiple Nested Verbs​