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 the timeout value Seconds of trailing silence before speech is considered final; when unset it inherits timeout. The literal value auto lets the recognizer decide when the caller has finished speaking.
maxSpeechTime 30 Hard cap on speech duration in seconds; values above 60 are clamped to 60.
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.
bargeIn unset Accepted for compatibility and ignored — no effect. Prompts are always interruptible by a key press.
debug unset Accepted for compatibility and ignored — no effect.

Nesting

<Gather> accepts these nested elements:

Callbacks

action request

Field Description
Digits The digits the caller pressed (DTMF input). Omitted when a speech result was captured and no digits were pressed.
FinishedOnKey The key that ended a DTMF gather (present on DTMF input).
msg Literal marker "Gather End" sent on DTMF gathers.
SpeechResult The final recognized transcript (speech input).
Confidence Recognition confidence between 0 and 1, to four decimal places (speech input).
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.
StableSpeechResult The portion of the interim transcript that is unlikely to change.
UnstableSpeechResult The still-changing tail of the interim transcript; sent empty on the final partial.
Stability The recognizer's stability score for the interim result; sent empty on the final partial.
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 stops it at once — including any later loop iteration or nested verb not yet started — and counts as the first input.
  • 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.