Module: Adhearsion::CallController::Input

Included in:
Adhearsion::CallController
Defined in:
lib/adhearsion/call_controller/input.rb,
lib/adhearsion/call_controller/input/result.rb,
lib/adhearsion/call_controller/input/menu_builder.rb,
lib/adhearsion/call_controller/input/prompt_builder.rb,
lib/adhearsion/call_controller/input/ask_grammar_builder.rb

Defined Under Namespace

Classes: AskGrammarBuilder, MenuBuilder, PromptBuilder, Result

Constant Summary collapse

InputError =
Class.new Adhearsion::Error

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

See Also:

  • Output#play
  • Rayo::Component::Input.new
  • Rayo::Component::Output.new

40
41
42
43
44
45
46
47
48
49
50
51
# File 'lib/adhearsion/call_controller/input.rb', line 40

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

  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

Raises:

  • (ArgumentError)

See Also:


107
108
109
110
111
112
113
114
115
116
117
# File 'lib/adhearsion/call_controller/input.rb', line 107

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