Verbs

<Gather>

Collect digits or speech from the caller and post the result to your server.

Example

<Response>
  <Gather input="dtmf speech" numDigits="1" timeout="5"
          action="https://app.example.com/menu" method="POST">
    <Say>For sales, press 1 or say sales. For support, press 2 or say support.</Say>
  </Gather>
  <Redirect>https://app.example.com/no-input</Redirect>
</Response>

Attributes

Attribute Default Behaviour
input dtmf Input mode: dtmf, speech, or dtmf speech (tokens in any order, space or comma separated). In combined mode, whichever modality completes first wins; a key press during speech terminates collection immediately. Unrecognised tokens are ignored.
action current document URL URL that receives the result. When omitted, the current document URL is re-requested with the result fields — menu-style IVRs rely on this to re-render with the pressed digit. For inline documents with no source URL, an omitted action falls through to the next verb.
method POST HTTP method for the action request: POST or GET.
numDigits unlimited Maximum number of digits to collect. When unset, collection waits for finishOnKey or timeout.
timeout 5 Seconds of silence between digits before the gather returns.
finishOnKey # Digit that ends collection. Set to an empty string to disable.
actionOnEmptyResult false By default the action request is skipped when no input was captured and execution falls through to the next verb. Set true to post to the action URL even on empty input.
speechTimeout auto Seconds of trailing silence before speech is considered final. auto lets the recognizer decide when the caller has finished speaking.
maxSpeechTime 30 Hard cap on speech duration in seconds.
language en-US BCP-47 recognition language.
speechModel engine default Recognizer model hint, passed through to the configured speech engine.
hints unset Comma-separated phrases that bias recognition toward expected words.
enhanced false Opt into the premium recognition model where the configured engine offers one.
profanityFilter true Mask profanities in the transcript.
partialResultCallback unset URL that receives a fire-and-forget request for every interim transcript while the caller is still speaking. Interim results can arrive out of order — re-order on SequenceNumber when sequence matters. Delivery failures are logged, never propagated to the call.
partialResultCallbackMethod POST HTTP method for partial-result callbacks: POST or GET.

Nesting

<Gather> accepts these nested elements:

Callbacks

action request

Field Description
Digits The digits the caller pressed (DTMF input).
SpeechResult The final recognized transcript (speech input).
Confidence Recognition confidence between 0 and 1. Engines that do not report confidence return 0 — treat 0 as unknown.
Language The recognition language as a BCP-47 tag.
CallSid Unique call identifier, included with the standard call parameters (From, To, CallStatus, AccountSid).

partialResultCallback request

Field Description
CallSid Unique call identifier.
SpeechResult The interim (in-progress) transcript for the current utterance.
Confidence Recognition confidence between 0 and 1, to four decimal places.
Language The recognition language as a BCP-47 tag.
SequenceNumber Zero-indexed counter scoped to the current <Gather>, used to re-order interim results.

Every callback also carries the standard call parameters (CallSid, AccountSid, From, To, CallStatus) and is signed with your account's API key.

Notes

  • Nested <Say>, <Play>, and <Pause> verbs play as the prompt. A digit pressed during the prompt is captured and counts as the first input; the prompt itself plays to completion rather than stopping early on the key press.
  • Speech recognition uses the recognizer configured for your account: a streaming recognizer (interim results, ~100-300 ms finalization) or a file-based recognizer (~5-15 s, no interim results — partialResultCallback is silently ignored). When both are configured, streaming wins.
  • Accounts without their own recognizer fall back to the platform default recognizer, which supports English only. A speech-mode gather with no available recognizer surfaces a clear speech-not-configured error rather than silently degrading.