Skip to main content

Gather

Definition​

The Gather verb collects digits entered by a caller on their phone keypad and sends them to the specified action URL. For example, you can use Gather to prompt a caller to enter an extension or PIN.

The Say, Play and Pause verbs can be nested in the Gather verb.

Example​

In these example FlexML instructions, once the party is reached, the called party will be prompted by verbal command to enter some digits. If an action URL is set, the URL will be queried once DMTF input has been gathered according to the specifications. In this case, if the action URL was set, it would be requested once the party has entered two digits because numDigits is set to 2.

<Response>
  <Gather numDigits="2">
    <Say>Please enter the extension of the party you'd like to be connected to. </Say>
  </Gather>
</Response>

Say will read out the text within its tags.

<Response>
  <Gather timeout="10" numDigits="2" method="get" action="http://www.example.com/path/to/handler">
    <Say>Please enter two digits</Say>
  </Gather>
</Response>

Play will play the file within its tags.

<Response>
  <Gather timeout="10" numDigits="2" method="get" action="http://www.example.com/path/to/handler">
    <Play>https://www.example.com/media/my_file.wav</Play>
  </Gather>
</Response>

Example with Play + Pause + Say inside Gather​

In this example, the caller will hear a prompt, then there will be a short pause, and then an additional message will play.

<Response>
  <Gather numDigits="4" action="https://example.com/handler">
    <Play>https://example.com/media/first_prompt.wav</Play>
    <Pause length="2"/>
    <Say>Please enter your 4-digit PIN now.</Say>
  </Gather>
</Response>

Supported Attributes​

These attributes can be used to modify the Gather verb. They are inserted as name-value pairs in the start-tag.

AttributeData TypeDescription
actionstringThe URL that is invoked when the Gather verb completes. The callback is triggered based on the completion conditions and the actionOnEmptyResult setting (see [Gather Completion Logic below]).
actionOnEmptyResultbooleanDetermines whether the action callback is triggered when Gather completes due to a timeout with no user input. When set to false (default), no action callback is sent if no digits or finish key were entered. When set to true, the action callback is sent on timeout even if no input was provided. This allows you to handle no-input scenarios in your application logic, such as by prompting the user again or ending the call.
finishOnKeystringOne or more keys that will act as the submit key. If no finishOnKey value is specified, the input will be submitted after the timeout is expired. Values accepted in this field are: 0-9, #, *. To disable this feature, add the _ value. If you define multiple keys (e.g., #*), any of these keys can be used as the submit key. The default value is #.
methodstringThe type of request made to the action URL. Values accepted in this field are POST or GET. The default value is POST.
numDigitsintegerThe number of digits expected before Gather completes. Must be greater than or equal to 1. If not specified, any number of digits will be accepted until another completion condition is met (such as finishOnKey or timeout). Other actions will be listened to, such as timeout and finishOnKey, to end the input. Note, that if the startDigits value is specified, then the digit entered as the start digit is counted as the first char in the number of digits specified by the numDigits attribute, e.g. if you specify 5 in the numDigits field, the system will be expecting 4 valid digits to be entered once the start digit has been pressed.
timeoutintegerThe number of seconds to wait for the calling party's next input before moving to the action URL request. Note that this is the time allotted between individual DTMF input, not the total time allotted to enter all values. If there is a nested verb such as Play within the Gather verb, the timeout will begin after the end of that verb. For example, if you have a Play URL, the playback will play through and then the timeout value will begin. The default value is 5.
startDigitsstringOne or more keys that must be entered before the system begins listening for further digits. Values accepted in this field are: 0-9, #, *. If you define multiple keys (e.g., *#), any of these keys can be used as the start key.
validDigitsstringThe list of digits (tone keys, which the user can press) that will be recognized by the Gather verb. Any key outside this list will be ignored. Note, if the startDigits value is specified, the system will not start listening for the digits specified in this validDigits attribute until a start digit is entered. The default value is 1234567890#*abcdABCD. If the caller enters only digits outside this list, they are ignored. If no valid digits are collected before completion, the behavior is treated as a no-input scenario.

Gather Completion Logic​

info

A "no-input" scenario refers to cases where the caller does not enter any valid digits before Gather completes. Pressing only the finishOnKey without entering digits is also treated as a no-input scenario.

The Gather verb completes under one of the following conditions, evaluated in this order:

1. Completion by numDigits​

If the required number of digits is collected, Gather completes immediately. The callback includes the Digits field containing the collected input.

2. Completion by finishOnKey​

If a key defined in finishOnKey is pressed, Gather completes immediately.

  • If at least one digit was entered before the key press, the action callback is sent. The callback includes the FinishKey field and the collected Digits.
  • If the finish key is pressed without entering any digits, the behavior follows the same rules as timeout with no input:
    • If actionOnEmptyResult is false (default), no action callback is sent.
    • If actionOnEmptyResult is true, the action callback is sent with:
      • FinishKey set
      • Digits empty

3. Completion by timeout​

If no valid input is received within the timeout window, Gather completes due to timeout.

  • If at least one digit or finish key was entered, the action callback is sent.
  • If no input was provided, the action callback is not sent unless actionOnEmptyResult is set to true.

Example with startDigits​

In this example, the startDigits attribute is used. In this case any other keys outside the list of key(s) specified in that attribute are ignored completely until any of the start digits is entered. As soon as the start digit is detected, the intro.mp3 prompt is terminated, and the system continues accepting numeric digits until one of the following occurs:

  • User enters 4 more digits, bringing the total digits count to 5, the start digit + 4 more digits.
  • User presses #.
  • 10 seconds pass without additional input.

In all cases, the /pin action is taken subject to the timeout rules described above.

<Response>
  <Gather startDigits="*" validDigits="0123456789" numDigits="5" finishOnKey="#" timeout="10" action="/pin">
    <Play>intro.mp3</Play>
  </Gather>
  <Redirect>/start</Redirect>
</Response>

Callback Data​

In addition to the standard callback fields the following fields are returned in the callback request body when the Gather verb completes:

AttributeData TypeDescription
DigitsstringDTMF digits collected during the Gather session. Empty if no digits were collected before timeout or finishOnKey.
FinishKeystringThe key that caused the Gather verb to finish. This field is only included if:
  • the finishOnKey attribute is set, and
  • the Gather completed due to a finish key, and
  • an action callback was triggered.
Values returned in this field are: 0-9, #, *.

Successful requests return a JSON response similar to the following. In this example, Gather completed because the finishOnKey (#) was pressed before the required number of digits was entered:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Digits": "",
    "Direction":"inbound",
    "FinishKey": "#",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

Nesting Rules​

  • You can nest the Play, Say, Pause/Wait verbs within the Gather verb.
  • You cannot nest the Gather verb within other FlexML verbs.