Gem of the Week: twilio-ruby

September 9, 2016 Jamey Alea 0 Comments

Ever had an app that needs to communicate with people in more ways than just shooting them an email? How about an app that can send text alerts or even make or receive phone calls? Enter Twilio. Similar to my recent spotlight on Stripe, Twilio isn’t just a standalone gem, but rather a useful service that also has a convenient gem to make it even easier to integrate that service into your app. Integrating with hardware can feel daunting but actually Twilio was one of the first gems I learned to use as a brand new Rails developer and I was pleasantly surprised by how simple it is to use!

To start working with Twilio in the app once you’ve installed the gem (which is called twilio-ruby), you’ll need a client. How do you get one? First you’ll need a Twilio account in order to get access to your account SID and auth token. When you sign in, both of those values are presented to you right at the top of your console dashboard (although your auth token will be censored and you’ll have to click through to see it). Now that you have those, you can create a client!

client = Twilio::REST::Client.new TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN

You can also configure your app to know those values like this:

Twilio.configure do |config|
  config.account_sid = TWILIO_ACCOUNT_SID
  config.auth_token = TWILIO_AUTH_TOKEN
end

Then you can create a client without passing them in as params, like this:

client = Twilio::REST::Client.new

(As you can see by my excessive use of capital letters, I’ve already saved my account SID and auth token as app constants. As I mentioned in the Stripe article, it’s safer to save them as environment variables and then set the app constants by referencing the environment variables.)

Okay, there’s one more thing you need – a phone number. Part of the Twilio service is you can purchase a phone number from them for your dedicated use. In your console dashboard, go to the “#” symbol in the left sidebar and then choose “Buy a Number.” You can specify the area code and capabilities that you want and then it’ll present you with a list of numbers to choose from, which cost a dollar or two a month.

If you’re not into using the console, or you need to programmatically requisition new numbers within your code, you can use your client to buy numbers too.

numbers = client.available_phone_numbers.get('US').local.list(
  contains: ‘716’
)
number = numbers[0].phone_number
client.incoming_phone_numbers.create(phone_number: number)

This will get you an array of local US phone numbers containing your specification and then grab the first one and associate it with your account.

So now you have a client and a phone number. What can you do now?

Send a text message like this:

client.messages.create(
  from: TWILIO_ACCOUNT_NUMBER,
  to: “+15551234567”,
  body: “You have just received a text message via Twilio!”
)

The from number here has to be a Twilio number that you’ve purchased. In this example, I’m assuming that I only have one and I’ve saved it in app constants, but you can have as many different Twilio numbers as you see fit.

You can also make and receive actual phone calls, although you’ll need a URL that has TwiML instructions for how the call should be handled. Yep, Twilio has it’s own markup language. But don’t worry, it’s easy to get started with. Here’s a sample .xml file that we can use as the URL callback to make a call.

<Response>
    <Say voice="woman">You have just received a call from my Twilio number</Say>
</Response>

Using the gem, you can also generate this TwiML with Ruby code. This call will output the exact same TwiML as shown above:

response = Twilio::TwiML::Response.new do |r|
  r.Say 'You have just received a call from my Twilio number', voice: ‘woman’
end

Then, we can make the call like this, where URL points to the sample file laid out above.

call = client.calls.create(
  from: TWILIO_ACCOUNT_NUMBER,
  to: '+15551234567,
  url: 'http://your-app.com/call-handler-twiml-file'
)

This will call the specified “to” number and they will hear a (slightly robotic) woman’s voice read them the message that you wrote in your TwiML instructions.

You can also set a TwiML file URL as your callback for when your Twilio number receives a call. If you go to the phone numbers section of your console dashboard and “manage numbers,” you’ll see there is a configuration for a Voice URL and a Messaging URL. If you put the same test file from above as the Voice URL here, a user will hear that same message when they call your Twilio number, rather than when they receive a call from it.

Using TwiML, you can also redirect the current caller to another phone using the command. This has a lot of really powerful applications, but here is the simplest:

<Dial callerId="+18005555555">
    <Number>+15551234567</Number>
</Dial>

This will attempt to connect the current call with the number 555-123-4567 and they will see 1-800-555-5555 as the number on their caller ID. If you put multiple tags inside the tag it will attempt to connect with all of them simultaneously and then hang up with the rest once the first one answers. You can also set a timeout, a time limit, if you want to record the call, as well as have a callback URL that gets hit afterwards.

We’ve only gone over the most basic Twilio capabilities, although being able to programmatically send text messages is one of the easiest and most useful features of the service. But if you want to do more, there is a whole world of Twilio and TwiML to explore, as it’s a very powerful tool, and luckily their documentation is quite good! They have docs and tutorials here or you can start here if you mainly want to learn Twilio Markup Language. Documentation specific to the gem can be found here.