Voice

Gather

View as Markdown

The <Gather> verb transcribes speech or collects digits during a call.

Verb attributes

action
string

The action attribute takes in an absolute URL. SignalWire will make a GET or POST request to this URL when entering of digits is completed. If there is no URL provided, SignalWire will re-request the URL that was previously used, which can cause an unwanted looping behavior. Be sure to provide the proper URL in order to avoid this outcome. See below for specified request parameters.

actionOnEmptyResult
booleanDefaults to false

Send a webhook to the action URL even if there is no input. By default, if no input is detected, the next XML instruction is executed but by setting actionOnEmptyResult to true, a callback to the action URL will be sent to continue call flow.

enhanced
booleanDefaults to false

This attribute enables enhanced speech recognition, which will incur an added cost. When it is false, speechModel has no effect.

finishOnKey
stringDefaults to #

The set of digits, (0-9, *, #), that can end a recording.

hints
string

A list of words and phrases, each a max of 100 characters, a caller is likely to say during a call.

input
stringDefaults to dtmf

The type of input received from a caller (i.e. speech or DTMF). Values can be dtmf, speech, or dtmf speech.

language
stringDefaults to en-US

The language in which you expect your callers to speak.

method
stringDefaults to POST

The method attribute specifies whether the request to action is a GET or a POST. Valid values are GET or POST.

numDigits
integer

The number of digits you expect to be pressed by a caller.

partialResultCallback
string

The URL to request to during speech recognition. No URL is specified by default.

partialResultCallbackMethod
stringDefaults to POST

The type of HTTP request to use when requesting a partialResultCallback.

profanityFilter
booleanDefaults to true

Tells SignalWire whether or not to filter profane language when transcribing a call.

speechModel
string

The model of enhanced speech recognition you would like to use. This attribute only has an effect if enhanced is true. Valid values are phone_call, video, or default. phone_call optimizes speech recognition for phone calls at a 8khz sample rate. video optimizes speech recognition for video calls at a 16khz sample rate. default will automatically choose the current best option between phone_call and video.

speechTimeout
string

The set time, in seconds, that SignalWire will wait before ending speech recognition. If set to auto, SignalWire will automatically end speech recognition when there is a pause in speech.

timeout
integerDefaults to 5

The number of seconds of silence or inaction that denote the end of caller input.

Supported languages

You can find a list of our supported languages here.

Request parameters for action URL

The action request contains the Standard Request Parameters as well as:

Confidence
string

The score, between 0.0 and 1.0, that determines the accuracy of a transcription.

Digits
string

The buttons pressed by a caller.

SpeechResult
string

The transcribed result of the caller’s speech.

Nesting

The following verbs can be nested within a <Gather>:

  • <Play>: plays an audio file, that SignalWire fetches from the URL you configured, back to the caller.
  • <Pause>: waits silently for a distinctive number of seconds.
  • <Say>: reads supplied text back to the caller.

Examples

Handle gathered input on your server

This example demonstrates a complete flow: the initial cXML prompts the caller for input, and your server handles the POST request to process Digits or SpeechResult and respond with appropriate cXML.

This cXML is served to SignalWire (e.g., as your webhook response). It prompts the caller for input and specifies your server’s action URL to handle the result.

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Gather input="speech dtmf" action="https://example.com/handle-gather" method="POST"
4            numDigits="1" hints="sales, support, billing" timeout="5" speechTimeout="auto">
5        <Say>
6            Press 1 or say sales for sales.
7            Press 2 or say support for technical support.
8            Press 3 or say billing for billing questions.
9        </Say>
10    </Gather>
11    <Say>We did not receive any input. Goodbye!</Say>
12</Response>

A simple gather

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Gather/>
4</Response>

SignalWire will collect any speech or digits pressed during a call.

Nesting <Say> within a gather

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Gather action="https://example.com/process_gather.php" method="GET">
4        <Say>
5            Please enter your account number,
6            followed by the pound sign.
7        </Say>
8    </Gather>
9    <Say>We did not receive any input. Goodbye!</Say>
10</Response>

You can use the <Say> verb to prompt callers to enter the desired input. In this example, when a caller enters their account number, SignalWire will submit the result to the URL provided in the action attribute. If the caller does not enter any digits, SignalWire will prompt the ‘Goodbye’ statement.

Nesting <Play> within a gather

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Gather action="https://example.com/process_gather.php" method="GET">
4        <Play>https://your-application.com/audio.mp3</Play>
5    </Gather>
6    <Say>We did not receive any input. Goodbye!</Say>
7</Response>

You can use the <Play> verb to prompt callers to enter the desired input. In this example, when a caller enters their account number, SignalWire will submit the result to the URL provided in the action attribute. If the caller does not enter any digits, SignalWire will prompt the ‘Goodbye’ statement.

Gather DTMF or speech

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Gather input="speech dtmf" timeout="5" numDigits="1">
4        <Say>Please press 3 or say account for account information.</Say>
5    </Gather>
6</Response>

A caller can access their account information either through speech recognition or DTMF tones. SignalWire will wait 5 seconds before processing the information and sending the data.

Potential issues

<Gather> doesn’t receive caller input when the caller is using a VoIP phone.

Solution: Some VoIP phones have trouble sending DTMF tones. Phones typically use compressed bandwidth-conserving audio protocols that can interfere with the transmission of the digit’s signal.

The Digits parameter is not sent to the <Gather> URL.

Solution: Verify that your application is not responding to the action URL with an HTTP 3xx redirect. SignalWire will follow this redirect but will not resend the Digits parameter.