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	"dtmf", "speech", or "dtmf speech"
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

Collect voice input:

{
  "verb": "Gather",
  "input": "speech",
  "action_url": "https://example.com/handle-speech",
  "timeout": 3,
  "say": {
    "text": "Please say your account number."
  }
}

Combined Input

Accept both DTMF and speech:

{
  "verb": "Gather",
  "input": "dtmf speech",
  "action_url": "https://example.com/handle-input",
  "say": {
    "text": "Say or enter your choice."
  }
}

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 input is collected, TryVox POSTs to your action_url with:

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

For speech input, additional fields are included:

{
  "call_uuid": "abc-123",
  "account_id": "acc_xyz",
  "speech_result": "Sales department",
  "confidence": 0.95,
  "from": "+919876543210",
  "to": "+911234567890"
}

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

Gather

On this page