Module: AdhearsionASR::ControllerMethods

Defined in:
lib/adhearsion-asr/controller_methods.rb

Instance Method Summary collapse

Instance Method Details

#ask(*args) ⇒ Result

Prompts for input, handling playback of prompts, DTMF grammar construction, and execution

The first arguments will be a list of sounds to play, as accepted by #play, including strings for TTS, Date and Time objects, and file paths. :timeout, :terminator and :limit options may be specified to automatically construct a grammar, or grammars may be manually specified.

Examples:

A basic DTMF digit collection:

ask "Welcome, ", "/opt/sounds/menu-prompt.mp3",
    timeout: 10, terminator: '#', limit: 3

Parameters:

  • args (Object, Array<Object>)

    A list of outputs to play, as accepted by #play

  • options (Hash)

    Options to modify the grammar

Returns:

  • (Result)

    a result object from which the details of the utterance may be established

See Also:



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
# File 'lib/adhearsion-asr/controller_methods.rb', line 35

def ask(*args)
  options = args.last.kind_of?(Hash) ? args.pop : {}
  prompts = args.flatten.compact

  if block_given?
    logger.warn "You passed a block to #ask, but this functionality is not available in adhearsion-asr. If you're looking for the block validator functionality, you should avoid using it in favour of grammars, and it is deprecated in Adhearsion Core."
  end

  options[:grammar] || options[:grammar_url] || options[:limit] || options[:terminator] || raise(ArgumentError, "You must specify at least one of limit, terminator or grammar")

  grammars = AskGrammarBuilder.new(options).grammars

  output_document = prompts.empty? ? nil : output_formatter.ssml_for_collection(prompts)

  PromptBuilder.new(output_document, grammars, options).execute self
end

Creates and manages a multiple choice menu driven by DTMF, handling playback of prompts, invalid input, retries and timeouts, and final failures.

The first arguments will be a list of sounds to play, as accepted by #play, including strings for TTS, Date and Time objects, and file paths. :tries and :timeout options respectively specify the number of tries before going into failure, and the timeout in seconds allowed on each digit input. The most important part is the following block, which specifies how the menu will be constructed and handled.

#match handles connecting an input pattern to a payload. The pattern can be one or more of: an integer, a Range, a string, an Array of the possible single types. Input is matched against patterns, and the first exact match has it’s payload executed. Matched input is passed in to the associated block, or to the controller through #options.

Allowed payloads are the name of a controller class, in which case it is executed through its #run method, or a block, which is executed in the context of the current controller.

#invalid has its associated block executed when the input does not possibly match any pattern. #timeout’s block is run when timeout expires before receiving any input #failure runs its block when the maximum number of tries is reached without an input match.

Execution of the current context resumes after #menu finishes. If you wish to jump to an entirely different controller, use #pass. Menu will return :failed if failure was reached, or :done if a match was executed.

Examples:

A complete example of the method is as follows:

menu "Welcome, ", "/opt/sounds/menu-prompt.mp3", tries: 2, timeout: 10 do
  match 1, OperatorController

  match 10..19 do
    pass DirectController
  end

  match 5, 6, 9 do |exten|
    play "The #{exten} extension is currently not active"
  end

  match '7', OfficeController

  invalid { play "Please choose a valid extension" }
  timeout { play "Input timed out, try again." }
  failure { pass OperatorController }
end

Parameters:

  • args (Object)

    A list of outputs to play, as accepted by #play

  • options (Hash)

    Options to use for the menu

Returns:

  • (Result)

    a result object from which the details of the utterance may be established

Raises:

  • (ArgumentError)

See Also:

  • Output#play
  • CallController#pass


106
107
108
109
110
111
112
113
114
115
116
# File 'lib/adhearsion-asr/controller_methods.rb', line 106

def menu(*args, &block)
  raise ArgumentError, "You must specify a block to build the menu" unless block
  options = args.last.kind_of?(Hash) ? args.pop : {}
  prompts = args.flatten.compact

  menu_builder = MenuBuilder.new(options, &block)

  output_document = prompts.empty? ? nil : output_formatter.ssml_for_collection(prompts)

  menu_builder.execute output_document, self
end