Module: Twilio::Rails::Phone::TreeMacros

Extended by:
TreeMacros
Included in:
TreeMacros
Defined in:
lib/twilio/rails/phone/tree_macros.rb

Overview

This module is available as ‘macros` in context of generating phone trees. It provides a set of shortcuts for common or verboase actions. It can be extended with custom macros using the config option Configuration#include_phone_macros

Instance Method Summary collapse

Instance Method Details

#answer_no?(string) ⇒ true, false

Matches if the entire passed in string is included in the Configuration#no_responses and is considered a “no”.

Parameters:

  • filename (String) —

    the string to match against.

Returns:

  • (true, false) —

    if the passed in string matches.



114
115
116
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 114

def answer_no?(string)
  answers_no.include?((string || "").downcase.strip.gsub(/[.,!?]/, ""))
end

#answer_yes?(string) ⇒ true, false

Matches if the entire passed in string is included in the Configuration#yes_responses and is considered a “yes”.

Parameters:

  • filename (String) —

    the string to match against.

Returns:

  • (true, false) —

    if the passed in string matches.



98
99
100
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 98

def answer_yes?(string)
  answers_yes.include?((string || "").downcase.strip.gsub(/[.,!?]/, ""))
end

#answers_no ⇒ Array<String>

The list of configured answers that are considered “no” from Configuration#no_responses.

Returns:

  • (Array<String>) —

    the list of configured answers that are considered “no”.



105
106
107
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 105

def answers_no
  Twilio::Rails.config.no_responses
end

#answers_yes ⇒ Array<String>

The list of configured answers that are considered “yes” from Configuration#yes_responses.

Returns:

  • (Array<String>) —

    the list of configured answers that are considered “yes”.



89
90
91
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 89

def answers_yes
  Twilio::Rails.config.yes_responses
end

#digit_gather_interruptable(timeout: 6) ⇒ Hash

Gather one digit, allowing the current speech to be interrupted and stopped when a digit is pressed, with a configurable timeout that defaults to 6 seconds.

Parameters:

  • timeout (Integer) (defaults to: 6) —

    the number of seconds to wait for a digit before timing out, defaults to 6 seconds.

Returns:

  • (Hash) —

    formatted to pass to ‘gather:`.



15
16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 15

def digit_gather_interruptable(timeout: 6)
  timeout = timeout.to_i.presence || 6
  timeout = 6 if timeout < 1

  {
    type: :digits,
    timeout: timeout.to_i.presence || 6,
    number: 1,
    interrupt: true,
    finish_on_key: "",
  }
end

#digits(num) ⇒ String

Split a number into its digits and join them with commas, in order for it to be read out as a list of digits.

Examples:

digits(123)
"1, 2, 3"

Parameters:

  • num (Integer, String) —

    the integer number to split into digits.

Returns:

  • (String) —

    the digits joined with commas.



35
36
37
38
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 35

def digits(num)
  return "" if num.blank?
  num.to_s.split("").join(", ")
end

#numbered_choice_response_includes?(choices, response:) ⇒ true, false

Validates if the response object includes a digit that is within the range of the choices array. This pairs directly with #numbered_choices for creating menus and validating the input. The array of choices must be larger than 1 and less than 10, otherwise a Error will be raised.

false also if there are no digits or the digit is out of range.

Parameters:

  • choices (Array<String>) —

    the list of choices in numbered order.

  • response (Twilio::Rails::Phone::Models::Response) —

    the response object to validate.

Returns:

  • (true, false) —

    whether the response includes a digit that is within the range of the choices. Returns

Raises:



80
81
82
83
84
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 80

def numbered_choice_response_includes?(choices, response:)
  raise Twilio::Rails::Phone::Error, "`numbered_choice_response_includes?` macro got an empty array" if choices.empty?
  raise Twilio::Rails::Phone::Error, "`numbered_choice_response_includes?` macro cannot be more than 9" if choices.length > 9
  !!(response.integer_digits && response.integer_digits > 0 && response.integer_digits <= choices.length)
end

#numbered_choices(choices, prefix: nil) ⇒ Array<String>

Format a list of choices such that they are a numbered list for a phone tree menu, and can be passed directly into a ‘say:`. This pairs perfectly with #numbered_choice_response_includes? for creating menus. The array of choices must be larger than 1 and less than 10, otherwise a Error will be raised.

Examples:

numbered_choices(["store hours", "accounting", "warehouse"])
[
   "For store hours, press 1.",
   "For accounting, press 2.",
   "For store warehouse, press 3.",
]

Parameters:

  • choices (Array<String>) —

    the list of choices in numbered order.

  • prefix (String) (defaults to: nil) —

    the prefix to use before each choice, defaults to “For”.

Returns:

  • (Array<String>) —

    the list of choices with numbers and prefixes formatted for ‘say:`.

Raises:



65
66
67
68
69
70
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 65

def numbered_choices(choices, prefix: nil)
  raise Twilio::Rails::Phone::Error, "`numbered_choices` macro got an empty array" if choices.empty?
  raise Twilio::Rails::Phone::Error, "`numbered_choices` macro cannot be more than 9" if choices.length > 9
  prefix ||= "For"
  choices.each_with_index.map { |choice, index| "#{ prefix } #{ choice }, press #{ index + 1 }." }.join(" ")
end

#pause(seconds = nil) ⇒ Hash

Pause for a number of seconds, defaults to 1 second. Useful when putting space between segments of speech.

Parameters:

  • seconds (Integer) (defaults to: nil) —

    the number of seconds to pause for, defaults to 1 second.

Returns:

  • (Hash) —

    formatted to pass to ‘message:`.



44
45
46
47
48
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 44

def pause(seconds=nil)
  {
    pause: (seconds.presence || 1),
  }
end

#play_public_file(filename) ⇒ Hash

Wraps the result of #public_file in a hash that can be used directly as a ‘message:`.

Parameters:

  • filename (String) —

    the filename of the file to play located in the ‘public` folder.

Returns:

  • (Hash) —

    formatted to pass to ‘message:`.



141
142
143
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 141

def play_public_file(filename)
  { play: public_file(filename) }
end

#public_file(filename) ⇒ String

Finds and validates the existence of a file in the ‘public` folder. Formats that link to include the configured hose from Configuration#host, and returns a fully qualified URL to the file. This is useful for playing audio files in a `message:` block. If the file is not found Error is raised.

Parameters:

  • filename (String) —

    the filename of the file to play located in the ‘public` folder.

Returns:

  • (String) —

    the fully qualified URL to the file.



126
127
128
129
130
131
132
133
134
135
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 126

def public_file(filename)
  filename = filename.gsub(/^\//, "")
  local_path = ::Rails.public_path.join(filename)

  if File.exist?(local_path)
    "#{ ::Twilio::Rails.config.host }/#{ filename }"
  else
    raise Twilio::Rails::Phone::Error, "Cannot find public file '#{ filename }' at #{ local_path }"
  end
end

#say(&block) ⇒ Twilio::Rails::Phone::Tree::Message

Expose a TwiML::Say node to be used in a ‘message:` block. This can be used to form Speech Synthesis Markup Language (SSML) to be used with Amazon Polly. Note that SSML is only available with some Polly voices, and only some tags are supported. Twilio will return server errors if used incorrectly. See the Twilio documentation for more information: www.twilio.com/docs/voice/twiml/say/text-speech#ssml-with-amazon-polly

Examples:

prompt :with_ssml,
  message: macros.say { |say|
    say.emphasis(words: "with emphasis.", level: 'moderate')
    say.w(words: "A message.")
    say.prosody(words: 'Thank you for calling.', pitch: '-10%', rate: '110%')
  }

Returns:



160
161
162
 
# File 'lib/twilio/rails/phone/tree_macros.rb', line 160

def say(&block)
  Twilio::Rails::Phone::Tree::Message.new(&block)
end