<Gather>

The <Gather> verb is used to collect digits or transcribe speech during a call.

<Gather> Attributes

<Gather> supports the following attributes that change its behavior:

Attribute	Allowed Values	Default Value
action	relative or absolute URL	none
actionOnEmptyResult	true,false	false
finishOnKey	0-9,#,*, and '' (the empty string)	#
input	dtmf,speech,dtmf speech	dtmf
language	BCP-47 language tags	en-US
history	disable, compact, full	disable
method	GET, POST	POST
numDigits	integer > 0	unlimited
output	alphanumeric name	none
profanityFilter	true,false	false
speechTimeout	integer > 0 or auto	timeout attribute value
timeout	integer > 0	5

action

The action attribute accepts an absolute or relative URL as its argument. When the caller finished entering digits (or the timeout is reached), Voxtelesys will make an HTTP request to this URL.

After <Gather> ends and Voxtelesys sends its request to your action URL, the current call will continue using the VoXML you send back from that URL. Because of this, any VoXML verbs that occur after your <Gather> are unreachable if action is provided.

If you do not provide an action parameter, Voxtelesys will continue onto the next verb in the current VoXML document.

See additional parameters sent on the action webhook.

actionOnEmptyResult

The actionOnEmptyResult attribute allows you to force <Gather> to send a webhook to the action URL even when there is no DTMF input. By default, if <Gather> times out while waiting for DTMF input, it will continue on to the next VoXML instruction.

finishOnKey

The finishOnKey attribute lets you set a value that your caller can press to submit their digits.

For example, if you set finishOnKey to # and your caller enters 1234#, Voxtelesys will immediately stop waiting for more input after they press # and will store 1234 as the entered digits.

If you use an empty string, <Gather> will capture all user input and no key will end the <Gather>. In this case, Voxtelesys ends the <Gather> only after the timeout is reached.

input

The input attribute specifies which inputs (DTMF or speech) Voxtelesys should accept.

If you set input to speech, Voxtelesys will gather speech from the caller for a maximum duration of 60 seconds.

If you set dtmf speech for your input, the first detected input (speech or dtmf) will take precedence. If speech is detected first, finishOnKey will be ignored.

language

The language attribute specifies the language Voxtelesys should recognize from your caller.

This value defaults to en-US.

Acceptables values include: zh-CN,zh-TW,da,nl,en,en-AU,en-IN,en-NZ,en-GB,en-US,fr,fr-CA,de,hi,hi-Lat,id,it,ja,ko,no,pl,pt,pt-BR,pt-PT,ru,es,es-419,sv,ta,tr,uk.

history

The history attribute determines if the <Gather> verb should be logged in the history array of the CDR. The default is to not log.

For <Gather>, the compact and full values log the following payload to the history array respectively.

compact

{
  "payload": {
    "input": "dtmf",
    "action": "/next"
  }
}

full

{
  "payload": {
    "input": "dtmf",
    "action": "/next",
    "timeout": "5",
    "numDigits": "1",
    "finishOnKey": "#"
  }
}

The <Gather> verb will also generate an element in the history array for the user's input, if either compact or full is used.

{
  "payload": {
    "digits": "1234",
    "speech": ""
  }
}

method

The method attribute accepts either GET or POST. This tells Voxtelesys whether to request the action URL via HTTP GET or POST, with POST as its default value.

numDigits

The numDigits attribute sets the number of digits you expect from your caller.

The numDigits attribute only applies to DTMF input.

For example, you might wish to set numDigits="5" when asking your caller to enter their 5-digit zip code. Once the caller enters the final digit of 94117, Voxtelesys will immediately submit the data to your action URL.

output

The output attribute accepts an alphanumeric variable name, up to 50 characters. The final status of <Gather> is saved to this variable via the <output>.digits and <output>.speech variables.

profanityFilter

The profanityFilter specifies if Voxtelesys should filter profanities out of your speech transcription. This attribute defaults to false, which replaces all but the intial character in each filtered profane word with asterisks, e.g., 'f***.'

If you set this attribute to false, Voxtelesys will no longer filter any profanities in your transcriptions.

speechTimeout

The speechTimeout sets the limit (in seconds) that Voxtelesys will wait after a pause in speech before it stops its recognition. This only applies to speech input.

If you use both timeout and speechTimeout in your <Gather>, timeout will take precedence for DTMF input and speechTimeout will take precedence for speech.

If you set speechTimeout to auto, Voxtelesys will stop speech recognition when there is a pause in speech and return the results immediately.

timeout

The timeout allows you to set the limit (in seconds) that Voxtelesys will wait for the caller to press another digit or say another word before it sends data to your action URL.

For example, if timeout is 3, Voxtelesys waits three seconds for the caller to press another key or say another word before submitting their data.

Voxtelesys will wait until all nested verbs execute before it begins the timeout period.

<Gather> Verbs

You may choose to nest the following verbs within <Gather>:

• <Pause>
• <Say>
• <Play>

<Gather> Webhooks

action Webhook

If you specify an action URL, Voxtelesys will send a webhook with the following additional parameters:

Parameter	Description
Digits	The collected DTMF.
SpeechResult	The collected transcribed speech.

<Gather> Examples

Simple Usage

Welcome the caller and collect DTMF.

<Response>
  <Gather input="dtmf" action="/next">
    <Say>Hello, to speak with support press one, for sales press two.</Say>
  </Gather>
</Response>