Twilito

A tiny, zero dependency helper for sending text messages with Twilio. Just enough of a wrapper to abstract away Twilio's REST API for sending messages, without anything else.

Why

Twilio's full Ruby library does a lot, and has a large memory footprint to go with it—too large for just sending a message. It's also more difficult to mock and verify in tests than I'd like.

Using Twilio's REST API directly is fine, but can be cumbersome.

You should consider using Twilito if the only thing you need to do is send text messages and you don't want to worry about making HTTP requests to Twilio yourself.

If you use more of Twilio, consider twilio-ruby or interact with the REST API in another way.

Usage

Twilito is designed for currently maintained Ruby versions. (3.0 and up as of 8/2023). Unit tests run in CI on 3.0, 3.1, and 3.2

Install the gem

gem 'twilito'

Simplest case

# All of these arguments are required, but can be configured as defaults (see below)
result = Twilito.send_sms(
  to: '+15555555555',
  from: '+15554444444', # or 'messaging_service_sid'
  body: 'This is my content',
  account_sid: '...', # Twilio Credentials
  auth_token: '...'
)


# Returns instance of Twilito::Result

result.success? # => boolean
result.errors # => [] or error messages
result.sid #=> Twilio SID for Message (SM[...])
result.response # => Raw response (instance of Net::HTTPResponse)
result.data # => Hash of response data (parsed from JSON)

Use send_sms! to raise on error instead

begin
  Twilito.send_sms!(
    to: '+15555555555',
    from: '+12333',
    body: 'This is my content',
    account_sid: '...',
    auth_token: '...'
  )
rescue Twilito::SendError => e
  e.message # => 'Error from Twilio API'
  e.response # => Raw response (instance of Net::HTTPResponse)
end

Configuring Defaults For Required Arguments

The five required arguments (to, from (or messaging_service_sid), body, account_sid, and auth_token) can be configured as defaults with Twilito.configure.

# In an initializer or something like that:

Twilito.configure do |config|
  # Store your secrets elsewhere
  config.account_sid = ENV['TWILIO_ACCOUNT_SID']
  config.auth_token = ENV['TWILIO_AUTH_TOKEN']

  config.from = '+16145555555'
end

# Later, in your code:

Twilito.send_sms!(to: '+15555555555', body: 'Foo')

Using Other, Optional (Arbitrary) Arguments

There are a number of optional parameters defined by Twilio for sending a message (see the API documentation). Any of these can be sent with Twilito using the "Ruby-style" snake cased equivalent of the parameter.

# Twilito sends arbitrary arguments to Twilio's API after CamelCasing keys to match Twilio's style.
# NOTE: This example assumes auth_token, account_sid, and from have already been configured.

result = Twilito.send_sms(
  to: '+15555555555',
  body: 'This is my content',
  media_url: 'https://example.com/image.png', # MediaUrl
  status_callback: 'https://your.app.io/sms/callback', # StatusCallback
  smart_encoded: true # SmartEncoded
)

Testing your code

TODO: Add examples of mocking and/or test helpers for asserting your code sends an SMS

Contributing

Contribute Feedback, Ideas, and Bug Reports

Create or comment on an issue

Contribute Code

Find an open issue or create one
Fork this repo and open a PR
Write unit tests for your change

Contribute Docs

Open a PR to make the README better, or help with contribution guidelines, etc.
There is currently an open issue for adding RDoc/YARD documentation

Contribute Beer

Did Twilito save you some RAM?

twilito

Development