Class: Twilio::Rails::Phone::BaseTree

Inherits:
Object
  • Object
show all
Defined in:
lib/twilio/rails/phone/base_tree.rb

Overview

Base class for all phone trees which provides the DSL to define a tree. To define a phone tree start by generating a sublcass.

rails generate twilio:rails:phone_tree LeaveFeedback

This will create a new class in ‘app/phone_trees/leave_feedback_tree.rb` which will subclass this class. It must be registered with the framework in the initializer for it to be available. The generator does this.

# config/initializers/twilio_rails.rb
config.phone_trees.register { LeaveFeedbackTree }

Then define the tree using the DSL methods provided by this class. For example:

class LeaveFeedbackTree < Twilio::Rails::Phone::BaseTree
  voice "Polly.Matthew-Neural"
  final_timeout_message "Sorry, you don't appear to be there. Goodbye."
  unanswered_call ->(phone_call) { MyMailer.send_followup(phone_call).deliver_later }
  finished_call ->(phone_call) { MyMailer.send_followup(phone_call).deliver_later }
  invalid_phone_number "Sorry, we can only accept calls from North America. Goodbye."

  greeting message: "Hello, and thank you for calling.",
    prompt: :leave_feedback

  prompt :leave_feedback,
    message: "Please leave your feedback after the tone, and press pound when you are finished.",
    gather: {
      type: :voice,
      timeout: 30,
      transcribe: true,
    },
    after: ->(response) {
      if MyServiceObject.new(response.phone_caller).has_followup_message?
        { prompt: :followup_message }
      else
        {
          message: "Thank you for your feedback. Have a nice day.",
          hangup: true,
        }
      end
    }

  prompt :followup_message,
    message: ->(response) {
      [
        { play: "http://example.com/followup_message_sound.mp3" },
        { say: MyServiceObject.new(response.phone_caller).followup_message_text },
      ]
    },
    after: {
      message: "Thank you. Have a nice day.",
      hangup: true,
    }
end

Class Method Summary collapse

Class Method Details

.final_timeout_message(message) ⇒ Object

The ‘message:` object that is played to the caller if the phone tree is expecting input but none is received. The default number of attempts before this is called is 3, configured in `final_timeout_attempts`. The default value is a simple “Goodbye.”



75
76
77
78
 
# File 'lib/twilio/rails/phone/base_tree.rb', line 75

def final_timeout_message(message)
  tree.config[:final_timeout_message] = message
  nil
end

.finished_call(proc) ⇒ nil

Accepts a proc which will be called when a call is completed, unanswered, or any state not in progress. The proc will be called asynchronously in a job. The proc will be passed the Models::PhoneCall instance for the call. It is called after the call has been completed so cannot control the flow of the call. It is intended to be used as a hook to handle application logic for when a call finishes and is no longer in progress. The default is ‘nil` and no action is taken.

Parameters:

  • proc (Proc) —

    the proc to call when a call is finished, must accept a phone call instance.

Returns:

  • (nil) 


182
183
184
185
 
# File 'lib/twilio/rails/phone/base_tree.rb', line 182

def finished_call(proc)
  tree.finished_call = proc
  nil
end

.greeting(message: nil, prompt:) ⇒ nil

The entrypoint and first call for any incoming or outgoing phone call. It should only be called once as there is only one greeting. Subsequent calls will overwrite the earlier ones. It accepts an optional ‘message:` object which will be played to the caller. See the documentation for prompt for what a message can contain. It then accepts a required `prompt:` which is the next prompt in the flow of the call.

Parameters:

  • message (String, Hash, Array, Proc) (defaults to: nil) —

    The message to play to the caller.

  • prompt (Symbol, Hash, Proc) —

    The name of the next prompt.

Returns:

  • (nil) 


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

def greeting(message: nil, prompt:)
  tree.greeting = Twilio::Rails::Phone::Tree::After.new(message: message, prompt: prompt)
  nil
end

.invalid_phone_number(message) ⇒ Object

The ‘message:` object that played to the caller if a call from an invalid phone number is received. The important case here is a number from outside of North America. This is currently a limitation of the framework. The default is `nil` and no action is taken. See the documentation for prompt for what a message object can contain.

Parameters:

  • message (String, Hash, Array, Proc) —

    The message to play to the caller.



193
194
195
196
 
# File 'lib/twilio/rails/phone/base_tree.rb', line 193

def invalid_phone_number(message)
  tree.config[:invalid_phone_number] = message
  nil
end

.macros ⇒ Twilio::Rails::Phone::TreeMacros

A module of convenience macros used in prompts to prevent repetition or wordy tasks. See TreeMacros for the available methods. The macros do not have access to any instance information and must be passed any context they require.

Additional macros can be added through the application config. See Configuration#include_phone_macros.

Returns:



221
222
223
 
# File 'lib/twilio/rails/phone/base_tree.rb', line 221

def macros
  Twilio::Rails::Phone::TreeMacros
end

.prompt(prompt_name, message: nil, gather: nil, after:) ⇒ Object

Defines a prompt in the phone tree. It accepts a required ‘name:` which must be unique within the tree.

It accepts an optional ‘message:` object which will be played to the caller. A message must be one of:

  • ‘nil`: No message will be played.

  • ‘String`: A string that will be read to the caller using text-to-speech. This is the equivalent of `{ say: “a string” }`.

  • ‘Hash`: A hash that contain only the following keys:

    • ‘{ say: “hello” }`: A string that will be read to the caller using text-to-speech. Optionally also accepts a `voice:` key which will override the default voice for this message.

    • ‘{ play: “example.com/sound.mp3” }`: A URL to a “wav” or “mp3” file that will be played to the caller via Twilio.

    • ‘{ pause: 1 }`: Pause in silence for the given number of seconds.

  • ‘Array`: An array that contains any number of the above.

  • ‘Proc`: A proc that will be called when the prompt is reached. The prompt will receive the previous Models::Response instance as an argument. The proc must return one of the above.

It accepts an optional ‘gather:` object which, if present, will be used to gather input from the caller. After the optional message completes, the gather will collect the input. The gather object must be a hash with one of the following types:

  • ‘{ type: :digits }`: Collects one or more integer digits from the caller’s keypad. Those digits will be stored in the ‘digits` field of the Models::Response instance. Digits accepts the following configuration keys:

    • ‘:timeout`: The number of seconds to wait for input before timing out and falling through to the `after:`. The default is 5.

    • ‘:number`: The number of digits to collect. The default is 1.

    • ‘:interrupt`: Weather pressing a key will interrupt the message, or if the gather will not start until the message is complete. The default is `false`.

  • ‘{ type: :voice }`: Records and collects the phone caller’s voice as audio. The framework handles updating the ‘url` and fetching the audio file as a Models::Recording attached to the response instance. However, this all happens asynchronously with no guarantee of time or success. Voice accepts the following configuration keys:

    • ‘:length`: The number of seconds to record. The default is 10.

    • ‘:transcribe`: A boolean if Twilio should attempt to transcribe the audio and send it back as text. The framework handles this all asynchronously and will update the `transcription` field. Default is `false`.

    • ‘:profanity_filter`: Replaces any profanity in the transcription with ***. Default is `false`.

  • ‘{ type: :speech }`: Collects speech from the caller as text using a specialzed model designed to better identify utterances of digits, commands, conversations, etc.. This does not collect audio files, and is more expensive, but returns the `response.transcription` in realtime which can be immediately used in the call flow. Speech accepts the following configuration keys:

    • ‘:language`: The language of the caller. The default is “en-US”.

    • ‘:speech_model`: The model to use for the speech recognition. Accepts “default”, “numbers_and_commands”, “phone_call”, “experimental_conversations”, and “experimental_utterances”. The default is “default”. See the Twilio documentation for details. www.twilio.com/docs/voice/twiml/gather#speechmodel

    • ‘:enhanced`: A boolean if the enhanced model should be used. Results are better but the cost is higher.

      The default is `false`.

    • ‘:timeout`: The number of seconds to wait for input before timing out and falling through to the `after:`. The default is 5.

    • ‘:speech_timeout`: Accepts an interger or “auto”. If both this and `timeout` is set, Twilio will use `timeout` for digits and this value for voice or speech.

    • ‘:profanity_filter`: Replaces any profanity in the transcription with ***. Default is `false`.

It accepts an required ‘after:` object which, will be used to determine the next prompt in the call flow. The after object must be one of:

  • ‘Symbol`: The name of the next prompt in the flow.

  • ‘Hash`: A hash that contains:

    • ‘:message`: An optional message to play before the next prompt. See the above documentation for what a message can contain.

    • ‘:prompt`: The name of the next prompt in the flow.

    • ‘:hangup`: A boolean if the call should be hung up after the message. Only one of prompt and hangup can be present.

  • ‘Proc`: A proc that will be called after the message and gather have been called. The proc will receive the current Models::Response instance as an argument. The proc must return one of the above.



156
157
158
159
 
# File 'lib/twilio/rails/phone/base_tree.rb', line 156

def prompt(prompt_name, message: nil, gather: nil, after:)
  tree.prompts[prompt_name] = Twilio::Rails::Phone::Tree::Prompt.new(name: prompt_name, message: message, gather: gather, after: after)
  nil
end

.tree ⇒ Twilio::Rails::Phone::Tree

The instance of Tree built from the DSL. Should be treated as read-only. Used mostly internally by the framework. It is named according to tree_name.

Returns:



210
211
212
 
# File 'lib/twilio/rails/phone/base_tree.rb', line 210

def tree
  @tree ||= Twilio::Rails::Phone::Tree.new(tree_name)
end

.tree_name ⇒ String

The string name of the tree used to look it up and identify it in the registry and used in the routes. It must be unique and use URL safe characters. It defaults to the class name but can be overridden here.

Returns:

  • (String) —

    the name of the tree.



202
203
204
 
# File 'lib/twilio/rails/phone/base_tree.rb', line 202

def tree_name
  self.name.demodulize.underscore.sub(/_tree\z/, "")
end

.unanswered_call(proc) ⇒ nil

Accepts a proc which will be called when a call goes unanswered, or is answered by an answering machine. The proc will be called asynchronously in a job. The proc will be passed the Models::PhoneCall instance for the call. It is called after the call has been completed so cannot control the flow of the call. It is intended to be used as a hook to handle application logic for unanswered calls. The default is ‘nil` and no action is taken.

Parameters:

  • proc (Proc) —

    the proc to call when a call goes unanswered, must accept a phone call instance.

Returns:

  • (nil) 


169
170
171
172
 
# File 'lib/twilio/rails/phone/base_tree.rb', line 169

def unanswered_call(proc)
  tree.unanswered_call = proc
  nil
end

.voice(voice_name) ⇒ nil

Accepts a string with the voice parameter to be used throughout the phone tree, unless overridden for a given message. See the Twilio documentation for a list of available voices. The voices are dependent on locale, and can also accept Amazon Polly voices. The default is “male”. www.twilio.com/docs/voice/twiml/say/text-speech

Parameters:

  • voice_name (String) —

    the name of the voice to use.

Returns:

  • (nil) 


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

def voice(voice_name)
  tree.config[:voice] = voice_name
  nil
end