How to Use Twilio for Voice and SMS Capabilities in Ruby
This guide demonstrates how to perform common programming tasks with the Twilio API service on Windows Azure. The scenarios covered include making a phone call and sending a Short Message Service (SMS) message. For more information on Twilio and using voice and SMS in your applications, see the Next Steps section.
Table of Contents
What is Twilio?
Twilio is a telephony web-service API that lets you use your existing web languages and skills to build voice and SMS applications. Twilio is a third-party service (not a Windows Azure feature and not a Microsoft product).
Twilio Voice allows your applications to make and receive phone calls. Twilio SMS allows your applications to make and receive SMS messages. Twilio Client allows your applications to enable voice communication using existing Internet connections, including mobile connections.
Twilio Pricing and Special Offers
Information about Twilio pricing is available at Twilio Pricing. Windows Azure customers receive a special offer: a free credit of 1000 texts or 1000 inbound minutes. To sign up for this offer or get more information, please visit http://ahoy.twilio.com/azure.
The Twilio API is a RESTful API that provides voice and SMS functionality for applications. Client libraries are available in multiple languages; for a list, see Twilio API Libraries.
TwiML is a set of XML-based instructions that inform Twilio of how to process a call or SMS.
As an example, the following TwiML would convert the text Hello World to speech.
<?xml version="1.0" encoding="UTF-8" ?>
All TwiML documents have
<Response> as their root element. From there, you use Twilio Verbs to define the behavior of your application.
Twilio Verbs are XML tags that tell Twilio what to do. For example, the <Say> verb instructs Twilio to audibly deliver a message on a call.
The following is a list of Twilio verbs.
- <Dial>: Connects the caller to another phone.
- <Gather>: Collects numeric digits entered on the telephone keypad.
- <Hangup>: Ends a call.
- <Play>: Plays an audio file.
- <Pause>: Waits silently for a specified number of seconds.
- <Record>: Records the caller's voice and returns a URL of a file that contains the recording.
- <Redirect>: Transfers control of a call or SMS to the TwiML at a different URL.
- <Reject>: Rejects an incoming call to your Twilio number without billing you
- <Say>: Converts text to speech that is made on a call.
- <Sms>: Sends an SMS message.
For more information about Twilio verbs, their attributes, and TwiML, see TwiML. For additional information about the Twilio API, see Twilio API.
Create a Twilio Account
When you're ready to get a Twilio account, sign up at Try Twilio. You can start with a free account, and upgrade your account later.
When you sign up for a Twilio account, you'll get a free phone number for your application. You'll also receive an account SID and an auth token. Both will be needed to make Twilio API calls. To prevent unauthorized access to your account, keep your authentication token secure. Your account SID and auth token are viewable at the Twilio account page, in the fields labeled ACCOUNT SID and AUTH TOKEN, respectively.
Verify Phone Numbers
In addition to the number you are given by Twilio, you can also verify numbers that you control (i.e. your cell phone or home phone number) for use in your applications.
For information on how to verify a phone number, see Manage Numbers.
Create a Ruby Application
A Ruby application that uses the Twilio service and is running in Windows Azure is no different than any other Ruby application that uses the Twilio service. While Twilio services are RESTful and can be called from Ruby in several ways, this article will focus on how to use Twilio services with Twilio helper library for Ruby.
First, set-up a new Windows Azure Linux VM to act as a host for your new Ruby web application. Ignore the steps involving the creation of a Rails app, just set-up the VM. Make sure you create an Endpoint with an external port of 80 and an internal port of 5000.
In the examples below, we will be using Sinatra, a very simple web framework for Ruby. But you can certainly use the Twilio helper library for Ruby with any other web framework, including Ruby on Rails.
SSH into your new VM and create a directory for your new app. Inside that directory, create a file called Gemfile and copy the following code into it:
On the command line run
bundle install. This will install the dependecies above. Next create a file called
web.rb. This will be where the code for your web app lives. Paste the following code into it:
get '/' do
At this point you should be able the run the command
ruby web.rb -p 5000. This will spin-up a small web server on port 5000. You should be able to browse to this app in your browser by visiting the URL you set-up for your Windows Azure VM. Once you can reach your web app in the browser, you're ready to start building a Twilio app.
Configure Your Application to Use Twilio
You can configure your web app to use the Twilio library by updating your
Gemfile to include this line:
On the command line, run
bundle install. Now open
web.rb and including this line at the top:
You're now all set to use the Twilio helper library for Ruby in your web app.
How to: Make an outgoing call
The following shows how to make an outgoing call. Key concepts include using the Twilio helper library for Ruby to make REST API calls and rendering TwiML. Substitute your values for the From and To phone numbers, and ensure that you verify the From phone number for your Twilio account prior to running the code.
Add this function to
# Set your account ID and authentication token.
sid = "your_twilio_account_sid";
token = "your_twilio_authentication_token";
# The number of the phone initiating the the call.
# This should either be a Twilio number or a number that you've verified
from = "NNNNNNNNNNN";
# The number of the phone receiving call.
to = "NNNNNNNNNNN";
# Use the Twilio-provided site for the TwiML response.
url = "http://yourdomain.cloudapp.net/voice_url";
get '/make_call' do
# Create the call client.
client = Twilio::REST::Client.create(sid, token);
# Make the call
client.account.calls.create(to: to, from: from, url: url)
post '/voice_url' do
If you open-up
http://yourdomain.cloudapp.net/make_call in a browser, that will trigger the call to the Twilio API to make the phone call. The first two parameters in
client.account.calls.create are fairly self-explanatory: the number the call is
from and the number the call is
The third parameter (
url) is the URL that Twilio requests to get instructions on what to do once the call is connected. In this case we set-up a URL (
http://yourdomain.cloudapp.net) that returns a simple TwiML document and uses the
<Say> verb to do some text-to-speech and say "Hello Monkey" to the person recieving the call.
How to: Recieve an SMS message
In the previous example we initiated an outgoing phone call. This time, let's use the phone number that Twilio gave us during sign-up to process an incoming SMS message.
First, log-in to your Twilio dashboard. Click on "Numbers" in the top nav and then click on the Twilio number you were provided. You'll see two URLs that you can configure. A Voice Request URL and an SMS Request URL. These are the URLs that Twilio calls whenever a phone call is made or an SMS is sent to your number. The URLs are also known as "web hooks".
We would like to process incoming SMS messages, so let's update the URL to
http://yourdomain.cloudapp.net/sms_url. Go ahead and click Save Changes at the bottom of the page. Now, back in
web.rb let's program our application to handle this:
post '/sms_url' do
<Sms>Hey, thanks for the ping! Twilio and Azure rock!</Sms>
After making the change, make sure to re-start your web app. Now, take out your phone and send an SMS to your Twilio number. You should promptly get an SMS response that says "Hey, thanks for the ping! Twilio and Azure rock!".
How to: Use Additional Twilio Services
In addition to the examples shown here, Twilio offers web-based APIs that you can use to leverage additional Twilio functionality from your Windows Azure application. For full details, see the Twilio API documentation.
Now that you've learned the basics of the Twilio service, follow these links to learn more: