Gather

The <Gather> verb supports touch tones (DTMF) to get digit responses.

In DTMF mode it "gathers" digits that a caller enters into his or her telephone keypad. When the caller is done entering digits, callapi submits that digits to the provided 'action' URL in an HTTP GET or POST request.

If no input is received before timeout, <Gather> falls through to the next verb in the callapi document. You may optionally nest <Say>, <Play>, and <Pause> verbs within a <Gather> verb while waiting for input. This allows you to read menu options to the caller while letting her enter a menu selection at any time. After the first digit is received the audio will stop playing.

Gather Attributes

Name	Allowed Values	Default Value
action	relative or absolute URL	current document URL
method	GET, POST	POST
timeout	positive integer	5 seconds
finishOnKey	any digit, #, *	#
numDigits	integer >= 1	unlimited
input	dtmf	dtmf
partialResultCallback	relative or absolute url	none
language	en-US, en-GB, es-ES, it-IT, fr-FR, pl-PL, pt-PT	en-US
hints	"words, phrases that have many words"	none

Action. The 'action' attribute takes an absolute or relative URL as a value. When the caller has finished entering digits callapi will make a GET or POST request to this URL including the parameters below. If no 'action' is provided, callapi will by default make a POST request to the current document’s URL.

Request Parameters

Parameter	Description
Digits	The digits the caller pressed, excluding the finishOnKey digit.

Method. The 'method' attribute takes the value 'GET' or 'POST'. This tells callapi whether to request the 'action' URL via HTTP GET or POST.

Timeout. The 'timeout' attribute sets the limit in seconds that CallAPI will wait for the caller to press another digit before moving on and making a request to the 'action' URL. For example, if 'timeout' is '10', CallAPI will wait ten seconds for the caller to press another key before submitting the previously entered digits to the 'action' URL. CallAPI waits until completing the execution of all nested verbs before beginning the timeout period.

finishOnKey. The 'finishOnKey' attribute lets you choose one value that submits the received data when entered. For example, if you set 'finishOnKey' to '#' and the user enters '1234#', CallAPI will immediately stop waiting for more input when the '#' is received and will submit "Digits=1234" to the 'action' URL. Note that the 'finishOnKey' value is not sent. The allowed values are the digits 0-9, '#', '*' and the empty string (set 'finishOnKey' to ''). If the empty string is used, <Gather> captures all input and no key will end the <Gather> when pressed. In this case CallAPI will submit the entered digits to the 'action' URL only after the timeout has been reached. The value can only be a single character.

numDigits. The 'numDigits' attribute lets you set the number of digits you are expecting, and submits the data to the 'action' URL once the caller enters that number of digits.

input A list of inputs that CallAPI should accept for <Gather>.

partialResultCallback A relative or fully qualified URL.

The Webhooks to partialResultCallback are async and doesn’t accept RCML back. If you want to act based on the partial result, then use the REST API to Live Modify the call.

Request Parameters

language The language CallAPI should recognize. Defaults to en-US

hints A list of words or phrases that CallAPI should expect during recognition. These are very useful for improving recognition of single words or phrases. Entries into hints should be separated by a comma.

Nesting

You can nest the following verbs within : <Gather>:<Say>:<Play>:,<Pause>

Example

Example of how to use the verb:

<Response>
   <Gather action="http://example.com/rest/menu" numDigits="1">
      <Say>Welcome to TPS.</Say>
      <Say>For store hours, press 1.</Say>
      <Say>To speak to an agent, press 2.</Say>
      <Say>To check your account status, press 3.</Say>
    </Gather>
<!-- If customer doesn't input anything, prompt and try again. -->
    <Say>Sorry, I didn't get your response.</Say>
<Redirect>http://example.com/rest/menu/redirect</Redirect>
</Response>