twilio-rails 1.0.0

data/lib/twilio/rails/configuration.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    class Configuration
+      # Raised in initialization if the configuration is invalid.
+      class Error < StandardError ; end
+
+      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" ]
+        @no_responses = [ "no", "naw", "nah", "reject", "decline", "negative", "not", "false" ]
+        @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
+
+      # 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.
+      #
+      # @return [String] the default outgoing phone number formatted as "+15555555555"
+      attr_accessor :default_outgoing_phone_number
+
+      # 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)`.
+      #
+      # @return [Logger] the logger used by the framework.
+      attr_accessor :logger
+
+      # The account SID used to authenticate with Twilio. This should be set from an environment variable or from
+      # somewhere like `Rails.credentials`.
+      #
+      # @return [String] the account SID used to authenticate with Twilio.
+      attr_accessor :account_sid
+
+      # The account auth token used to authenticate with Twilio. his should be set from an environment variable or from
+      # somewhere like `Rails.credentials`.
+      #
+      # @return [String] the account auth token used to authenticate with Twilio.
+      attr_accessor :auth_token
+
+      # 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.
+      #
+      # @return [Proc] a proc that will be called to filter messages, or `nil` if no filter is set.
+      attr_accessor :spam_filter
+
+      # 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.
+      #
+      # @return [Proc] a proc that will be called when an exception is raised in certain key points in the framework.
+      attr_accessor :exception_notifier
+
+      # 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.
+      #
+      # @example
+      #   Twilio::Rails.config.attach_recordings = ->(recording) { recording.should_attach_audio? }
+      #
+      # @return [true, false, Proc] a boolean or a proc that will be called to return a boolean to determine if reordings will be downloaded.
+      attr_accessor :attach_recordings
+
+      # A list of strings to be interpreted as yes or acceptance to a question.
+      #
+      # @return [Array<String>] a list of strings to be interpreted as yes or acceptance to a question.
+      attr_accessor :yes_responses
+
+      # A list of strings to be interpreted as no or rejection to a question.
+      #
+      # @return [Array<String>] a list of strings to be interpreted as no or rejection to a question.
+      attr_accessor :no_responses
+
+      # 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.
+      #
+      # @return [String] the name of the model class defined in the Rails application.
+      attr_accessor :phone_caller_class_name, :phone_call_class_name, :response_class_name,
+        :sms_conversation_class_name, :message_class_name, :recording_class_name
+      # @return [Class] the class of the model defined in the Rails application constantized from the string name.
+      attr_reader :phone_caller_class, :phone_call_class, :response_class,
+        :sms_conversation_class, :message_class, :recording_class
+
+      # 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.
+      #
+      # @return [PhoneTreeRegistry] a registry of phone tree classes that are used to handle incoming phone calls.
+      attr_reader :phone_trees
+
+      # 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.
+      #
+      # @return [SMSResponderRegistry] a registry of SMS responder classes that are used to handle incoming messages.
+      attr_reader :sms_responders
+
+      # 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`.
+      #
+      # @return [String] the host and protocol where Twilio can reach the application, formatted "https://example.com".
+      attr_reader :host
+      # Sets the host and protocol where Twilio can reach the application, formatted "https://example.com".
+      #
+      # @param value [String] the host and protocol where Twilio can reach the application, formatted "https://example.com".
+      def host=(value)
+        @host = if value.is_a?(String)
+          value.gsub(/\/$/, "")
+        else
+          value
+        end
+      end
+
+      # The {#host} domain name with the protocol stripped, if the host is set.
+      #
+      # @return [String] the {#host} domain name.
+      def host_domain
+        return nil unless host.present?
+        value = host.gsub(/\Ahttps?:\/\//, "")
+        value = value.gsub(/:\d+\z/, "")
+        value
+      end
+
+      # 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.
+      #
+      # @return [Array<Symbol>] the HTTP methods used for the routes that Twilio will use to call into the app.
+      attr_accessor :controller_http_methods
+
+      # 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 {Twilio::Rails::Phone::TreeMacros}.
+      #
+      # @param [Module] mod a module to be included into the `macros` module use in the phone tree DSL.
+      # @return [nil]
+      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
+
+      # Uses the {#attach_recordings} configuration to determine if the recording should be downloaded and attached.
+      #
+      # @return [true, false] If this recording should be downloaded and attached.
+      def attach_recording?(recording)
+        if attach_recordings.is_a?(Proc) || attach_recordings.respond_to?(:call)
+          !!attach_recordings.call(recording)
+        else
+          !!attach_recordings
+        end
+      end
+
+      # 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.
+      #
+      # @return [nil]
+      def setup!
+        @setup = true
+        nil
+      end
+
+      # 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.
+      #
+      # @return [nil]
+      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
+
+      # 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.
+      #
+      # @return [true]
+      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
+
+      # Base abstract registry class for configuration both phone trees and SMS responders.
+      # @abstract
+      class Registry
+        def initialize
+          @finalized = false
+          @registry = {}.with_indifferent_access
+          @values = []
+        end
+
+        # Finalizes the registry and makes it ready for use. It evaluates the blocks and constantizes the class names.
+        # Looks up the constants each time `to_prepare` is called, so frequently in dev but only once in production.
+        #
+        # @return [true]
+        def finalize!
+          @registry = {}.with_indifferent_access
+          @values.each { |value| add_to_registry(value) }
+          @finalized = true
+        end
+
+        # Registers a phone tree or SMS responder. It accepts a callable, a Class, a String, or a block which returns
+        # any of the aforementioned. The result will all be turned into a class when {#finalize!} is called. This can be
+        # called multiple times.
+        #
+        # @param klass_or_proc [Class, String, Proc] value containing the Class to be lazily initialized when {#finalize!} is called.
+        # @yield [nil] if a block is passed, it will be called and the result will be used as the value.
+        # @yieldreturn [Class, String, Proc] containing the Class to be lazily initialized when {#finalize!} is called.
+        # @return [nil]
+        def register(klass_or_proc=nil, &block)
+          raise Error, "Must pass either a param or a block" unless klass_or_proc.present? ^ block.present?
+          value = klass_or_proc || block
+
+          @values << value
+          add_to_registry(value) if @finalized
+
+          nil
+        end
+
+        # Returns the phone tree or SMS responder for the given name, or raises an error if it is not found.
+        #
+        # @param [String, Symbol] name of the phone tree or SMS responder to find.
+        # @return [Class] the phone tree or SMS responder class.
+        def for(name)
+          @registry[name.to_s] || raise(error_class, "No responder registered for '#{ name }'")
+        end
+
+        # Returns all the phone trees or SMS responders as a read-only hash, keyed by name.
+        #
+        # @return [Hash] all the phone trees or SMS responders.
+        def all
+          @registry.dup.freeze
+        end
+
+        private
+
+        def add_to_registry(value)
+          raise NotImplementedError
+        end
+
+        def error_class
+          StandardError
+        end
+      end
+
+      # Registry class used to store and query SMS responders in the configuration. It is the value
+      # of {Twilio::Rails::Configuration#sms_responders}.
+      class SMSResponderRegistry < Registry
+        private
+
+        def add_to_registry(value)
+          value = value.call if value.respond_to?(:call)
+          begin
+            value = value.constantize if value.is_a?(String)
+          rescue NameError => e
+            raise(error_class, "Responder class '#{ value }' could not be constantized")
+          end
+          raise(error_class, "Responder cannot be blank") unless value.present?
+          raise(error_class, "Responder must be a class but got #{ value.inspect }") unless value.is_a?(Class)
+          name = value.responder_name
+          raise(error_class, "Responder name cannot be blank") unless name.present?
+          raise(error_class, "Responder name '#{ name }' is already registered") if @registry[name]
+          @registry[name] = value
+        end
+
+        def error_class
+          Twilio::Rails::SMS::InvalidResponderError
+        end
+      end
+
+      # Registry class used to store and query phone trees in the configuration. It is the value
+      # of  {Twilio::Rails::Configuration#phone_trees}.
+      class PhoneTreeRegistry < Registry
+        private
+
+        def add_to_registry(value)
+          value = value.call if value.respond_to?(:call)
+          begin
+            value = value.constantize if value.is_a?(String)
+          rescue NameError => e
+            raise(error_class, "Tree class '#{ value }' could not be constantized")
+          end
+          raise(error_class, "Tree cannot be blank #{ value }") unless value.present?
+          raise(error_class, "Tree is not a Twilio::Rails::Phone::BaseTree class #{ value }") unless value.is_a?(Class)
+          raise(error_class, "Tree is not a Twilio::Rails::Phone::BaseTree #{ value }") unless value.ancestors.include?(Twilio::Rails::Phone::BaseTree)
+          name = value.tree_name
+          raise(error_class, "Tree name cannot be blank") unless name.present?
+          raise(error_class, "Tree name '#{ name }' is already registered") if @registry[name]
+          klass = klass.constantize if klass.is_a?(String)
+          @registry[name] = value.tree
+        end
+
+        def error_class
+          Twilio::Rails::Phone::InvalidTreeError
+        end
+      end
+    end
+  end
+end

data/lib/twilio/rails/engine.rb

@@ -0,0 +1,11 @@
+module Twilio
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace Twilio::Rails
+
+      config.to_prepare do
+        Twilio::Rails.config.finalize!
+      end
+    end
+  end
+end

data/lib/twilio/rails/formatter.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Formatter
+      extend self
+
+      PHONE_NUMBER_REGEX = /\A\+1[0-9]{10}\Z/
+      PHONE_NUMBER_SEGMENTS_REGEX = /\A\+1([0-9]{3})([0-9]{3})([0-9]{4})\Z/
+
+      # Takes in a string or a {Twilio::Rails::PhoneNumber} or something that responds to `to_s` and turns it into a
+      # consistently formatted valid north american 10 digit phone number prefixed with 1 and plus. It uses the format
+      # Twilio expects which is "+15555555555" or returns `nil` if it cannot be coerced.
+      #
+      # @param string [String, Twilio::Rails::PhoneNumber, nil, Object] the input to turn into a phone number string.
+      # @return [String, nil] the phone number string or nil.
+      def coerce_to_valid_phone_number(string)
+        string = string.number if string.is_a?(Twilio::Rails::PhoneNumber)
+        string = string.to_s.presence
+
+        if string
+          string = string.gsub(/[^0-9]/, "")
+          string = "1#{ string }" unless string.starts_with?("1")
+          string = "+#{ string }"
+          string = nil unless valid_north_american_phone_number?(string)
+        end
+
+        string
+      end
+
+      # Takes in a string or a {Twilio::Rails::PhoneNumber} or something that responds to `to_s` and validates it
+      # matches the expected format "+15555555555" of a north american phone number.
+      #
+      # @param phone_number [String, Twilio::Rails::PhoneNumber, nil] the input to validate as a phone number.
+      # @return [true, false]
+      def valid_north_american_phone_number?(phone_number)
+        phone_number = phone_number.number if phone_number.is_a?(Twilio::Rails::PhoneNumber)
+        !!phone_number&.match?(PHONE_NUMBER_REGEX)
+      end
+
+      # Takes in a string or a {Twilio::Rails::PhoneNumber} or something that responds to `to_s` and turns it into
+      # a phone number formatted for URLs. Appropriate to use for `#to_param` in Rails or other controller concerns
+      # where a phone number or phone caller can be passed around as a URL parameter.
+      #
+      # @param phone_number [String, Twilio::Rails::PhoneNumber, nil] the input to turn into a phone number string.
+      # @return [String] the phone number string or empty string if invalid.
+      def to_phone_number_url_param(phone_number)
+        phone_number = coerce_to_valid_phone_number(phone_number)
+        return "" unless phone_number
+        matches = phone_number.match(PHONE_NUMBER_SEGMENTS_REGEX)
+        raise Twilio::Rails::Error, "[to_phone_number_url_param] Phone number marked as valid but could not capture. I made a bad regex: #{ phone_number }" unless matches
+        matches.captures.join("-")
+      end
+
+      # Takes in a string or a {Twilio::Rails::PhoneNumber} or something that responds to `to_s` and turns it into a
+      # phone number string formatted for display. If the number cannot be coerced to a valid phone number it will be
+      # passed through.
+      #
+      # @param phone_number [String, Twilio::Rails::PhoneNumber, nil] the input to turn into a phone number string.
+      # @return [String, Object] the phone number string or the original object if invalid.
+      def display_phone_number(phone_number)
+        coerced_phone_number = coerce_to_valid_phone_number(phone_number)
+        if coerced_phone_number
+          matches = coerced_phone_number.match(PHONE_NUMBER_SEGMENTS_REGEX)
+          raise Twilio::Rails::Error, "[display_phone_number] Phone number marked as valid but could not capture. I made a bad regex: #{ phone_number }" unless matches
+          "(#{ matches.captures[0] }) #{ matches.captures[1] } #{ matches.captures[2] }"
+        else
+          phone_number
+        end
+      end
+
+      # Formats a city, province, and country into a single string, correctly handling blanks, and formatting countries.
+      #
+      # @param city [String, nil] the city name.
+      # @param province [String, nil] the province name.
+      # @param country [String, nil] the country code.
+      # @return [String] the formatted location string.
+      def location(city: nil, country: nil, province: nil)
+        country_name = case country
+        when "CA" then "Canada"
+        when "US" then "USA"
+        else
+          country
+        end
+
+        [
+          city.presence&.titleize,
+          province,
+          country_name,
+        ].reject(&:blank?).join(", ")
+      end
+    end
+  end
+end

data/lib/twilio/rails/models/message.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Models
+      # A message sent or received via SMS. Belongs to a {Twilio::Rails::Models::SmsConversation}. Has a direction to
+      # indicate whether it was sent or received.
+      module Message
+        extend ActiveSupport::Concern
+
+        included do
+          include Twilio::Rails::HasDirection
+          include Twilio::Rails::HasTimeScopes
+
+          belongs_to :sms_conversation, class_name: Twilio::Rails.config.sms_conversation_class_name
+
+          scope :in_order, -> { reorder(created_at: :asc) }
+        end
+      end
+    end
+  end
+end

data/lib/twilio/rails/models/phone_call.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Models
+      # The record of a phone call. Can be inbound or outbound. The associated {Twilio::Rails::Models::Response} objects
+      # in order track the progress of the call.
+      module PhoneCall
+        extend ActiveSupport::Concern
+
+        included do
+          include Twilio::Rails::HasDirection
+          include Twilio::Rails::HasTimeScopes
+
+          validates :sid, presence: true
+          validates_associated :phone_caller
+
+          belongs_to :phone_caller, class_name: Twilio::Rails.config.phone_caller_class_name
+
+          has_many :responses, -> { order(created_at: :asc) }, dependent: :destroy, class_name: Twilio::Rails.config.response_class_name
+          has_many :recordings, -> { order(created_at: :asc) }, dependent: :destroy, class_name: Twilio::Rails.config.recording_class_name
+
+          scope :recent, -> { reorder(created_at: :desc).limit(10) }
+          scope :tree, ->(name) { where(tree_name: name) }
+          scope :called_today, -> { where("created_at > ?", Time.now - 1.day).includes(:phone_caller).order(created_at: :asc) }
+          scope :in_progress, -> { where(call_status: "in-progress") }
+          scope :finished, -> { where(finished: true) }
+          scope :unfinished, -> { where(finished: false) }
+
+          after_save :status_callback
+        end
+
+        # All possible call statuses:
+        # "queued", "initiated", "ringing", "in-progress", "completed", "canceled", "busy", "no-answer", "failed"
+
+        class_methods do
+          # Returns the number of unique callers for a given tree.
+          #
+          # @param tree [String, Twilio::Rails::Phone::Tree, String, Symbol] The tree or name of the tree.
+          # @return [Integer] The number of unique callers for the tree.
+          def caller_count_for_tree(tree)
+            tree = tree.is_a?(Twilio::Rails::Phone::Tree) ? tree.name : tree
+            tree(tree).pluck(:phone_caller_id).uniq.count
+          end
+        end
+
+        # Indicates if the call was answered by an answering machine. Only will return true if answering machine
+        # detection is enabled. Is always false for inbound calls.
+        #
+        # @return [true, false] true if the call was answered by an answering machine.
+        def answering_machine?
+          outbound? && answered_by == "machine_start"
+        end
+
+        # Indicates if the call was not answered, busy, or failed. Is always false for inbound calls.
+        #
+        # @return [true, false] true if the call was not answered by a person.
+        def no_answer?
+          outbound? && call_status.in?(["busy", "failed", "no-answer"])
+        end
+
+        # Checks if the call is in the completed state. This does not cover all possible states for a call that is not
+        # in progress. See {#in_progress?} to check if a call is finished or not.
+        #
+        # @return [true, false] true if the call is in the completed state.
+        def completed?
+          call_status.in?(["completed"])
+        end
+
+        # Checks if that call is in a state where it is currently in progress with the caller. This includes ringing,
+        # queued, initiated, or in progress. Use this method to check if the call has finished or not.
+        #
+        # @return [true, false] true if the call is currently ringing, queued, or in progress.
+        def in_progress?
+          call_status.blank? || call_status.in?(["queued", "initiated", "ringing", "in-progress"])
+        end
+
+        # A formatted string for the location data of the caller provided by Twilio, if any is available.
+        #
+        # @return [String] The location of the caller.
+        def location
+          Twilio::Rails::Formatter.location(city: from_city, country: from_country, province: from_province)
+        end
+
+        # @return [String] The {Twilio::Rails::Phone::Tree} for the call.
+        def tree
+          @tree ||= Twilio::Rails.config.phone_trees.for(tree_name)
+        end
+
+        # Checks if the call is for a given tree or trees, by class or by name.
+        #
+        # @param tree [Twilio::Rails::Phone::Tree, String, Symbol, Array] The tree or name of the tree, or an array of either.
+        # @return [true, false] true if the call is for the given tree or trees.
+        def for?(tree:)
+          trees = Array(tree).map { |t| t.is_a?(Twilio::Rails::Phone::Tree) ? t.name : t.to_s }
+
+          trees.include?(tree_name)
+        end
+
+        # Updates the `length_seconds` attribute based on the time difference between the first and most recent
+        # responses in the phone call. Called by {Twilio::Rails::Phone::Response} when it is updated.
+        #
+        # @return [Integer] The length of the call in seconds.
+        def recalculate_length
+          first_response = responses.in_order.first
+          last_response = responses.in_order.last
+          result = 0
+          estimated_length_seconds = 5 # scientifically determined to be extremely accurate
+
+          result = last_response.created_at.to_i - first_response.created_at.to_i + estimated_length_seconds if first_response
+          update!(length_seconds: result)
+          result
+        end
+
+        private
+
+        def status_callback
+          if saved_changes.key?("call_status") && no_answer?
+            Twilio::Rails::Phone::UnansweredCallJob.perform_later(phone_call_id: id)
+          end
+
+          if saved_changes.key?("call_status") && !in_progress?
+            Twilio::Rails::Phone::FinishedCallJob.perform_later(phone_call_id: id)
+          end
+
+          if saved_changes.key?("answered_by") && answering_machine?
+            Twilio::Rails::Phone::UnansweredCallJob.perform_later(phone_call_id: id)
+          end
+        end
+      end
+    end
+  end
+end