by Scott Schecter

Twilio Ruby App


About Twilio

Creating a Twilio Ruby app is a great way to begin harnessing the power of Twilio for all of your organization’s programmable voice and SMS needs. Twilio is a cloud communications platform that brings programmable communications to the masses. Using Twilio you can embed messaging, voice, video, and authentication in your apps with a simple and powerful API. A few examples of how one might use Twilio and more importantly what the benefits are to your organization:

  • To provide two-factor authentication functionality to an app with SMS verification numbers – This increases the security of your app.
  • To provide automated appointment notices for your business – This allows your organization to reduce no-shows with text or voice reminders.
  • To provide masked phone numbers – This provides increased privacy protection for your employees who communicate with the public on their mobile device of choice on behalf of your organization.
  • To provide analytics for call tracking – This allows you to measure calls to ad campaigns and listings providing your organization with more accurate business intelligence information.
  • To provide instant lead alerts – This allows your organization to expedite sales responses for new inquiries and reach your customers more rapidly than was previously possible.
  • To provide click-to-call functionality to an app – Using click-to-call technologies you can cut hold times for your customers to zero.

These are just a few of the many uses and benefits of integrating Twilio with your telephony stack. Now that have seen why one would want to use Twilio let us turn to how one would use Twilio. Before creating a new Twilio Ruby app yourself or using the one I will provide with this post you will first need to sign up for an account with Twilio. Twilio offers free trial accounts for developers. You can find more information on how the free trial works as well as a link to sign up here.

Building The Twilio Ruby App

To build our Twilio Ruby app we will be using Sinatra. Sinatra is a DSL for quickly creating web applications in Ruby with minimal effort. Before beginning any software project one should clearly define the requirements of said software project and what success looks like. The requirements for this app are:

  1. Receiving A Call – Our Twilio Ruby app should receive calls to a Twilio number and forward those calls to the number provided.
  2. Making A Call – Our Twilio Ruby app should provide an interface to make calls from a Twilio number to any phone number provided.
  3. Receiving A SMS Message – Our Twilio Ruby app should receive SMS messages sent to a Twilio number and forward those SMS messages to the number provided.
  4. Sending A SMS Message – Our Twilio Ruby app should provide an interface to send SMS messages from a Twilio number to any phone number provided.
  5. Basic HTTP Authentication – Our Twilio Ruby app should provide basic http authentication to prevent anyone unexpected from using the app.

Now that we know what functionality our Twilio Ruby app should have let’s get started building it.

1. Receiving A Call

Setting up call forwarding is the one requirement on our list you can achieve without hosting a Webhook on a server of your own. If you want to see how this is done, or want to provide redundancy to your phone number using this method please see here. We will be proving our own Webhook to forward calls in our app as well. Here is what the Ruby code looks like to forward a call using Twilio:

What is actually happening here is when Twilio performs a HTTP POST to the ‘/call/receive’ route our application is listening for that route and then renders some pre-defined XML to let Twilio know how to route the incoming call. The XML format is defined by TwiML the Twilio Markup Language. You can find more information on TwiML here. The actual XML rendered in this case would be:

2. Making A Call

We have just seen how to forward received calls to a Twilio phone number. Now let us see how to make calls from a Twilio phone number. The first thing we will need to do is create a HTML form to input your desired number to call. An example of this markup would be:

For the purposes of this app it is assumed the user will provide a valid phone number and knows to format all numbers in E.164 format as this is how Twilio expects them. If you were creating an app that took input from untrusted users you would want to use Phony to validate and format the provided phone number. The HTML form above will perform a HTTP POST to the ‘/call/make’ route. Now we will look at how we handle that post:

Above we are grabbing the ‘To’ parameter value from the form and passing it to the Twilio REST client. We also provide the from phone number which is our Twilio number and a URL which provides Twilio the instructions needed on how to route the call. This is the route we created previously in the receiving calls section. We have now covered how to receive and make programmable voice calls. This only begins to scratch the surface of what is capable with Twilio programmable voice services. However, this Twilio Ruby app should have enough functionality to be useful out of the box for the majority of users. We will now turn our attention to the SMS portion of the requirements we defined earlier.

3. Receiving A SMS Message

Just like we setup a Webhook previously to handle receiving programmable voice calls from Twilio we will also now setup a Webhook to handle receiving SMS messages. This time however, since we receive data from Twilio, we need to accept a HTTP POST instead of a HTTP GET. Our route to receive SMS messages looks like this:

What is happening here is when Twilio performs a HTTP POST to the ‘/sms/receive’ route our Twilio Ruby app is listening for that route. It then forwards the received SMS message from our Twilio phone number to the number we provided with the original ‘From’, ‘To’, and ‘Body’ parameter values in the forwarded message body.

4. Sending A SMS Message

To send a SMS message we will once again need to create a HTML form to input our desired data into. An example of this markup would be:

The HTML form above will perform a HTTP POST to the route ‘/sms/send’. Now we will look at how we handle that post:

Above we are grabbing the ‘To’ and the ‘Body’ parameter values from the form and passing them to the Twilio REST client. We also provide the from phone number which is once again our Twilio phone number.

5. Basic HTTP Authentication

At this point we have covered all of our required Twilio related functionality. Now we need to make sure only trusted users and Twilio can access it. We will do this by providing basic HTTP authentication to our Twilio Ruby app. This means in order to access any part of our application the request will need to provide the application with a username and password which we will then authenticate like so:

Above we are pulling the username and password we provide from our Twilio Ruby app’s settings and comparing them to those the user provides to ensure they match. If they match Rack authenticates the user. If they do not match Rack does not authenticate the user. All of the settings for this app can be updated in the included config.yml file.

Wrapping It Up

We have now satisfied the defined requirements of our Twilio Ruby app. This Twilio Ruby app is fully optimized for use on all of your mobile devices. It will look great on your desktop, from your tablet, or from your phone. Be sure to try it on all of your devices. There is also, one piece of additional configuration information you will need to use the app. You will need to ensure your Twilio phone number’s Webhooks are pointing at the routes we just created and that Twilio can access them. Your configuration should be in the form of:

Voice:

  • Webhook
  • https://yourusername:yourpassword@yourdomain.com/call/receive
  • HTTP POST

Messaging:

  • Webhook
  • https://yourusername:yourpassword@yourdomain.com/sms/receive
  • HTTP POST

I am also providing an image to help you configure the correct values.

Twilio Ruby App

Configure your Twilio phone number’s settings for your Twilio Ruby app

You can configure these values by editing your Twilio phone number settings in the Twilio console. The full source code for this Twilio Ruby app is attached to this post. To run this Twilio Ruby app unzip the files provided and then execute the command ‘bundle install’ in the root folder of the Twilio Ruby app to install the required dependencies. You will need the bundler gem installed for this operation. After you have installed the required dependencies with bundler execute ‘bundle exec rackup’. The site will then be running at localhost:9292. One final reminder, to actually use this Twilio Ruby app you must host it somewhere that routes are accessible to Twilio. I hope you find this Twilio Ruby app useful. If you are looking for a talented developer to assist you with the creation of a custom Twilio Ruby app for your organization drop us a line.


Leave a Comment

Your email address will not be published. Required fields are marked *