Class: Twilio::Rails::Configuration

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

Defined Under Namespace

Classes: Error, PhoneTreeRegistry, Registry, SMSResponderRegistry

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/twilio/rails/configuration.rb', line 8

def initialize
  @finalized = false
  @setup = false

  @default_outgoing_phone_number = nil
  @logger = ::Rails.logger
  @account_sid = nil
  @auth_token = nil
  @spam_filter = nil
  @exception_notifier = nil
  @attach_recordings = true
  @yes_responses = [ "yes", "accept", "ya", "yeah", "true", "ok", "okay", "yep", "yup", "yes please" ]
  @no_responses = [ "no", "naw", "nah", "reject", "decline", "negative", "not", "false", "nope", "no thank you", "know" ]
  @message_class_name = "Message"
  @message_class = nil
  @phone_call_class_name = "PhoneCall"
  @phone_call_class = nil
  @phone_caller_class_name = "PhoneCaller"
  @phone_caller_class = nil
  @sms_conversation_class_name = "SMSConversation"
  @sms_conversation_class = nil
  @response_class_name = "Response"
  @response_class = nil
  @recording_class_name = "Recording"
  @recording_class = nil
  @phone_trees = PhoneTreeRegistry.new
  @sms_responders = SMSResponderRegistry.new
  @host = if ::Rails.configuration&.action_controller&.default_url_options
    "#{ ::Rails.configuration.action_controller.default_url_options[:protocol] }://#{ ::Rails.configuration.action_controller.default_url_options[:host] }"
  else
    nil
  end
  @controller_http_methods = [:get, :post]
  @include_phone_macros = []
end

Instance Attribute Details

#account_sid ⇒ String

The account SID used to authenticate with Twilio. This should be set from an environment variable or from somewhere like ‘Rails.credentials`.

Returns:

  • (String) —

    the account SID used to authenticate with Twilio.



62
63
64
 
# File 'lib/twilio/rails/configuration.rb', line 62

def 
  @account_sid
end

#attach_recordings ⇒ true, ...

Controls if recordings will be downloaded and attached to the ‘Recording` model in an ActiveStorage attachment. This is `true` by default, but can be set to `false` to disable all downloads. It can also be set to a `Proc` or callable that will receive the `Recording` instance and return a boolean for this specific instance. A typical usage would be to delegate to the model or a business logic process to determine if the recording should be downloaded.

Examples:

Twilio::Rails.config.attach_recordings = ->(recording) { recording.should_attach_audio? }

Returns:

  • (true, false, Proc) —

    a boolean or a proc that will be called to return a boolean to determine if reordings will be downloaded.



96
97
98
 
# File 'lib/twilio/rails/configuration.rb', line 96

def attach_recordings
  @attach_recordings
end

#auth_token ⇒ String

The account auth token used to authenticate with Twilio. his should be set from an environment variable or from somewhere like ‘Rails.credentials`.

Returns:

  • (String) —

    the account auth token used to authenticate with Twilio.



68
69
70
 
# File 'lib/twilio/rails/configuration.rb', line 68

def auth_token
  @auth_token
end

#controller_http_methods ⇒ Array<Symbol>

The HTTP methods that Twilio will use to call into the app. Defaults to ‘[:get, :post]` but can be restricted to just `[:get]` or `[:post]`. This must match the configuration in the Twilio dashboard.

Returns:

  • (Array<Symbol>) —

    the HTTP methods used for the routes that Twilio will use to call into the app.



166
167
168
 
# File 'lib/twilio/rails/configuration.rb', line 166

def controller_http_methods
  @controller_http_methods
end

#default_outgoing_phone_number ⇒ String

This is the phone number that will be used to send SMS messages or start Phone Calls. It must be first configured and purchased in the Twilio dashboard, then entered here. The format must be “+15556667777”. In most applications it is probably the only number, but in more complex applications it is the “main” or default number. It is used when the phone number is not specified and the number otherwise cannot be intelligently guessed or inferred.

Returns:

  • (String) —

    the default outgoing phone number formatted as “+15555555555”



50
51
52
 
# File 'lib/twilio/rails/configuration.rb', line 50

def default_outgoing_phone_number
  @default_outgoing_phone_number
end

#exception_notifier ⇒ Proc

A proc that will be called when an exception is raised in certain key points in the framework. This will never capture the exception, it will raise regardless, but it is a good spot to send an email or notify in chat if desired. The proc needs to accept ‘(exception, message, context, exception_binding)` as arguments. The default is `nil`, which means no action will be taken.

Returns:

  • (Proc) —

    a proc that will be called when an exception is raised in certain key points in the framework.



84
85
86
 
# File 'lib/twilio/rails/configuration.rb', line 84

def exception_notifier
  @exception_notifier
end

#host ⇒ String

The default protocol and host used to generate URLs for Twilio to call back to. Defaults to what is defined by ‘Rails` using `default_url_options`.

Returns:

  • (String) —

    the host and protocol where Twilio can reach the application, formatted “example.com”.



140
141
142
 
# File 'lib/twilio/rails/configuration.rb', line 140

def host
  @host
end

#logger ⇒ Logger

The logger used by the framework. Defaults to ‘Rails.logger`. It cannot be `nil`, so to disable framework logging explicitly set it to `Logger.new(nil)`.

Returns:

  • (Logger) —

    the logger used by the framework.



56
57
58
 
# File 'lib/twilio/rails/configuration.rb', line 56

def logger
  @logger
end

#message_class ⇒ Class (readonly)

Returns the class of the model defined in the Rails application constantized from the string name.

Returns:

  • (Class) —

    the class of the model defined in the Rails application constantized from the string name.



118
119
120
 
# File 'lib/twilio/rails/configuration.rb', line 118

def message_class
  @message_class
end

#message_class_name ⇒ String

The name of the model classes, as strings, that this application uses to represent the concepts stored in the DB. The generators will generate the models with the default names below, but they can be changed as the application may need.

Returns:

  • (String) —

    the name of the model class defined in the Rails application.



115
116
117
 
# File 'lib/twilio/rails/configuration.rb', line 115

def message_class_name
  @message_class_name
end

#no_responses ⇒ Array<String>

A list of strings to be interpreted as no or rejection to a question. Pairs with the Phone::TreeMacros#answer_no? method.

Returns:

  • (Array<String>) —

    a list of strings to be interpreted as no or rejection to a question.



108
109
110
 
# File 'lib/twilio/rails/configuration.rb', line 108

def no_responses
  @no_responses
end

#phone_call_class ⇒ Class (readonly)

Returns the class of the model defined in the Rails application constantized from the string name.

Returns:

  • (Class) —

    the class of the model defined in the Rails application constantized from the string name.



118
119
120
 
# File 'lib/twilio/rails/configuration.rb', line 118

def phone_call_class
  @phone_call_class
end

#phone_call_class_name ⇒ String

The name of the model classes, as strings, that this application uses to represent the concepts stored in the DB. The generators will generate the models with the default names below, but they can be changed as the application may need.

Returns:

  • (String) —

    the name of the model class defined in the Rails application.



115
116
117
 
# File 'lib/twilio/rails/configuration.rb', line 115

def phone_call_class_name
  @phone_call_class_name
end

#phone_caller_class ⇒ Class (readonly)

Returns the class of the model defined in the Rails application constantized from the string name.

Returns:

  • (Class) —

    the class of the model defined in the Rails application constantized from the string name.



118
119
120
 
# File 'lib/twilio/rails/configuration.rb', line 118

def phone_caller_class
  @phone_caller_class
end

#phone_caller_class_name ⇒ String

The name of the model classes, as strings, that this application uses to represent the concepts stored in the DB. The generators will generate the models with the default names below, but they can be changed as the application may need.

Returns:

  • (String) —

    the name of the model class defined in the Rails application.



115
116
117
 
# File 'lib/twilio/rails/configuration.rb', line 115

def phone_caller_class_name
  @phone_caller_class_name
end

#phone_trees ⇒ PhoneTreeRegistry (readonly)

A registry of phone tree classes that are used to handle incoming phone calls. Calling ‘register` will add a responder, and they can be accessed via `all` or `for(name)`. The tree is built by subclassing `Twilio::Rails::Phone::BaseTree` and defining the tree as described in the documentation.

Returns:

  • (PhoneTreeRegistry) —

    a registry of phone tree classes that are used to handle incoming phone calls.



126
127
128
 
# File 'lib/twilio/rails/configuration.rb', line 126

def phone_trees
  @phone_trees
end

#recording_class ⇒ Class (readonly)

Returns the class of the model defined in the Rails application constantized from the string name.

Returns:

  • (Class) —

    the class of the model defined in the Rails application constantized from the string name.



118
119
120
 
# File 'lib/twilio/rails/configuration.rb', line 118

def recording_class
  @recording_class
end

#recording_class_name ⇒ String

The name of the model classes, as strings, that this application uses to represent the concepts stored in the DB. The generators will generate the models with the default names below, but they can be changed as the application may need.

Returns:

  • (String) —

    the name of the model class defined in the Rails application.



115
116
117
 
# File 'lib/twilio/rails/configuration.rb', line 115

def recording_class_name
  @recording_class_name
end

#response_class ⇒ Class (readonly)

Returns the class of the model defined in the Rails application constantized from the string name.

Returns:

  • (Class) —

    the class of the model defined in the Rails application constantized from the string name.



118
119
120
 
# File 'lib/twilio/rails/configuration.rb', line 118

def response_class
  @response_class
end

#response_class_name ⇒ String

The name of the model classes, as strings, that this application uses to represent the concepts stored in the DB. The generators will generate the models with the default names below, but they can be changed as the application may need.

Returns:

  • (String) —

    the name of the model class defined in the Rails application.



115
116
117
 
# File 'lib/twilio/rails/configuration.rb', line 115

def response_class_name
  @response_class_name
end

#sms_conversation_class ⇒ Class (readonly)

Returns the class of the model defined in the Rails application constantized from the string name.

Returns:

  • (Class) —

    the class of the model defined in the Rails application constantized from the string name.



118
119
120
 
# File 'lib/twilio/rails/configuration.rb', line 118

def sms_conversation_class
  @sms_conversation_class
end

#sms_conversation_class_name ⇒ String

The name of the model classes, as strings, that this application uses to represent the concepts stored in the DB. The generators will generate the models with the default names below, but they can be changed as the application may need.

Returns:

  • (String) —

    the name of the model class defined in the Rails application.



115
116
117
 
# File 'lib/twilio/rails/configuration.rb', line 115

def sms_conversation_class_name
  @sms_conversation_class_name
end

#sms_responders ⇒ SMSResponderRegistry (readonly)

A registry of SMS responder classes that are used to handle incoming SMS messages. Calling ‘register` will add a responder, and they can be accessed via `all` or `for(name)`. The class must either be a subclass of `Twilio::Rails::SMS::DelegatedResponder` or implement the same interface. Responders are evaluated in the order they are registered.

Returns:

  • (SMSResponderRegistry) —

    a registry of SMS responder classes that are used to handle incoming messages.



134
135
136
 
# File 'lib/twilio/rails/configuration.rb', line 134

def sms_responders
  @sms_responders
end

#spam_filter ⇒ Proc

Allows SMS messages to be filtered at source if they appear to be spam. This is an optional callable that is run with raw params from Twilio on each request. If the callable returns ‘true` it will prevent the message from being processed. This is useful for filtering out messages that are obviously spam. Setting this to `nil` will disable the filter and is the default.

Returns:

  • (Proc) —

    a proc that will be called to filter messages, or ‘nil` if no filter is set.



76
77
78
 
# File 'lib/twilio/rails/configuration.rb', line 76

def spam_filter
  @spam_filter
end

#yes_responses ⇒ Array<String>

A list of strings to be interpreted as yes or acceptance to a question. Pairs with the Phone::TreeMacros#answer_yes? method.

Returns:

  • (Array<String>) —

    a list of strings to be interpreted as yes or acceptance to a question.



102
103
104
 
# File 'lib/twilio/rails/configuration.rb', line 102

def yes_responses
  @yes_responses
end

Instance Method Details

#attach_recording?(recording) ⇒ true, false

Uses the #attach_recordings configuration to determine if the recording should be downloaded and attached.

Returns:

  • (true, false) —

    If this recording should be downloaded and attached.



190
191
192
193
194
195
196
 
# File 'lib/twilio/rails/configuration.rb', line 190

def attach_recording?(recording)
  if attach_recordings.is_a?(Proc) || attach_recordings.respond_to?(:call)
    !!attach_recordings.call(recording)
  else
    !!attach_recordings
  end
end

#finalize! ⇒ true

Finalizes the configuration and makes it ready for use. This is called by the railtie after initialization. It constantizes and performs the final steps that assumes the whole app has been initalized. Called in ‘to_prepare` in the engine, so this is called on every code reload in development mode.

Returns:

  • (true) 


234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/twilio/rails/configuration.rb', line 234

def finalize!
  return nil unless @setup
  validate!

  [
    :phone_caller_class_name,
    :phone_call_class_name,
    :response_class_name,
    :sms_conversation_class_name,
    :message_class_name,
    :recording_class_name,
  ].each do |attribute|
    value = self.send(attribute)
    raise Error, "`#{attribute}` must be set to a string name" if value.blank? || !value.is_a?(String)
    begin
      klass = value.constantize
      instance_variable_set("@#{ attribute.to_s.gsub("_name", "") }", klass)
    rescue NameError
      raise Error, "`#{attribute}` must be a valid class name but could not be found or constantized"
    end
  end

  until @include_phone_macros.empty?
    Twilio::Rails::Phone::TreeMacros.include(@include_phone_macros.pop)
  end

  @phone_trees.finalize!
  @sms_responders.finalize!

  @finalized = true
end

#host_domain ⇒ String

The #host domain name with the protocol stripped, if the host is set.

Returns:

  • (String) —

    the #host domain name.



155
156
157
158
159
160
 
# File 'lib/twilio/rails/configuration.rb', line 155

def host_domain
  return nil unless host.present?
  value = host.gsub(/\Ahttps?:\/\//, "")
  value = value.gsub(/:\d+\z/, "")
  value
end

#include_phone_macros(mod) ⇒ nil

Allows adding a module to be included into the ‘macros` in the phone tree DSL. This is useful for adding convenience methods specific to the application. It can be called multiple times to add multiple modules. Built in macros can be seen in Phone::TreeMacros.

Parameters:

  • mod (Module) —

    a module to be included into the ‘macros` module use in the phone tree DSL.

Returns:

  • (nil) 


174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/twilio/rails/configuration.rb', line 174

def include_phone_macros(mod)
  @include_phone_macros << mod

  if @finalized
    validate!
    until @include_phone_macros.empty?
      Twilio::Rails::Phone::TreeMacros.include(@include_phone_macros.pop)
    end
  end

  nil
end

#setup! ⇒ nil

Flags that the configuration has been setup and should be validated and finalized. If this is not called, the framework will not work, but the Railtie will not prevent the application from starting.

Returns:

  • (nil) 


203
204
205
206
 
# File 'lib/twilio/rails/configuration.rb', line 203

def setup!
  @setup = true
  nil
end

#validate! ⇒ nil

Validates the configuration and raises an error if it is invalid. This is called after initialization, but is not the finalized configuration. See #finalize! for the last step.

Returns:

  • (nil)

Raises:



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/twilio/rails/configuration.rb', line 212

def validate!
  return nil unless @setup
  raise Error, "`default_outgoing_phone_number` must be set" if @default_outgoing_phone_number.blank?
  raise Error, "`default_outgoing_phone_number` must be a String of the format `\"+12223334444\"`" unless @default_outgoing_phone_number.is_a?(String) && @default_outgoing_phone_number.match?(/\A\+1[0-9]{10}\Z/)
  raise Error, "`account_sid` must be set" if @account_sid.blank?
  raise Error, "`auth_token` must be set" if @auth_token.blank?
  raise Error, "`logger` must be set" if @logger.blank?
  raise Error, "`spam_filter` must be callable" if @spam_filter && !@spam_filter.respond_to?(:call)
  raise Error, "`exception_notifier` must be callable" if @exception_notifier && !@exception_notifier.respond_to?(:call)
  raise Error, '`yes_responses` must be an array' unless @yes_responses.is_a?(Array)
  raise Error, '`no_responses` must be an array' unless @no_responses.is_a?(Array)
  raise Error, "`host` #{ @host.inspect } is not a valid URL of the format https://example.com without the trailing slash" unless @host =~ /\Ahttps?:\/\/[a-z0-9\-\.:]+\Z/i
  raise Error, "`controller_http_methods` must be an array containing one or both of `:get` and `:post` but was #{ @controller_http_methods.inspect }" unless @controller_http_methods.is_a?(Array) && @controller_http_methods.sort == [:get, :post].sort || @controller_http_methods == [:get] || @controller_http_methods == [:post]
  raise Error, "`include_phone_macros` must be a module, but received #{ @include_phone_macros.inspect }" unless @include_phone_macros.all? { |mod| mod.is_a?(Module) }
  nil
end