Simple gem for implementing texter classes which allow sending SMS messages in similar way to how e-mails are implemented and sent with ActionMailer-based mailers.
Unlike similar gems, textris has some unique features:
Textris::Base.deliveries
See the blog entry for the whole story and a practical usage example.
Add to Gemfile
:
gem 'textris'
Then run:
bundle install
Place texter classes in app/texters
(e.g. app/texters/user_texter.rb
):
class UserTexter < Textris::Base
default :from => "Our Team <+48 666-777-888>"
def welcome(user)
@user = user
text :to => @user.phone
end
end
Place relevant view templates in app/views/<texter_name>/<action_name>.text.*
(e.g. app/views/user_texter/welcome.text.erb
):
Welcome to our system, <%= @user.name %>!
Invoke them from application logic:
class User < ActiveRecord::Base
after_create do
UserTexter.welcome(self).deliver
end
end
Media messages are supported if you are using the Twilio, Log or Mail adapter. Twilio currently supports sending MMS in the US and Canada.
Media messages aren't part of a template, but must be specified as an array of URLs when sending the message, like:
class UserMediaTexter < Textris::Base
default :from => "Our Team <+48 666-777-888>"
def welcome(user)
@user = user
text(
:to => @user.phone,
:media_urls => ["http://example.com/hilarious.gif"]
)
end
end
As of version 0.4, textris supports native Rails 4.2+ way of background job handling, the ActiveJob. You can delay delivery of your texters the same way as with ActionMailer mailers, like:
UserTexter.welcome(user).deliver_later
UserTexter.welcome(user).deliver_later(:wait => 1.hour)
UserTexter.welcome(user).deliver_later(:wait_until => 1.day.from_now)
UserTexter.welcome(user).deliver_later(:queue => :custom_queue)
UserTexter.welcome(user).deliver_now
You can safely pass ActiveRecord records as delayed action arguments. ActiveJob uses GlobalID to serialize them for scheduled delivery.
By default, textris
queue will be used by the Textris::Delay::ActiveJob::Job job.
As of Rails 4.2, ActiveJob is the recommended way for background job handling and it does support Sidekiq as its backend, so please see chapter above if you're using Rails 4.2 or above. Otherwise, keep on reading to use textris with Sidekiq regardless of your Rails version.
Thanks to Sidekiq integration, you can send text messages in the background to speed things up, retry in case of failures or just to do it at specific time. To do so, use one of three delay methods:
UserTexter.delay.welcome(user)
UserTexter.delay_for(1.hour).welcome(user)
UserTexter.delay_until(1.day.from_now).welcome(user)
Remember not to call deliver
after the action invocation when using delay. It will be called by the Textris::Delay::Sidekiq::Worker worker.
You can safely pass ActiveRecord records and arrays as delayed action arguments. textris will store their
id
s and find them upon scheduled delivery.
Keep in mind that textris does not install sidekiq for you. If you don't have it yet, install Redis on your machine and add the sidekiq gem to Gemfile
:
gem 'sidekiq'
Then run:
bundle install
bundle exec sidekiq
Access all messages that were sent with the :test
delivery:
Textris::Base.deliveries
You may want to clear the delivery queue before each test:
before(:each) do
Textris::Base.deliveries.clear
end
Keep in mind that messages targeting multiple phone numbers, like:
text :to => ['48111222333', '48222333444']
will yield multiple message deliveries, each for specific phone number.
You can change default settings by placing them in any of environment files, like development.rb
or test.rb
, or setting them globally in application.rb
.
Below you'll find sample settings for any of supported delivery methods along with short description of each:
# Send messages via the Twilio REST API
config.textris_delivery_method = :twilio
# Send messages via the Nexmo API
config.textris_delivery_method = :nexmo
# Don't send anything, log messages into Rails logger
config.textris_delivery_method = :log
# Don't send anything, access your messages via Textris::Base.deliveries
config.textris_delivery_method = :test
# Send e-mails instead of SMSes in order to inspect their content
config.textris_delivery_method = :mail
# Chain multiple delivery methods (e.g. to have e-mail and log backups of messages)
config.textris_delivery_method = [:twilio, :mail, :log]
Unless otherwise configured, default delivery methods will be: log in
development
environment, test intest
environment and mail inproduction
environment. All these come with reasonable defaults and will work with no further configuration.
textris connects with the Twilio API using twilio-ruby gem. It does not, however, install the gem for you. If you don't have it yet, add the twilio-ruby gem to Gemfile
:
gem 'twilio-ruby'
Then, pre-configure the twilio-ruby settings by creating the config/initializers/twilio.rb
file:
Twilio.configure do |config|
config.account_sid = 'some_sid'
config.auth_token = 'some_auth_token'
end
To use Twilio's Copilot use twilio_messaging_service_sid
in place of from
when sending a text or setting defaults.
In order to use Nexmo with textris, you need to include the nexmo
gem in your Gemfile
:
gem 'nexmo', '~> 4'
The Nexmo gem uses the environment variables NEXMO_API_KEY
and NEXMO_API_SECRET
to authenticate with the API.
Therefore the safest way to provide authentication credentials is to set these variables in your application environment.
textris logger has similar logging behavior to ActionMailer. It will log single line to info log with production in mind and then a couple details to debug log. You can change the log level for the whole output:
config.textris_log_level = :info
Currently, textris comes with several delivery methods built-in, but you can easily implement your own. Place desired delivery class in app/deliveries/<name>_delivery.rb
(e.g. app/deliveries/my_provider_delivery.rb
):
class MyProviderDelivery < Textris::Delivery::Base
# Implement sending message to single phone number
def deliver(phone)
send_sms(:phone => phone, :text => message.content)
end
# ...or implement sending message to multiple phone numbers at once
def deliver_to_all
send_multiple_sms(:phone_array => message.to, :text => message.content)
end
end
Only one of methods above must be implemented for the delivery class to work. In case of multiple phone numbers and no implementation of deliver_to_all, the deliver method will be invoked multiple times.
You can place your custom deliveries in
app/texters
orapp/models
instead ofapp/deliveries
if you don't want to clutter the app directory too much.
After implementing your own deliveries, you can activate them by setting app configuration:
# Use your new delivery
config.textris_delivery_method = :my_provider
# Chain your new delivery with others, including stock ones
config.textris_delivery_method = [:my_provider, :twilio, :mail]
textris comes with reasonable defaults for the mail
delivery method. It will send messages to a Mailinator address specific to the application name, environment and target phone number. You can customize the mail delivery by setting appropriate templates presented below.
Arguably, the textris_mail_to_template setting is the most important here as it specifies the target e-mail address scheme.
# E-mail target, here: "app-name-test-48111222333-texts@mailinator.com"
config.textris_mail_to_template = '%{app:d}-%{env:d}-%{to_phone}-texts@mailinator.com'
# E-mail sender, here: "our-team-48666777888@test.app-name.com"
config.textris_mail_from_template = '%{from_name:d}-%{from_phone}@%{env:d}.%{app:d}.com'
# E-mail subject, here: "User texter: Welcome"
config.textris_mail_subject_template = '%{texter:dh} texter: %{action:h}'
# E-mail body, here: "Welcome to our system, Mr Jones!"
config.textris_mail_body_template = '%{content}'
You can use the following interpolations in your mail templates:
%{app}
: application name (e.g. AppName
)%{env}
: enviroment name (e.g. test
or production
)%{texter}
: texter name (e.g. User
)%{action}
: action name (e.g. welcome
)%{from_name}
: name of the sender (e.g. Our Team
)%{from_phone}
: phone number of the sender (e.g. 48666777888
)%{to_phone}
: phone number of the recipient (e.g. 48111222333
)%{content}
: message content (e.g. Welcome to our system, Mr Jones!
)%{media_urls}
: comma separated string of media URLs (e.g. http://example.com/hilarious.gif
)You can add optional interpolation modifiers using the %{variable:modifiers}
syntax. These are most useful for making names e-mail friendly. The following modifiers are available:
d
: dasherize (for instance, AppName
becomes app-name
)h
: humanize (for instance, user_name
becomes User name
)p
: format phone (for instance, 48111222333
becomes +48 111 222 333
)Here you can find a simple example project that demonstrates textris usage with Rails 4.2. In order to see how it works or experiment with it, just go to project's directory and invoke:
bundle install
rake db:migrate
rails server
Open application page and fill in some user information. Sample texter will be invoked and you'll see an output similar to following in your server log:
[ActiveJob] Enqueued Textris::Delay::ActiveJob::Job (Job ID: 71ed54f7-02e8-4205-9093-6f2a0ff7f483) to Inline(textris) with arguments: "UserTexter", "welcome", [#<User id: 1, name: "Mr Jones", phone: "48666777888", created_at: "2015-02-20 17:17:16", updated_at: "2015-02-20 17:17:16">]
[ActiveJob] User Load (0.3ms) SELECT "users".* FROM "users" WHERE "users"."id" = ? LIMIT 1 [["id", 1]]
[ActiveJob] [Textris::Delay::ActiveJob::Job] [71ed54f7-02e8-4205-9093-6f2a0ff7f483] Performing Textris::Delay::ActiveJob::Job from Inline(textris) with arguments: "UserTexter", "welcome", [#<User id: 1, name: "Mr Jones", phone: "48666777888", created_at: "2015-02-20 17:17:16", updated_at: "2015-02-20 17:17:16">]
[ActiveJob] [Textris::Delay::ActiveJob::Job] [71ed54f7-02e8-4205-9093-6f2a0ff7f483] Sent text to +48 666 777 888
[ActiveJob] [Textris::Delay::ActiveJob::Job] [71ed54f7-02e8-4205-9093-6f2a0ff7f483] Texter: User#welcome
[ActiveJob] [Textris::Delay::ActiveJob::Job] [71ed54f7-02e8-4205-9093-6f2a0ff7f483] Date: 2015-02-20 18:17:16 +0100
[ActiveJob] [Textris::Delay::ActiveJob::Job] [71ed54f7-02e8-4205-9093-6f2a0ff7f483] From: Our Team <+48 666 777 888>
[ActiveJob] [Textris::Delay::ActiveJob::Job] [71ed54f7-02e8-4205-9093-6f2a0ff7f483] To: +48 666 777 888
[ActiveJob] [Textris::Delay::ActiveJob::Job] [71ed54f7-02e8-4205-9093-6f2a0ff7f483] Rendered user_texter/welcome.text.erb (0.4ms)
[ActiveJob] [Textris::Delay::ActiveJob::Job] [71ed54f7-02e8-4205-9093-6f2a0ff7f483] Content: Welcome to our system, Mr Jones!
[ActiveJob] [Textris::Delay::ActiveJob::Job] [71ed54f7-02e8-4205-9093-6f2a0ff7f483] Performed Textris::Delay::ActiveJob::Job from Inline(textris) in 9.98ms
Example project may serve as a convenient sandbox for developing custom delivery methods.
git checkout -b my-new-feature
)git commit -am 'Add some feature'
)git push origin my-new-feature
)Implementing new delivery methods in Pull Requests is strongly encouraged. Start by implementing custom delivery method. Then, you can prepare it for a Pull Request by adhering to following guidelines:
lib/textris/delivery/service_name.rb
and named in a way that will best indicate the service with which it's supposed to work with.remove_const
to undefine loaded consts).COVERAGE=1 bundle exec rake spec
to generate simplecov coverage into the coverage/index.html file.The commit in which the log delivery was added is an example of delivery method addition that meets all guidelines listed above.