twilio-rails 1.0.0

data/app/operations/twilio/rails/phone/twiml/timeout_operation.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      module Twiml
+        class TimeoutOperation < Twilio::Rails::Phone::Twiml::BaseOperation
+          input :tree, accepts: Twilio::Rails::Phone::Tree, type: :keyword, required: true
+          input :response_id, accepts: Integer, type: :keyword, required: true
+
+          def execute
+            return Twilio::Rails::Phone::Twiml::ErrorOperation.call(phone_call_id: phone_call.id, tree: tree) if phone_call.answering_machine?
+
+            response = phone_call.responses.find(response_id)
+            response.timeout = true
+            response.save!
+
+            if final_timeout?(response, count: tree.config[:final_timeout_attempts])
+              twiml_response = Twilio::TwiML::VoiceResponse.new do |twiml|
+                add_messages(twiml, message_set: tree.config[:final_timeout_message], response: response)
+                twiml.hangup
+              end
+
+              Twilio::Rails.config.logger.info("final timeout on phone_call##{ phone_call.id }")
+              Twilio::Rails.config.logger.info("timeout_twiml: #{twiml_response.to_s}")
+              twiml_response.to_s
+            else
+              prompt = tree.prompts[response.prompt_handle]
+              raise Twilio::Rails::Phone::InvalidTreeError, "cannot find #{ response.prompt_handle } in #{ tree.name }" unless prompt
+
+              after = prompt.after
+              after = Twilio::Rails::Phone::Tree::After.new(after.proc.call(response)) if after.proc
+
+              Twilio::Rails::Phone::Twiml::AfterOperation.call(phone_call_id: phone_call.id, tree: tree, after: after)
+            end
+          end
+
+          private
+
+          def final_timeout?(last_response, count: )
+            responses = phone_call.responses.final_timeout_check(count: count, prompt_handle: last_response.prompt_handle)
+
+            responses.count == count && responses.all? { |r| r.timeout? }
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/unanswered_call_operation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      class UnansweredCallOperation < ::Twilio::Rails::Phone::BaseOperation
+        def execute
+          if !phone_call.outbound?
+            Twilio::Rails.config.logger.tagged(self.class) { |l| l.error("Should never be called on inbound call") }
+            halt
+          end
+
+          if phone_call.unanswered?
+            Twilio::Rails.config.logger.tagged(self.class) { |l| l.warn("Skipping duplicate unanswered call job") }
+          else
+            phone_call.update!(unanswered: true)
+            phone_call.tree.unanswered_call.call(phone_call) if phone_call.tree.unanswered_call
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/update_operation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      class UpdateOperation < ::Twilio::Rails::Phone::BaseOperation
+        input :params, accepts: Hash, type: :keyword, required: true
+
+        def execute
+          if phone_call.outbound?
+            if params["AnsweredBy"].present? && phone_call.answered_by != params["AnsweredBy"]
+              phone_call.answered_by = params["AnsweredBy"]
+            end
+          end
+
+          if params["CallStatus"].present? && phone_call.call_status != params["CallStatus"]
+            phone_call.call_status = params["CallStatus"]
+          end
+
+          phone_call.save! if phone_call.changed?
+
+          phone_call
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/update_response_operation.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      class UpdateResponseOperation < ::Twilio::Rails::Phone::BaseOperation
+        input :params, accepts: Hash, type: :keyword, required: true
+        input :response_id, accepts: Integer, type: :keyword, required: true
+
+        def execute
+          response = phone_call.responses.find(response_id)
+
+          if params["Digits"].present?
+            response.digits = params["Digits"]
+          end
+
+          if params["TranscriptionText"].present? && params["TranscriptionStatus"] == "completed"
+            response.transcription = params["TranscriptionText"]
+            response.transcribed = true
+          end
+
+          if params["SpeechResult"].present?
+            response.transcription = params["SpeechResult"]
+            response.transcribed = true
+          end
+
+          response.save! if response.changed?
+
+          if params["RecordingSid"]
+            Twilio::Rails::Phone::ReceiveRecordingOperation.call(phone_call_id: phone_call.id, response_id: response.id, params: params)
+            response.reload # This attaches to the other end of the association so this instance doesn't know about it without a reload
+          end
+
+          response
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/sms/base_operation.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module SMS
+      # Base class for all SMS operations. Requires the `sms_conversation_id` to be passed in.
+      class BaseOperation < ::Twilio::Rails::ApplicationOperation
+        input :sms_conversation_id, accepts: Integer, type: :keyword, required: true
+
+        protected
+
+        def conversation
+          @conversation ||= ::Twilio::Rails.config.sms_conversation_class.find(sms_conversation_id)
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/sms/create_operation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module SMS
+      # Called by {Twilio::Rails::SMSController} with the Twilio params to create a new SMS conversation.
+      class CreateOperation < ApplicationOperation
+        input :params, accepts: Hash, type: :keyword, required: true
+
+        def execute
+          conversation = ::Twilio::Rails.config.sms_conversation_class.new(
+            number: params["Called"].presence || params["To"].presence,
+            from_number: params["From"].presence,
+            from_city: params["FromCity"].presence,
+            from_province: params["FromState"].presence,
+            from_country: params["FromCountry"].presence,
+          )
+          conversation.save!
+          conversation
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/sms/find_message_operation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module SMS
+      # Called by {Twilio::Rails::SMSController} with the Twilio params to find an existing SMS message.
+      class FindMessageOperation < ApplicationOperation
+        input :params, accepts: Hash, type: :keyword, required: true
+
+        def execute
+          ::Twilio::Rails.config.message_class.find_by!(sid: params["SmsSid"])
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/sms/find_operation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module SMS
+      # Called by {Twilio::Rails::SMSController} with the Twilio params to find an existing SMS conversation.
+      class FindOperation < ApplicationOperation
+        input :sms_conversation_id, accepts: Integer, type: :keyword, required: true
+
+        def execute
+          ::Twilio::Rails.config.sms_conversation_class.find(sms_conversation_id)
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/sms/send_operation.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module SMS
+      # Public entrypoint used to send an SMS message. This operation will create a new conversation to the phone caller
+      # and send a series of messages to them. The interaction will be stored in the database and sent via Twilio's API.
+      # The operation will raise if the {#from_number} is not a valid phone number.
+      #
+      # @example
+      #   Twilio::Rails::SMS::SendOperation.call(
+      #     phone_caller_id: a_phone_caller.id,
+      #     messages: ["Hello world!"],
+      #     from_number: "+1234567890"
+      #   )
+      #
+      # *Note:* Operations should be called with `call(params)` and not by calling `new(params).execute` directly.
+      class SendOperation < ApplicationOperation
+        input :phone_caller_id, accepts: Integer, type: :keyword, required: true
+        input :messages, accepts: Array, type: :keyword, required: true
+        input :from_number, accepts: [String, Twilio::Rails::PhoneNumber], type: :keyword, required: false
+
+        TWILIO_UNSUBSCRIBED_ERROR_CODES = [ 21610 ].freeze
+
+        # @param phone_caller_id [Integer] the id of the phone caller to send the message to.
+        # @param messages [Array<String>] the messages to send to the phone caller. It may be empty.
+        # @param from_number [String, Twilio::Rails::PhoneNumber] the phone number to send the message from. If the
+        # number is `nil` then it will attempt to extract the phone number from the last phone call. If that is not found
+        # then it will raise {Twilio::Rails::SMS::Error}.
+        # @return [Twilio::Rails::Models::SMSConversation] the SMS conversation that was created and sent.
+        def execute
+          return nil if messages.blank?
+          raise Twilio::Rails::SMS::Error, "from_number=#{ from_number } is not a valid phone number" if from_number.present? && !Twilio::Rails::Formatter.coerce_to_valid_phone_number(from_number)
+
+          conversation = ::Twilio::Rails.config.sms_conversation_class.new(
+            number: calculated_from_number,
+            from_number: calculated_to_number,
+            from_city: phone_call&.from_city,
+            from_province: phone_call&.from_province,
+            from_country: phone_call&.from_country,
+          )
+          conversation.save!
+
+          messages.each do |body|
+            sid = nil
+            begin
+              sid = Twilio::Rails::Client.send_message(
+                message: body,
+                to: calculated_to_number,
+                from: calculated_from_number,
+              )
+            rescue Twilio::REST::RestError => e
+              if TWILIO_UNSUBSCRIBED_ERROR_CODES.include?(e.code)
+                Twilio::Rails.config.logger.tagged(self.class) { |l| l.warn("tried to send to unsubscribed and got Twilio::REST::RestError code=21610 phone_caller_id=#{ phone_caller.id } phone_number=#{ calculated_to_number } message=#{ body }") }
+              else
+                Twilio::Rails.notify_exception(e,
+                  message: "Failed to send Twilio message. Got REST error response.",
+                  context: {
+                    to: calculated_to_number,
+                    from: calculated_from_number,
+                    phone_call_id: phone_call&.id,
+                  },
+                  exception_binding: binding
+                )
+                raise
+              end
+            end
+
+            message = conversation.messages.build(body: body, sid: sid, direction: "outbound")
+
+            message.save!
+          end
+
+          conversation
+        end
+
+        private
+
+        def phone_caller
+          @phone_caller ||= ::Twilio::Rails.config.phone_caller_class.find(phone_caller_id)
+        end
+
+        def phone_call
+          @phone_call ||= phone_caller.phone_calls.inbound.last
+        end
+
+        def calculated_from_number
+          if from_number.present?
+            Twilio::Rails::Formatter.coerce_to_valid_phone_number(from_number)
+          elsif phone_call
+            phone_call.number
+          else
+            raise Twilio::Rails::SMS::Error, "Cannot find a valid from_number to send from"
+          end
+        end
+
+        def calculated_to_number
+          phone_caller.phone_number
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/sms/twiml/base_operation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module SMS
+      module Twiml
+        class BaseOperation < Twilio::Rails::SMS::BaseOperation
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/sms/twiml/error_operation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module SMS
+      module Twiml
+        class ErrorOperation < ::Twilio::Rails::ApplicationOperation
+          def execute
+            twiml = Twilio::TwiML::MessagingResponse.new
+            twiml.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/sms/twiml/message_operation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module SMS
+      module Twiml
+        class MessageOperation < Twilio::Rails::SMS::Twiml::BaseOperation
+          input :params, accepts: Hash, type: :keyword, required: true
+
+          def execute
+            inbound_message = conversation.messages.build(
+              direction: "inbound",
+              body: params["Body"],
+              sid: params["SmsSid"].presence || params["MessageSid"].presence
+            )
+
+            inbound_message.save!
+
+            body = Twilio::Rails::SMS::Responder.new(inbound_message).respond
+
+            if body.present?
+              message = conversation.messages.build(
+                direction: "outbound",
+                body: body,
+              )
+
+              message.save!
+
+              twiml_response = Twilio::TwiML::MessagingResponse.new do |twiml|
+                twiml.message(
+                  body: body,
+                  action: ::Twilio::Rails::Engine.routes.url_helpers.sms_status_message_path(message_id: message.id)
+                )
+              end
+
+              Twilio::Rails.config.logger.info("message_twiml: #{twiml_response.to_s}")
+              twiml_response.to_s
+            else
+              Twilio::Rails.config.logger.info("resply is blank, not sending message in response")
+              Twilio::Rails.config.logger.info("message_twiml: #{twiml_response.to_s}")
+
+              twiml = Twilio::TwiML::MessagingResponse.new
+              twiml.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/sms/update_message_operation.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module SMS
+      # Called by {Twilio::Rails::SMSController} with the Twilio params to update an existing SMS message with any
+      # status changes or updates that Twilio sends. The save will only happen if there has been a change.
+      class UpdateMessageOperation < ApplicationOperation
+        input :params, accepts: Hash, type: :keyword, required: true
+        input :message_id, accepts: Integer, type: :keyword, required: true
+
+        def execute
+          message = ::Twilio::Rails.config.message_class.find(message_id)
+
+          if params["MessageStatus"].present?
+            message.status = params["MessageStatus"]
+          end
+
+          if message.changed?
+            message.save!
+          end
+
+          message
+        end
+      end
+    end
+  end
+end

data/app/views/layouts/twilio/rails/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Twilio rails</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag    "twilio/rails/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,16 @@
+# Implements all the routes that Twillio will call to manage the lifecycle of phone calls and SMS messages. See the
+# {README.md} for detailed instructions on how to configure the Twilio dashboard to call these routes.
+Twilio::Rails::Engine.routes.draw do
+  match "phone/receive_recording/:response_id", to: "phone#receive_response_recording", as: :phone_receive_recording, via: ::Twilio::Rails.config.controller_http_methods
+  match "phone/transcribe/:response_id", to: "phone#transcribe", as: :phone_transcribe, via: ::Twilio::Rails.config.controller_http_methods
+  match "phone/status", to: "phone#status", as: :phone_status, via: ::Twilio::Rails.config.controller_http_methods
+  match "phone/:tree_name/inbound", to: "phone#inbound", as: :phone_inbound, via: ::Twilio::Rails.config.controller_http_methods
+  match "phone/:tree_name/outbound", to: "phone#outbound", as: :phone_outbound, via: ::Twilio::Rails.config.controller_http_methods
+  match "phone/:tree_name/prompt/:response_id", to: "phone#prompt", as: :phone_prompt, via: ::Twilio::Rails.config.controller_http_methods
+  match "phone/:tree_name/prompt_response/:response_id", to: "phone#prompt_response", as: :phone_prompt_response, via: ::Twilio::Rails.config.controller_http_methods
+  match "phone/:tree_name/timeout/:response_id", to: "phone#timeout", as: :phone_timeout, via: ::Twilio::Rails.config.controller_http_methods
+
+  match "sms/message", to: "sms#message", as: :sms_message, via: ::Twilio::Rails.config.controller_http_methods
+  match "sms/status", to: "sms#status", as: :sms_status, via: ::Twilio::Rails.config.controller_http_methods
+  match "sms/status/:message_id", to: "sms#status", as: :sms_status_message, via: ::Twilio::Rails.config.controller_http_methods
+end

data/lib/generators/twilio/rails/install/USAGE

@@ -0,0 +1,15 @@
+Description:
+    Installs the initializer, routes, models, and migrations for `twilio-rails`.
+
+Example:
+    bin/rails generate twilio:rails:install
+
+    This will create:
+        config/initializers/twilio_rails.rb
+        db/migrate/install_twilio_rails.rb
+        app/models/message.rb
+        app/models/phone_caller.rb
+        app/models/phone_call.rb
+        app/models/recording.rb
+        app/models/response.rb
+        app/models/sms_conversation.rb

data/lib/generators/twilio/rails/install/install_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+class Twilio::Rails::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  include Rails::Generators::Migration
+
+  class << self
+    def next_migration_number(dirname)
+      next_migration_number = current_migration_number(dirname) + 1
+      ActiveRecord::Migration.next_migration_number(next_migration_number)
+    end
+  end
+
+  def setup_initializer
+    copy_file "initializer.rb", "config/initializers/twilio_rails.rb"
+  end
+
+  def setup_routes
+    route "mount Twilio::Rails::Engine => '/twilio'"
+  end
+
+  def setup_migrations
+    migration_template "migration.rb", "db/migrate/install_twilio_rails.rb"
+  end
+
+  def setup_models
+    copy_file "message.rb", "app/models/message.rb"
+    copy_file "phone_caller.rb", "app/models/phone_caller.rb"
+    copy_file "phone_call.rb", "app/models/phone_call.rb"
+    copy_file "recording.rb", "app/models/recording.rb"
+    copy_file "response.rb", "app/models/response.rb"
+    copy_file "sms_conversation.rb", "app/models/sms_conversation.rb"
+  end
+end

data/lib/generators/twilio/rails/install/templates/initializer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+Twilio::Rails.setup do |config|
+  # These are the Twilio account credentials used to access the Twilio API. These should likely be configured in the
+  # encrypted Rails credentials or loaded from an ENV variable.
+  config.account_sid = "TODO: account_sid"
+  config.auth_token = "TODO: auth_token"
+
+  # 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. This number
+  # should likely be configured in the encrypted Rails credentials or loaded from an ENV variable.
+  config.default_outgoing_phone_number = "TODO: +15556667777"
+
+  # All the following configuration options are optional and have reasonable defaults. Though if no phone trees or SMS
+  # responders are registered then the app will not be able to do much.
+
+  # Registry objects used to store and lookup phone trees and SMS responders. They must be registered here at setup time
+  # in order for the application to be able to use them. They can either be defined as strings that will be
+  # constantized, or as a block that will be evaluated after initialization. It is recommended to use the included
+  # generators to create new phone trees and SMS responders, which will add the lines here to register them.
+  #
+  # See the README documentation for more information on how to define and register phone trees and SMS responders.
+  # config.phone_trees.register { MyPhoneTree }
+  # config.sms_responders.register { MySMSResponder }
+
+  # This is the host that will be used to generate URLs that the Twilio API will use to make requests to the
+  # application. It defaults to what is defined in Rails `default_url_options` but can be overridden here. The format
+  # must be a protocol and domain, without the trailing slash, and no path.
+  # config.host = "https://example.com"
+
+  # 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)`.
+  # config.logger = Rails.logger
+
+  # 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.
+  # config.controller_http_methods = [:get, :post]
+
+  # 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.
+  # config.spam_filter = ->(params) {
+  #   [ "Bad text" ].any? { |regex| regex.match?(params["Body"]) }
+  # }
+
+  # 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.
+  # config.exception_notifier = ->(exception, message, context, exception_binding) {
+  #   MyChatClient.send_message("Error: #{ message } #{ exception.message } #{ context }")
+  # }
+
+  # 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. if reordings will be downloaded.
+  # config.attach_recordings = true
+
+  # A list of strings to be interpreted as yes or acceptance to a question, when the response is transcribed. Used in
+  # the phone macros. Defaults to a list of common responses.
+  # config.yes_responses = ["yes"]
+
+  # A list of strings to be interpreted as no or rejection to a question, when the response is transcribed. Used in
+  # the phone macros. Defaults to a list of common responses.
+  # config.no_responses = ["no"]
+
+  # 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.
+  # config.phone_caller_class_name = "PhoneCaller"
+  # config.phone_call_class_name = "PhoneCall"
+  # config.response_class_name = "Response"
+  # config.sms_conversation_class_name = "SMSConversation"
+  # config.message_class_name = "Message"
+  # config.recording_class_name = "Recording"
+
+  # 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 are defined in `Twilio::Rails::Phone::TreeMacros`.
+  # config.include_phone_macros MyMacrosModule
+end

data/lib/generators/twilio/rails/install/templates/message.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+class Message < ApplicationRecord
+  include Twilio::Rails::Models::Message
+end