Gather XML Element – Collect DTMF & Speech Input

You can use the Gather XML element to collect user input through automatic speech recognition or DTMF “digit press” inputs. When collecting speech as input, Vobiz transcribes and relays a user’s speech to the specified action URL in real time. When collecting input through digit press, Vobiz relays the digits entered to the specified action URL. The Gather XML element supports simultaneous detection of both speech and digit press inputs.

Nesting elements

You can nest Speak XML (text-to-speech) and Play XML elements inside Gather XML to prompt users for inputs. This is useful for building interactive voice response (IVR) experiences.

Attributes

Attribute	Description
`action` string, required Callback-retry configurable	The input is sent to a specific URL. See the parameters sent to the action URL for more information. Allowed values: a fully qualified URL
`method` string	The HTTP method to use when invoking the action URL. Allowed values: `GET`, `POST` Default: `POST`
`inputType` string	The type of input you expect to receive. When set to `dtmf speech`, Vobiz listens for both speech and digit inputs. The input detected first is relayed to the action URL. Allowed values: `dtmf`, `speech`, `dtmf speech`
`executionTimeout` integer	Maximum input-detection time in seconds. If the user provides no input, Vobiz processes the next element. The timer starts after nested `Play` and `Speak` elements finish. Allowed values: `5` to `60` Default: `15`
`digitEndTimeout` string	Time in seconds allowed between consecutive digit inputs. If Vobiz receives no new digit during this period, it processes the digits already entered. Applies to `dtmf` and `dtmf speech`. Allowed values: `2` to `10`, or `auto` Default: `auto`
`speechEndTimeout` string	Time in seconds that Vobiz waits for more speech after detecting silence. Vobiz then stops recognition and sends the transcription to the action URL. Applies to `speech` and `dtmf speech`. Allowed values: `2` to `10`, or `auto` Default: `auto`
`finishOnKey` string	A digit the user can press to submit the collected digits. If set to `<empty string>` or `none`, capture ends based on a timeout or `numDigits`. Applies to `dtmf` and `dtmf speech`. Allowed values: exactly one of `0`–`9`, ``, `#`, `<empty string>`, or `none` Default:* `#`
`numDigits` integer	Maximum number of digits to collect. Vobiz sends the digits to the action URL as soon as it collects this number. Applies to `dtmf` and `dtmf speech`. Allowed values: `1` to `32` Default: `32`
`speechModel` string	The automatic speech recognition model used to transcribe speech. Applies to `speech` and `dtmf speech`. Allowed values: `default`, `command_and_search`, `phone_call` Default: `default` `command_and_search`: optimized for short voice commands and searches. `phone_call`: optimized for phone-call audio with inconsistent quality. `telephony`: an enhanced `phone_call` model for audio that typically originates from phone calls. `default`: optimized for audio that does not match a specialized model, such as long-form audio.
`hints` string	A list of phrases that can improve recognition probability. Provide phrases as single words or small groups of words. Applies to `speech` and `dtmf speech`. Allowed values: a non-empty, comma-separated string of phrases Limits: 500 phrases per request; 10,000 characters per request; 100 characters per phrase
`language` string	The language Vobiz should recognize. Applies to `speech` and `dtmf speech`. Allowed values: see the list of supported languages Default: `en-US`
`interimSpeechResultsCallback` string Callback-retry configurable	URL that receives real-time requests as Vobiz recognizes speech. See the interim speech callback parameters for more information. Applies to `speech` and `dtmf speech`. Allowed values: a fully qualified URL
`interimSpeechResultsCallbackMethod` string	The HTTP method used to invoke `interimSpeechResultsCallback`. Applies to `speech` and `dtmf speech`. Allowed values: `GET`, `POST` Default: `POST`
`log` boolean	If `true`, Vobiz logs digits or recognized speech from the caller. If `false`, Vobiz disables logging while it processes `Gather`. Allowed values: `true`, `false` Default: `true`
`redirect` boolean	If `true`, Vobiz redirects to the action URL. If `false`, Vobiz requests the URL and continues to the next element. Allowed values: `true`, `false` Default: `true`
`profanityFilter` boolean	If `true`, Vobiz masks profane words with their first letter and asterisks for the remaining characters, such as `f*`. The filter operates on single words and does not detect abusive or offensive phrases. Applies to `speech` and `dtmf speech`. Allowed values: `true`, `false` Default:** `false`

Parameters sent to the action URL

In addition to the standard action URL request parameters, these parameters are sent to the action URL specified.

Parameter	Description
`InputType`	The type of input detected. Allowed values: `dtmf`, `speech`
`Digits`	The digits entered by the caller, excluding the finishOnKey input, if used. Empty if `inputType` is `speech`.
`Speech`	The transcribed result of the caller’s speech. Empty if `inputType` is `dtmf`.
`SpeechConfidenceScore`	A confidence score between 0.0 and 1.0. The higher the score, the more likely the transcription is accurate.
`BilledAmount`	The total amount billed for speech input transcription.

Parameters sent to the interimSpeechResultsCallback URL

In addition to the standard callback URL request parameters, these parameters are sent to the interim speech results callback URL.

Parameter	Description
`StableSpeech`	The stable transcribed result of the user’s speech.
`UnstableSpeech`	The newer, unstable transcribed result of the user’s speech. This is an interim result and may change as more speech is gathered.
`Stability`	Likelihood that the recognizer will not change its guess about the interim result. Range: 0.0 (completely unstable) to 1.0 (completely stable). Only applies to unstable speech.
`SequenceNumber`	Sequence number of the interim speech callback, to help with ordering incoming callback requests.

Examples

Nest a Speak or Play element to prompt the caller. With numDigits="1", Vobiz posts to the action URL as soon as one digit is pressed.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather action="https://yourapp.com/menu-choice" method="POST"
            inputType="dtmf" numDigits="1" executionTimeout="10">
        <Speak>Press 1 for sales, 2 for support, or 0 for an operator.</Speak>
    </Gather>
    <Speak>We didn't receive your input. Goodbye.</Speak>
    <Hangup/>
</Response>

Collect a multi-digit number with finishOnKey

For variable-length input such as an account number, set finishOnKey="#" and let the caller signal completion.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather action="https://yourapp.com/account" method="POST"
            inputType="dtmf" numDigits="12" finishOnKey="#" executionTimeout="20">
        <Speak>Enter your account number, then press pound.</Speak>
    </Gather>
    <Redirect>https://yourapp.com/answer</Redirect>
</Response>

Collect speech input

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather action="https://yourapp.com/intent" method="POST"
            inputType="speech" language="en-US" speechEndTimeout="auto"
            hints="billing,support,sales">
        <Speak>In a few words, tell us what you're calling about.</Speak>
    </Gather>
    <Speak>Sorry, we didn't catch that.</Speak>
</Response>

Accept either speech or digits

With inputType="dtmf speech", whichever input Vobiz detects first is the one relayed to the action URL.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather action="https://yourapp.com/choice" method="POST"
            inputType="dtmf speech" numDigits="1" speechEndTimeout="auto">
        <Speak>Say "yes" or press 1 to confirm. Say "no" or press 2 to cancel.</Speak>
    </Gather>
</Response>

Webhook payload sent to the action URL

After the caller responds (or input ends), Vobiz POSTs the standard call parameters plus the Gather-specific parameters to your action URL.

DTMF input

POST /menu-choice HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded

CallUUID=xyz789&From=14155551234&To=14155559999&Direction=inbound&InputType=dtmf&Digits=1&Speech=

Speech input

POST /intent HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded

CallUUID=xyz789&From=14155551234&To=14155559999&Direction=inbound&InputType=speech&Digits=&Speech=I+have+a+billing+question&SpeechConfidenceScore=0.92&BilledAmount=0.0050

Edge cases and tips

No input / timeout. If the caller provides no input within executionTimeout seconds (counted after nested Play/Speak finishes), Vobiz moves on to the next element in the document. Always place fallback XML (a retry, a Redirect back to the menu, or a Hangup) after the Gather. By default, Vobiz still POSTs to the action URL with empty Digits and Speech on timeout - check for empty values in your handler.
Use executionTimeout, never timeout. Gather has no timeout attribute. Use Dial timeout to limit how long Vobiz waits for a B-leg to answer. The valid range for executionTimeout is 5-60 seconds (default 15).
finishOnKey is excluded from Digits. The terminating key (default #) is not included in the Digits parameter. Set finishOnKey="" or finishOnKey="none" to rely solely on numDigits or the timeout.
numDigits ends collection early. Vobiz posts as soon as it collects numDigits digits, before the timeout or finishOnKey. For single-key menus, set numDigits="1" for the snappiest response.
DTMF vs speech. Use dtmf for menus and structured input (account numbers, PINs) - it is precise and free. Use speech for open-ended intent capture; it incurs a per-request charge (see Pricing for speech recognition) and returns a SpeechConfidenceScore you should threshold before acting. Combine with dtmf speech when you want to accept both.
Improve recognition. Pass domain words via hints, set the correct language (see supported languages), and pick a speechModel suited to the input (command_and_search for short commands, phone_call/telephony for call audio).
Validate input server-side. Never trust Digits or Speech directly in queries or business logic - sanitize and range-check them in your handler.

XML Overview

Gather XML Element – Collect DTMF & Speech Input | Vobiz

Nesting elements

Attributes

Parameters sent to the action URL

Parameters sent to the interimSpeechResultsCallback URL

Examples

Collect a single DTMF digit (IVR menu)

Collect a multi-digit number with finishOnKey

Collect speech input

Accept either speech or digits

Webhook payload sent to the action URL

Edge cases and tips

​Nesting elements

​Attributes

​Parameters sent to the action URL

​Parameters sent to the interimSpeechResultsCallback URL

​Examples

​Collect a single DTMF digit (IVR menu)

​Collect a multi-digit number with finishOnKey

​Collect speech input

​Accept either speech or digits

​Webhook payload sent to the action URL

​Edge cases and tips

Nesting elements

Attributes

Parameters sent to the action URL

Parameters sent to the interimSpeechResultsCallback URL

Examples

Collect a single DTMF digit (IVR menu)

Collect a multi-digit number with finishOnKey

Collect speech input

Accept either speech or digits

Webhook payload sent to the action URL

Edge cases and tips