Reference Turnkey Applications Tutorials Visual Designer
    • REST API
      • Overview
      • API Endpoint
      • Authentication
      • Requests
      • Responses
      • Paging
      • Reason Codes Dictionary
    • Management APIs
      • Accounts
      • Identity Access Management Early Access
        • Identity Access Management Overview
        • Identity Access Management API
          • User Management
            • Create a User
            • Update a User
            • Retrieve a User
            • Delete a User
          • API Keys Management
            • Create an API Key
            • Update an API Key
            • Retrieve an API Key
            • Delete an API Key
      • Applications
      • Clients
        • Create a Client
        • Delete a Client
        • Change Client’s Password
        • Get a List of Available Clients
      • Incoming Phone Numbers
        • IncomingPhoneNumber Instance Resource
        • IncomingPhoneNumbers List Resource
        • Local IncomingPhoneNumber Factory Resource
        • Toll-Free IncomingPhoneNumber Factory Resource
        • Mobile IncomingPhoneNumber Factory Resource
        • Attach a phone number to an application
        • Delete a phone number
        • List of Phone Numbers
        • Incoming Phone Number Regex Support
      • Notifications
      • Usage Records
    • Voice
      • Calls
        • Call List Resource URI
        • Making a Call
        • Modifying Live Calls
        • Examples
        • List Filter
        • Paging Information
      • Conference Management
        • Supported Operations
        • Conference List Resource URI
      • Conference Participants Management
        • Participants List Resource URI
      • Gather DTMF
      • Gather Speech
      • Say
      • Play
      • Hold
      • Recordings
      • Refers
        • Resource Properties
        • Supported Operations
        • Paging Information
      • Resume
      • SIP Refer Support
    • SMS
      • Messages
        • Send SMS
        • Get SMS List
        • Get single SMS Information
        • SMS Attributes
      • Email
    • RCML
      • Overview
        • Interacting with Your Application
        • RCML Verbs
      • Dial
        • Client
        • Conference
        • Number
        • SIP
      • Email
      • Gather
      • Say
      • Play
      • SMS
      • Hold
      • Resume
      • Hangup
      • Pause
      • Redirect
      • Record
      • Reject
      • Refer
    • Visual Designer API
      • List Application Templates
      • :List a Specific Application Template
      • Create a Visual Designer Application
      • Get Application Details
      • Save Application Changes
      • Create Application Parameters
      • List Application Parameters
      • Delete Application Parameters
      • Upload Application Media Files
      • List Application Media Files
      • Play Application Media Files
      • Delete Application Media Files
      • Get Application Logs
      • Delete Application Logs
      • Get Application Settings
      • Modify Application Settings
      • Rename an Application
      • Delete an Application
      • Get Visual Designer Configuration
    • Turnkey Apps APIs
      • Smart 2FA
        • Sending One-Time Passwords
        • Verifying One-Time Passwords
        • Cancel One-Time Passwords
        • Session Detail Record (SDR)
        • Get list of One-Time Passwords
        • Get a Single One-Time Password
        • Usage Record One-Time Passwords
        • Common Response Error Code
        • Limit
          • Create Limit
          • Update Limit
          • Delete Limit
          • Get List of Limits
      • Call Queuing
      • Auto Attendant
        • Users
        • Announcement
        • Auto Attendant System
        • Menu
        • Schedule
        • Phone Number
        • Usage Records
        • Third Party Integration
      • Number Masking
        • Application
        • Mask Number Pool
        • Context
        • Participants
        • Interactions
        • Usage Records
      • Task Router
docs 1.0
  • docs
    • 1.0
  • docs
  • Enterprise:RCML
  • Enterprise:Gather

Gather

Gather

The <Gather> verb supports two modes: DTMF and SPEECH. In DTMF mode it "gathers" digits that a caller enters into his or her telephone keypad. When the caller is done entering digits, CPaaS submits that digits to the provided 'action' URL in an HTTP GET or POST request. In SPEECH mode it "gathers" recognized speech that a caller said. If no input is received before timeout, <Gather> falls through to the next verb in the CPaaS 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

actionOnEmptyResult

true, false

false

method

GET, POST

POST

timeout

positive integer

5 seconds

preTimeout

positive integer

5 seconds

postTimeout

positive integer

5 seconds

finishOnKey

any digit, #, *

#

numDigits

integer >= 1

unlimited

input

dtmf, speech

dtmf

partialResultCallback

relative or absolute url

none

partialResultCallbackMethod

GET, POST

POST

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

  • timeout. The 'timeout' attribute is discontinued in favor of the new 'preTimeout', and 'postTiemout' attributes, whose values will take precedence is provided.

  • action. The 'action' attribute takes an absolute or relative URL as a value. When the caller has finished entering digits Restcomm will make a GET or POST request to this URL including the parameters below. If you provide an 'action' URL, Restcomm will continue the current call after the Gather is completed, using the RCML received in your response to the 'action' URL request. Any RCML verbs occuring after a <Gather> which specifies an 'action' attribute are unreachable. If no 'action' is provided, Restcomm 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.

SpeechResult

The transcribed result of the speech.

Duration

In case of Speech mode, this is the duration the ASR engine took to recognize.

  • actionOnEmptyResult If set to true, it will forcefully trigger a webhook to the action URL even when there is no collected input. Otherwise, the following verb will be processed.

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

  • timeout (deprecated) The timeout attribute sets a limit in seconds that Restcomm will wait for the caller to press another digit before moving on and making a request to the action URL. For example, if the timeout is '10', Restcomm will wait ten seconds for the caller to press another key before submitting the previously entered digits to the action URL. Restcomm will wait until all nested verbs are executed before beginning the timeout period.

  • preTimeout The preTimeout attribute sets a limit in seconds that Restcomm will wait for the caller to first press a digit (DTMF) or detect speech (ASR) before moving on and making a request to the 'action' URL, if the actionOnEmptyResult is set to true.

  • postTimeout The postTimeout attribute sets a limit in seconds that Restcomm will wait for the caller to press each subsequent digit (DTMF), or amount of silence necessary after the end of speech (ASR) before moving on and making a request to the action URL.

  • 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#', CPaaS 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, ‘#’, ‘*’ . If the attribute hasn’t been set or has an empty string, the # symbol will be used as a fallback instead.

  • 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 CPaaS should accept for <Gather>. Can be "dtmf" or "speech". Defaults to "dtmf".

  • partialResultCallback A relative or fully qualified URL. Is a mandatory attribute for “speech” mode. CPaaS will make requests to your partialResultCallback in real-time as speech is recognized. These webhooks will contain UnstableSpeechResult parameter with partial transcriptions that may change as the recognition progresses.

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

Parameter Description

UnstableSpeechResult

Partially recognized speech the caller said.

  • language The language CPaaS should recognize. Defaults to en-US

  • hints A list of words or phrases that CPaaS 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>

Examples

For an example of how to use the <Gather> verb see below.

<Response>
                <Gather action="handle-user-input.php" 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 package 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>handle-incoming-call.xml</Redirect>
            </Response>
Platform

Programmable Voice

Programmable SMS

Turnkey Applications

Smart 2FA

Call Queue

Auto Attendant

Number Masking

Task Router

Campaign Manager

Learn

Terms And Conditions

About

ABOUT

CONTACT US

© 2020, All rights reserved.