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 sample 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: 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.

Attribute	Data Type	Description
action	string	The link to another set of FlexML instructions that will be called after the input has been submitted, or when the timeout value has expired. The URL can be absolute or relative.
finishOnKey	string	This determines a single key or multiple 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, 1, 2, 3, 4, 5, 6, 7, 8, 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 #.
method	string	The type of request made to the action URL. Values accepted in this field are POST or GET. The default value is POST.
numDigits	integer	The expected number of digits to be entered in order to submit data to the action URL. Integers entered into this field must be greater than or equal to 1. If the field value is not specified, any number of digits will be listened for. 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.
timeout	integer	The 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.
startDigits	string	The expected start digit(s) to be entered in order to set the system in waiting mode when it is expecting further digits to be entered. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *. If you define multiple keys (e.g., *#), any of these keys can be used as the start key.
validDigits	string	The list of the 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.

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 entered, 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 enters # without entering the 4 digits.
• 10 seconds pass without input.

The /pin action is taken in any of these cases.

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

Request Data

Successful requests return a JSON response that looks like the following:

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

The following is an additional parameter and value that will be included in action requests.

Attribute	Data Type	Description
Digits	string	The digits entered via DTMF.

info

For a list of the other parameters and values to expect in action requests, refer to the FlexML Call Flow section.

Nesting Rules

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