Gather

The Gather verb collects DTMF digits or speech input from the caller and sends it to your server.

Example

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Gather",
      "input": "dtmf",
      "action_url": "https://example.com/handle-input",
      "num_digits": 1,
      "timeout": 5,
      "say": {
        "text": "Press 1 for sales, 2 for support, or 3 for billing."
      }
    }
  ]
}

Parameters

Parameter	Type	Required	Default	Description
input	string	no	dtmf	Only `dtmf` is collected today. See the note below.
action_url	string	yes	—	URL to POST gathered input to
method	string	no	POST	HTTP method for action_url
timeout	integer	no	5	Seconds to wait for input
num_digits	integer	no	—	Exact digits to collect (auto-submit)
finish_on_key	string	no	#	Key that ends gathering
say	object	no	—	Inline Say to play while gathering
play	object	no	—	Inline Play to play while gathering

Input Types

DTMF Input

Collect numeric key presses:

{
  "verb": "Gather",
  "input": "dtmf",
  "action_url": "https://example.com/handle-dtmf",
  "num_digits": 4,
  "say": {
    "text": "Please enter your 4-digit PIN."
  }
}

Speech input is not implemented. input is accepted for forward compatibility but only DTMF is collected — a Gather with input: "speech" behaves exactly like input: "dtmf" and speech_result is always empty.

Nested Say and Play

You can nest a Say or Play verb to provide a prompt:

{
  "verb": "Gather",
  "input": "dtmf",
  "action_url": "https://example.com/menu",
  "num_digits": 1,
  "say": {
    "text": "For English, press 1. For Hindi, press 2.",
    "voice": "en-IN-Wavenet-B"
  }
}

Or use Play:

{
  "verb": "Gather",
  "input": "dtmf",
  "action_url": "https://example.com/menu",
  "play": {
    "url": "https://example.com/menu-prompt.mp3"
  }
}

Callback Payload

When the Gather finishes, TryVox POSTs to your action_url:

{
  "call_uuid": "abc-123",
  "account_id": "acc_xyz",
  "digits": "1",
  "speech_result": "",
  "reason": "complete",
  "from": "+919876543210",
  "to": "+911234567890"
}

reason tells you why the Gather ended, which matters because digits alone cannot distinguish a caller who chose nothing from one who was cut off:

Reason	Meaning
`complete`	The caller entered `num_digits` or pressed `finish_on_key`.
`timeout`	`timeout` elapsed. `digits` holds whatever was entered, possibly empty.
`cancelled`	The call ended during the Gather.
`error`	Input could not be collected. Treat as no input.

A timeout is not a failure — a caller saying nothing is a normal outcome, and your application decides whether to reprompt, transfer, or hang up.

Respond with the next VoxML document. Returning nothing ends the call.

finish_on_key is stripped from digits: it signals that the caller is done, it is not part of what they entered.

Response to Callback

Your action_url should return new VoxML instructions:

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Say",
      "text": "You pressed 1. Connecting you to sales."
    },
    {
      "verb": "Dial",
      "numbers": [{"number": "+919123456789"}]
    }
  ]
}

Finishing Gathering

Gathering completes when:

num_digits digits are collected (auto-submit)
The finish_on_key is pressed (default: #)
The timeout expires with no input
Speech input is detected and processed

Best Practices

Use num_digits for fixed-length input (PINs, menu choices)
Set appropriate timeout values (3-5 seconds for speech, 5-10 for DTMF)
Provide clear prompts explaining what input is expected
Handle timeout cases in your callback logic

On this page