twilio-rails 1.0.0

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

@@ -0,0 +1,89 @@
+class InstallTwilioRails < ActiveRecord::Migration[7.0]
+  def change
+    create_table "messages", force: :cascade do |t|
+      t.bigint "sms_conversation_id", null: false
+      t.string "sid"
+      t.text "body"
+      t.string "status"
+      t.string "direction"
+      t.datetime "created_at", null: false
+      t.datetime "updated_at", null: false
+      t.index ["created_at"], name: "index_messages_on_created_at"
+      t.index ["direction"], name: "index_messages_on_direction"
+      t.index ["sms_conversation_id"], name: "index_messages_on_sms_conversation_id"
+    end
+
+    create_table "phone_callers", force: :cascade do |t|
+      t.string "phone_number"
+      t.datetime "created_at", null: false
+      t.datetime "updated_at", null: false
+      t.index ["phone_number"], name: "index_phone_callers_on_phone_number"
+    end
+
+    create_table "phone_calls", force: :cascade do |t|
+      t.integer "phone_caller_id"
+      t.string "sid"
+      t.string "number"
+      t.string "from_number"
+      t.string "from_city"
+      t.string "from_province"
+      t.string "from_country"
+      t.string "tree_name"
+      t.string "direction"
+      t.string "answered_by"
+      t.boolean "unanswered", default: false
+      t.boolean "finished", default: false
+      t.string "call_status"
+      t.integer "length_seconds"
+      t.datetime "created_at", null: false
+      t.datetime "updated_at", null: false
+      t.index ["created_at"], name: "index_phone_calls_on_created_at"
+      t.index ["direction"], name: "index_phone_calls_on_direction"
+      t.index ["phone_caller_id"], name: "index_phone_calls_on_phone_caller_id"
+      t.index ["sid"], name: "index_calls_on_sid"
+      t.index ["tree_name"], name: "index_phone_calls_on_tree_name"
+    end
+
+    create_table "recordings", force: :cascade do |t|
+      t.bigint "phone_call_id", null: false
+      t.string "recording_sid"
+      t.string "duration"
+      t.string "url"
+      t.datetime "created_at", null: false
+      t.datetime "updated_at", null: false
+      t.index ["phone_call_id"], name: "index_recordings_on_call_id"
+    end
+
+    create_table "responses", force: :cascade do |t|
+      t.bigint "phone_call_id"
+      t.bigint "recording_id"
+      t.string "prompt_handle"
+      t.string "digits"
+      t.text "transcription"
+      t.boolean "transcribed", default: false
+      t.boolean "timeout", default: false
+      t.datetime "created_at", null: false
+      t.datetime "updated_at", null: false
+      t.index ["created_at"], name: "index_responses_on_created_at"
+      t.index ["digits"], name: "index_responses_on_digits"
+      t.index ["phone_call_id", "prompt_handle"], name: "index_responses_on_phone_call_id_and_prompt_handle"
+      t.index ["prompt_handle"], name: "index_responses_on_prompt_handle"
+      t.index ["recording_id"], name: "index_responses_on_recording_id"
+      t.index ["timeout"], name: "index_responses_on_timeout"
+      t.index ["transcribed"], name: "index_responses_on_transcribed"
+    end
+
+    create_table "sms_conversations", force: :cascade do |t|
+      t.string "number"
+      t.string "from_number"
+      t.string "from_city"
+      t.string "from_province"
+      t.string "from_country"
+      t.datetime "created_at", null: false
+      t.datetime "updated_at", null: false
+      t.index ["created_at"], name: "index_sms_conversations_on_created_at"
+      t.index ["from_number"], name: "index_sms_conversations_on_from_number"
+      t.index ["number"], name: "index_sms_conversations_on_number"
+    end
+  end
+end

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

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

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

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

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

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

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

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

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

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

data/lib/generators/twilio/rails/phone_tree/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generates a new phone tree and registers it.
+
+Example:
+    bin/rails generate twilio:rails:phone_tree SomeExample
+
+    This will create:
+        app/phone_trees/some_example_tree.rb

data/lib/generators/twilio/rails/phone_tree/phone_tree_generator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+class Twilio::Rails::PhoneTreeGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+
+  def copy_template_tree
+    template "tree.rb.erb", "app/phone_trees/#{file_name}_tree.rb"
+  end
+
+  def register_tree
+    insert_into_file "config/initializers/twilio_rails.rb", "\n  config.phone_trees.register { #{class_name}Tree }", before: "\nend\n"
+  end
+end

data/lib/generators/twilio/rails/phone_tree/templates/tree.rb.erb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+class <%= class_name %>Tree < Twilio::Rails::Phone::BaseTree
+  # voice "male"
+  # final_timeout_message("Goodbye.")
+  # invalid_phone_number("Sorry, we cannot accept your call.")
+
+  greeting message: "Hello!",
+    prompt: :thanks_and_hangup
+
+  prompt :thanks_and_hangup,
+    message: "Thank you for calling!",
+    after: { hangup: true }
+end

data/lib/generators/twilio/rails/sms_responder/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generates a new SMS responder and registers it.
+
+Example:
+    bin/rails generate twilio:rails:sms_responder SomeExample
+
+    This will create:
+        app/sms_responders/some_example_responder.rb

data/lib/generators/twilio/rails/sms_responder/sms_responder_generator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+class Twilio::Rails::SmsResponderGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+
+  def copy_template_responder
+    template "responder.rb.erb", "app/sms_responders/#{file_name}_responder.rb"
+  end
+
+  def register_responder
+    insert_into_file "config/initializers/twilio_rails.rb", "\n  config.sms_responders.register { #{class_name}Responder }", before: "\nend\n"
+  end
+end

data/lib/generators/twilio/rails/sms_responder/templates/responder.rb.erb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+class <%= class_name %>Responder < Twilio::Rails::SMS::DelegatedResponder
+  def handle?
+    raise NotImplementedError, "Implement #{ self.class }#handle?"
+  end
+
+  def reply
+    raise NotImplementedError, "Implement #{ self.class }#reply"
+  end
+end

data/lib/tasks/rails_tasks.rake

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+namespace :twilio do
+  namespace :rails do
+    desc "Show the available values to config in Twilio"
+    task config: :environment do
+      if Twilio::Rails.config.host.blank?
+        puts "Twilio::Rails.config.host is not set. Set it in the `config/initializers/twilio_rails.rb` file."
+      elsif Twilio::Rails.config.host == "https://example.com"
+        puts "Twilio::Rails.config.host is set to a test value. Set it in the `config/initializers/twilio_rails.rb` file."
+      else
+        http_methods = if Twilio::Rails.config.controller_http_methods.length == 1
+          "HTTP #{ Twilio::Rails.config.controller_http_methods.first.to_s.upcase }"
+        else
+          "HTTP POST or HTTP GET"
+        end
+
+        puts "Log into the Twilio web console: https://console.twilio.com"
+        puts "Navigate to Phone Numbers -> Manage -> Active Numbers and find the phone number #{Twilio::Rails.config.default_outgoing_phone_number}."
+        puts ""
+
+        if Twilio::Rails.config.phone_trees.all.length == 0
+          puts "You cannot yet configure `Voice & Fax' because There are no phone trees registered in this application."
+          puts "Register them in the `config/initializers/twilio_rails.rb` file if you want to handle phone calls, and run this task again to help configure Twilio."
+        else
+          puts "Under 'Voice & Fax' set 'A CALL COMES IN' to 'Webhook' with #{ http_methods } and one of the following URLs:"
+          Twilio::Rails.config.phone_trees.all.each do |name, tree|
+            puts "  #{tree.inbound_url}"
+          end
+          puts ""
+          puts "Under 'Voice & Fax' set 'CALL STATUS CHANGES' to following URL:"
+          puts "  #{ ::Twilio::Rails.config.host }#{ ::Twilio::Rails::Engine.routes.url_helpers.phone_status_path(format: :xml) }"
+        end
+
+        puts ""
+        puts "Under 'Messaging' set 'A MESSAGE COMES IN' to 'Webhook' with #{ http_methods } and the following URL:"
+        puts "  #{ ::Twilio::Rails.config.host }#{ ::Twilio::Rails::Engine.routes.url_helpers.sms_message_path(format: :xml) }"
+
+        if Twilio::Rails.config.sms_responders.all.length == 0
+          puts "There are no SMS responders registered so they will not be handled."
+          puts "Register them in the `config/initializers/twilio_rails.rb` file if you want to handle SMS messages."
+        end
+      end
+    end
+  end
+end

data/lib/twilio/rails/client.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    # An abstraction over top of the `Twilio::REST` API client. Used to send SMS messages and start calls, as well as
+    # return an initialized client if needed.
+    module Client
+      extend self
+
+      # @return [Twilio::REST::Client] Twilio client initialized with `account_sid` and `auth_token` from the config.
+      def client
+        @twilio_client ||= Twilio::REST::Client.new(
+          Twilio::Rails.config.account_sid,
+          Twilio::Rails.config.auth_token,
+        )
+      end
+
+      # Do not call this directly, instead see {Twilio::Rails::SMS::SendOperation}. Send an SMS message to and from the
+      # given phone numbers using the Twilio REST API directly. This does not store or manage any interactions in the
+      # database.
+      #
+      # @param message [String] the message to send.
+      # @param to [String] the phone number to send the message to.
+      # @param from [String] the phone number to send the message from.
+      # @return [String] the SID returned from Twilio for the sent SMS message.
+      def send_message(message:, to:, from:)
+        Twilio::Rails.config.logger.tagged(self) { |l| l.info("[send_message] to=#{ to } from=#{ from } body='#{ message }'") }
+        client.messages.create(
+          from: from,
+          to: to,
+          body: message,
+          status_callback: "#{ Twilio::Rails.config.host }#{ ::Twilio::Rails::Engine.routes.url_helpers.sms_status_path(format: :xml) }",
+        ).sid
+      end
+
+      # Do not call this directly, instead see {Twilio::Rails::SMS::SendOperation}. Sends multiple SMS messages to and
+      # from the given phone numbers using the Twilio REST API directly. This does not store or manage any interactions
+      # in the database. If a message is blank it will be ignored.
+      #
+      # @param messages [Array<String>] the messages to send.
+      # @param to [String] the phone number to send the messages to.
+      # @param from [String] the phone number to send the messages from.
+      # @return [Array<String>] the SIDs returned from Twilio for the sent SMS messages.
+      def send_messages(messages:, to:, from:)
+        Twilio::Rails.config.logger.tagged(self) { |l| l.info("[send_messages] to blank messages") } if messages.blank?
+        messages.map { |m| send_message(message: m, to: to, from: from) }
+      end
+
+      # Do not call this directly, instead see {Twilio::Rails::Phone::StartCallOperation}. Starts a phone call to and
+      # from the given phone numbers using the Twilio REST API directly. This does not store or manage any interactions
+      # in the database. The URL should come from the {Twilio::Rails::Phone::Tree} that is being used to start the call.
+      #
+      # @param url [String] the URL to use for the Twilio REST API call, probably from the {Twilio::Rails::Phone::Tree}.
+      # @param to [String] the phone number to make the call to.
+      # @param from [String] the phone number to make the call from.
+      # @param answering_machine_detection [true, false] whether or not to enable answering machine detection.
+      # @return [String] the SID returned from Twilio for the started call.
+      def start_call(url:, to:, from:, answering_machine_detection: true)
+        Twilio::Rails.config.logger.tagged(self) { |l| l.info("[start_call] to=#{ to } from=#{ from } url=#{ url } answering_machine_detection=#{ !!answering_machine_detection }") }
+        client.calls.create(
+          from: from,
+          to: to,
+          url: url,
+          machine_detection: ( answering_machine_detection ? "Enable" : "Disable" ),
+          async_amd: true,
+          async_amd_status_callback: "#{ Twilio::Rails.config.host }#{ ::Twilio::Rails::Engine.routes.url_helpers.phone_status_path(format: :xml, async_amd: "true") }",
+          async_amd_status_callback_method: "POST",
+          status_callback: "#{ Twilio::Rails.config.host }#{ ::Twilio::Rails::Engine.routes.url_helpers.phone_status_path(format: :xml) }",
+          status_callback_method: "POST",
+          status_callback_event: ["completed", "no-answer"],
+          # timeout: 30,
+        ).sid
+      end
+    end
+  end
+end

data/lib/twilio/rails/concerns/has_direction.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    # Provides scopes, validations, and convenience methods for a model that has an attribute `direction` with
+    # values "inbound" or "outbound".
+    module HasDirection
+      extend ActiveSupport::Concern
+
+      included do
+        validates :direction, inclusion: { in: ["outbound", "inbound"] }
+
+        scope :outbound, -> { where(direction: "outbound") }
+        scope :inbound, -> { where(direction: "inbound") }
+      end
+
+      def inbound?
+        direction == "inbound"
+      end
+
+      def outbound?
+        direction == "outbound"
+      end
+    end
+  end
+end

data/lib/twilio/rails/concerns/has_phone_number.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    # Provides validations and reformatting on validation for a model that has an attribute `phone_number` that is
+    # that is unique and that matches {Twilio::Rails::Formatter.coerce_to_valid_phone_number}.
+    module HasPhoneNumber
+      extend ActiveSupport::Concern
+
+      included do
+        validates :phone_number, uniqueness: { allow_blank: true, message: "already exists" }
+
+        before_validation :reformat_phone_number
+      end
+
+      def reformat_phone_number
+        current = Twilio::Rails::Formatter.coerce_to_valid_phone_number(phone_number)
+        self.phone_number = current if current
+
+        true
+      end
+
+      def valid_north_american_phone_number?
+        Twilio::Rails::Formatter.valid_north_american_phone_number?(phone_number)
+      end
+    end
+  end
+end

data/lib/twilio/rails/concerns/has_time_scopes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    # Provides convenience scopes for a model that has a `created_at` attribute.
+    module HasTimeScopes
+      extend ActiveSupport::Concern
+
+      included do
+        scope :in_last, ->(time) { where(created_at: (Time.now - time)..(Time.now)) }
+        scope :in_previous, ->(time) { where(created_at: (Time.now - time - time)..(Time.now - time)) }
+
+        scope :in_last_24_hours, -> { in_last(1.day) }
+        scope :in_last_2_days, -> { in_last(2.days) }
+        scope :in_last_4_hours, -> { in_last(4.hours) }
+        scope :in_previous_24_hours, -> { in_previous(1.day) }
+      end
+    end
+  end
+end