Cellular

Sending and receiving SMSs with Ruby through pluggable backends.

Supported Ruby versions: 2.0.0 or higher

Licensed under the MIT license, see LICENSE for more information.

Installation

Add this line to your application's Gemfile:

gem 'cellular'

And then execute:

bundle

Or install it yourself as:

gem install cellular

Usage

Configuration

Cellular.configure do |config|
  config.username = 'username'
  config.password = 'password'
  config.backend = Cellular::Backends::Sendega
  config.sender = 'Default custom sender'
  config.country_code = 'NO'
end

Cellular uses Rails' ActiveJob interface to interact with queue backends. Read appropriate documentation to set up queue.

Available Backends

Cellular::Backends::CoolSMS
Cellular::Backends::Sendega
Cellular::Backends::Twilio
Cellular::Backends::LinkMobility
Log (logs to $stdout)
Test (adds messages to Cellular.deliveries)

Sending SMSs

The options supported may differ between backends.

sms = Cellular::SMS.new(
  recipient: '+47xxxxxxxx', # Valid international format
  sender: '+370xxxxxxxx',
  message: 'This is an SMS message',
  price: 0,
  country_code: 'NO' # defaults to Cellular.config.country_code
)

sms.deliver

For use with multiple recipients in one request use:

sms = Cellular::SMS.new(
  recipients: ['+47xxxxxxx1','+47xxxxxxx2','+47xxxxxxx3'],
  sender: '+370xxxxxxxx',
  message: 'This is an SMS message',
  price: 0,
  country_code: 'NO' # defaults to Cellular.config.country_code
)

sms.deliver

Delayed SMSs delivery

You can also send texts asynchronously, which is great if you're in a Rails app and are concerned that it might time out or something. To use it, just call deliver_async instead of deliver on the SMS object:

sms = Cellular::SMS.new(
  recipient: '+47xxxxxxxx',
  sender: '+47xxxxxxxx',
  message: 'This is an SMS message'
)

sms.deliver_async

This will create a delayed job for you on the cellular queue, so make sure that your queue processor is running.

To override queue name, use queue option

sms.deliver_async(queue: :urgent)

Using ActiveJob, Cellular allows you to schedule the time when an SMS will be sent. Just call deliver_async(wait_until: timestamp) or deliver_async(wait: time) on the SMS object:

sms = Cellular::SMS.new(
  recipient: '+47xxxxxxxx',
  sender: '+47xxxxxxxx',
  message: 'This is an SMS message'
)

sms.deliver_async(wait_until: Date.tomorrow.noon)

Troubleshooting

If you are using Twilio as a backend, please make sure you add or port a phone number to your account, so that you can use that as a sender option. You won't be able to send messages from any phone number unless you port it to Twilio.

Also, make sure phone numbers are in valid international format: [+47xxxxxxxx, +370xxxxx]

Contributing

Fork it
Create your feature branch (git checkout -b feature/my-new-feature)
Write your code and necessary tests
Run your tests (bundle exec rspec)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin feature/my-new-feature)
Create pull request and be awesome!

Credits

Hyper made this. We're a digital communications agency with a passion for good code, and if you're using this library we probably want to hire you.

hyperoslo / cellular

readme