dballona / actionmessage

ActionMailer-like gem for sending SMS/Text Messages

ActionMessage

ActionMessage is heavily-inspired on ActionMailer. It's a gem for sending SMS/Text messages like we do for sending e-mails on ActionMailer. Pull requests are more than welcome!

Setup

Install it using bundler:

# Gemfile
gem 'actionmessage'

If you're using Rails, place this on your environment file or application.rb

require 'action_message/railtie'

config.action_message = {
  # sender in international format you can also pass an array and it will
  # shuffle and randomly pick one number.
  from: "[phone]",

  # adapter information. Right now we only support Twilio.
  adapter: { 
    name: :twilio,
    credentials: {
      account_sid: 'MY TWILIO ACCOUNT SID'.freeze,
      auth_token: 'MY AUTH TOKEN'.freeze
    }
  }
}

Usage

In order to generate your message class, you can either place this code under app/messages/welcome_message.rb or just use our generators by running the following command: rails g message Welcome send_welcome_sms

class WelcomeMessage < ActionMessage::Base
  def send_welcome_sms(name, phone_number_to_send_message)
    @name = name
    sms(to: phone_number_to_send_message)
  end

  # Inline body example, body parameter has preference compared
  # to a text.erb template.
  def welcome_with_inline_body(name, phone_number_to_send_message)
    @name = name
    sms(to: phone_number_to_send_message, body: 'Inline body!')
  end

  # While on development environment, you can use debug: true to
  # prevent sending SMS and spending funds on your Twilio account.
  def welcome_with_debug_mode(name, phone_number_to_send_message)
    @name = name
    sms(to: phone_number_to_send_message, debug: true)
  end
end

Define your views under your view path, such as: app/views/welcome_message/send_welcome_sms.text.erb

Welcome, <%= @name %>!

And to send is really simple!

name = 'John Doe'
phone = '[phone]'

# To send right away:
WelcomeMessage.send_welcome_sms(name, phone).deliver_now

# To send through a background job
WelcomeMessage.send_welcome_sms(name, phone).deliver_later

Interceptors

In order to prevent sending messages to a specific number or containing any specific text on it's body you can use Interceptors:

# You can use strings (exact comparison)
ActionMessage::Interceptor.register(to: 'number I want to prevent sending messages')

# Regular expressions
ActionMessage::Interceptor.register(body: /something innapropriate/i)

# Pass Multiple arguments on the same call
ActionMessage::Interceptor.register(to: '[phone]', body: /anything/i)

actionmessage's Issues

Add engine for receiving hooks from the adapters

Do you not find most of the work associated with twilio etc are setting up state machines and database layers for the sms/call states? In my experience the "send" portion of the work is very small compared to the data tracking and for twilio for instance setting up hooks to either get the delivery status or polling to do so.

I think it for sure deserves probably an engine to be mounted at routes, and persisting it out (even for interceptions for invalid numbers, as you suggested). that’s actually a huge feature, and VERY nice to have.

probably, something like

# on routes.rb
mount ActionMessage::Statistics => '/sms'

This engine would define two routes, one for hooks for the adapters to post messages into (such as Twilio). and the other one for statistics (more on that the statistics part on another github issue);

we’d probably have a module to include on the tracker model under the app for Mongoid, and a generator for SQL databases (generates both migration and model);

and on the hook action, we’d record every single interaction out the adapters send for us under that model. Would be basically plug and play.

Add ability for creating interceptors

It's important to have a way to block to send to some numbers because of legal issues, and also, per user request.

Add option to render[:body] instead of using a template

We should support sms(to: number, body: "Hardcoded message").
Need to add test cases for this under base_spec and usage_spec.

Statistics screen for the engine

As described on #13

# on routes.rb
mount ActionMessage::Statistics => '/sms'

This engine would define two routes, one for hooks for the adapters to post messages into (such as Twilio). and the other one for statistics;

we’d probably have a module to include on the tracker model under the app for Mongoid, and a generator for SQL databases (generates both migration and model);

and on the statistics action, we’d show statistics that are common between adapters, such as delivery status, amount sent by date, amount received.

Basically consists on building something next to Sidekiq::Web engine on this interface.

Test Helpers (delivery counts, etc)

Add Railtie for easier rails configuration

Background processing (deliver_later)

Log instrumentation and logger handling

Improve tests quality

Add more ruby versions on CI

Think about adding more ruby versions:

• More CRuby versions
• JRuby
• Rubinius

I can help with something like that

Add Plivo as an adapter

https://www.plivo.com/docs/api/message/

Add ability to override body instead of using templates.

Basically allow render text: "whatever I'd like to"

Formatting errors per adapter

Some adapters may accept different characters as the phone to receive message.

We should create error specializations (or maybe just log errors?) for each one of the Adapter classes, with correct messages if something goes wrong, e.g.:

Twilio:
21211: Invalid 'To' Phone Number
21401: Invalid Phone Number
21407: This Phone Number type does not support SMS
21614: 'To' number is not a valid mobile number

Create Generators

Add Amazon SNS as an adapter (?)

http://docs.aws.amazon.com/sns/latest/dg/mobile-push-send-directmobile.html
Seems like it's possible? need some research on that...