About

Play a prompt and get digits. The prompt file can be interrupted by dialed digits.

Usage

<min> <max> <tries> <timeout> <terminators> <file> <invalid_file> [<var_name> [<regexp> [<digit_timeout> [<transfer_on_failure>]]]]

Parameters

• min = Minimum number of digits to fetch (minimum value of 0)

• max = Maximum number of digits to fetch (maximum value of 128)

• tries = number of tries for the sound to play

• timeout = Number of milliseconds to wait for a dialed response after the file playback ends and before PAGD does a retry.

• terminators = digits used to end input if less than <max> digits have been pressed. If it starts with '=', then a terminator must be present for the input to be accepted (Since FS 1.2). (Typically '#', can be empty). Add '+' in front of terminating digit to always append it to the result variable specified in var_name.

• file = Sound file to play to prompt for digits to be dialed by the caller; playback can be interrupted by the first dialed digit (can be empty or the special string "silence" to omit the message).

• invalid_file = Sound file to play when digits don't match the regexp (can be empty to omit the message).

• var_name = Channel variable into which valid digits should be placed (optional, no variable is set by default. See also 'var_name_invalid' below).

• regexp = Regular expression to match digits (optional, an empty string allows all input (default)).

• digit_timeout = Inter-digit timeout; number of milliseconds allowed between digits in lieu of dialing a terminator digit; once this number is reached, PAGD assumes that the caller has no more digits to dial (optional, defaults to the value of <timeout>).

• transfer_on_failure = where to transfer call when max tries has been reached, example: "1 XML hangup" (optional, by default no transfer is executed, allowing the caller to process channel variables).

Exit Values

On exit, there may be some useful values in channel variables

read_terminator_used

The digit used to terminate entry (if a digit was used). Note that if termination was due to a timeout or hangup, then this channel variable is not touched (so may be left as nil or whatever it was on entry)

var_name_invalid

(Since FreeSWITCH v1.6.0)

When the dialed digits do not satisfy the regexp pattern to form a valid response, the string that was actually dialed is returned in the var_name with the string "_invalid" appended to the var_name. For example:

If ${dialed_digits} is the name of the variable that contains the valid string of digits that match the regular expression. Then

${dialed_digits_invalid} will contain the digits that were dialed when they failed to match the regexp pattern specified to this command, to allow at least some further helpful processing.

Examples

<extension name="play_and_get_digits example">
  <condition field="destination_number" expression="^(1888)$">
    <action application="play_and_get_digits" data="2 5 3 7000 # $${base_dir}/sounds/en/us/callie/conference/8000/conf-pin.wav /invalid.wav foobar \d+"/>
    <action application="log" data="CRIT ${foobar}"/>
  </condition>
</extension>

The following example demonstrates using mod_dptools: say (or mod_dptools: phrase) to get one digit after 3s, 250ms of silence on fail (no digit entered). Quote the text string!

<extension name="play_and_get_digits with say">
  <condition field="destination_number" expression="^(6500)$">
    <action application="play_and_get_digits" data="1 1 1 3000 # say:'press one for technicial support' silence_stream://250 res \d+" />
  </condition>
</extension>

Note that the parameters are slightly different in the lua version (and you can't use "say"!)

session:setVariable("read_terminator_used","-")
destnum = session:playAndGetDigits(3, 20, 3, 5000, "#*", "phrase:getnum", "phrase:error", "\\d+")
terminator = session:getVariable("read_terminator_used")

See Also

• Dialplan
• mod_dptools: read