README.markdown in twilio_contactable-0.8.4 vs README.markdown in twilio_contactable-0.8.5

- old
+ new

@@ -1,45 +1,51 @@ Twilio Contactable ===== -Twilio makes voice and SMS interactions easy. But if you want to be able to seamlessly validate your user's phone numbers for -both voice and text there's a lot of work you'll have to do in your Rails app. Unless you use this gem. +Twilio makes voice and SMS interactions easy. But if you want to ensure that your user's phone numbers really belong +to them there's a lot of buggy code you'll have to add in your Ruby app. Unless you use this gem. Don't Write Twilio Ruby Code Like It's PHP == -You don't want to be passing strings around and writing procedural code in your Ruby app. This gem lets you ask for a phone number from your users (or any ActiveRecord model), confirm their ownership of it via SMS or Voice or both, and keep track of whether the number is still validated whenever the number is edited. +You don't want to be passing strings around between multiple web requests and writing procedural code in your Ruby app. Not for such a simple feature. This gem lets you ask for a phone number from your users (or any ActiveRecord-like Ruby class), confirm their ownership of it via SMS or Voice (or both), and automatically handle number invalidation. Install It == Install TwilioContactable as a gem: - gem install twilio_contactable - # then add this gem to your project in .gems or in environment.rb + $ gem install twilio_contactable + + # For Rails add it in environment.rb: + config.gem 'twilio_contactable' + # then edit your .gems file or run + $ rake gems:unpack + # to unpack the gem into your vendor/gems directory + Or as a Plugin: ruby script/plugin install git://github.com/JackDanger/twilio_contactable.git Connect This Code To Your App == -Include Twilio::Contactable into your User class or whatever you're using to represent an entity with a phone number. +Include Twilio::Contactable into your User class or whatever you're using to represent an entity with a contactable phone number. class User < ActiveRecord::Base include TwilioContactable::Contactable twilio_contactable end -If you're using custom column names you can easily overwrite any of them: +If you're using custom column names you can easily overwrite any of them by passing in a configuration block: class User < ActiveRecord::Base include TwilioContactable::Contactable @@ -75,12 +81,12 @@ t.string :voice_confirmation_code t.datetime :voice_confirmation_attempted t.string :voice_confirmed_phone_number end -You don't necessarily need all those columns though. Say you have users that are notified by SMS but business locations that -just need to have their retail phone number validated: +You don't necessarily need all those columns though. Say you have users that want to use SMS and business locations that +just need to have their retail phone number to confirm their identity: change_table :users do |t| t.string :phone_number t.string :formatted_phone_number t.boolean :sms_blocked, :default => false, :null => false @@ -97,25 +103,27 @@ t.string :voice_confirmed_phone_number end Both the User and the BusinessLocation models are now prepared for SMS and Voice confirmation, respectively. -You'll also need to create a controller that is capable of receiving connections from Twilio.com: +You'll also need to create a controller that is capable of receiving connections from Twilio.com. You can reuse an existing controller or +create a new one just for this task. TwilioContactable will guess the path from the controller name, so if you include it into a class called CheckPhoneNumbersController: - # app/controllers/twilio_contactable_controller.rb - class TwilioContactableController < ActionController::Base + # app/controllers/check_phone_numbers_controller.rb + class CheckPhoneNumbersController < ActionController::Base include TwilioContactable::Controller # any models that you want to have phone numbers confirmed for: twilio_contactable User, BusinessLocation end +then Twilio.com would try to contact your site at '/check_phone_numbers'. As long as that route works then you don't need to configure anything else. -Configure It With Twilio Account Info +Configure It With Your Twilio Account Info == -Because it can be expensive to send TXTs or make calls accidentally, it's required that you manually configure TwilioContactable in your app. Put this line in config/environments/production.rb or anything that loads _only_ in your production environment: +Because it can be expensive to send TXTs or make calls accidentally, it's required that you manually set TwilioContactable.mode in your app. Put this line in config/environments/production.rb or anything that loads _only_ in your production environment: TwilioContactable.mode = :live Skipping this step (or adding any other value) will prevent TXTs or phone calls from actually being sent. @@ -201,15 +209,12 @@ http://myrubyapp.com/twilio_contactable/receive_sms_message This gem will handle all those incoming messages automatically. Now if your users reply to an SMS with 'STOP' or 'BLOCK' the appropriate record in your database will be updated so that sms messages no longer can be sent to them (i.e.: @user.sms_blocked? will be true) -All other incoming TXTs (besides 'BLOCK' and 'STOP') from a user will automatically be sent to that user's record: +All other incoming TXTs (besides 'BLOCK' and 'STOP') from a user will automatically be sent to that user's record. If "I love you!" is sent to you from a user with the phone number "555-111-9999" then the following will be executed: - # If "I love you!" is sent to you from a user with - # the phone number "555-111-9999" - # then the following will be executed: - User.find_by_formatted_phone_number('+15551119999').receive_sms("I love you!") + User.find_by_formatted_phone_number('+15551119999').receive_sms("I love you!") It's up to you to implement the 'receive_sms' method on User. That's it. Patches welcome, forks celebrated.