Make Outbound Phone Calls with Ruby

In this guide, we'll show you how to use Programmable Voice to make outbound phone calls from your Ruby applications. You'll need the Twilio Ruby Helper Library, a voice-capable Twilio phone number, your account credentials, and five minutes. Let's get started!

(warning)

Warning

If you are sending SMS messages to the U.S. or Canada, before proceeding further, be aware of updated restrictions on the use of Toll-Free numbers for messaging, including TF numbers obtained by purchasing them. These restrictions do not apply to Voice or other uses outside of SMS messaging. See this support article for details.

In the Twilio console, search for and purchase an available phone number capable of making outbound calls. You'll use this phone number as the "From" phone number when you initiate an outbound call.

Make an outbound call

Now we're ready to make an outbound voice call using the Twilio Ruby gem.

Make an outbound call

1# Download the helper library from https://www.twilio.com/docs/ruby/install
2require 'rubygems'
3require 'twilio-ruby'
4
5# Find your Account SID and Auth Token at twilio.com/console
6# and set the environment variables. See http://twil.io/secure
7account_sid = ENV['TWILIO_ACCOUNT_SID']
8auth_token = ENV['TWILIO_AUTH_TOKEN']
9@client = Twilio::REST::Client.new(account_sid, auth_token)
10
11call = @client
12       .api
13       .v2010
14       .calls
15       .create(
16         twiml: '<Response><Say>Ahoy, World!</Say></Response>',
17         to: '+14155551212',
18         from: '+15017122661'
19       )
20
21puts call.sid

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "annotation": null,
4  "answered_by": null,
5  "api_version": "2010-04-01",
6  "caller_name": null,
7  "date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
8  "date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
9  "direction": "inbound",
10  "duration": "15",
11  "end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
12  "forwarded_from": "+141586753093",
13  "from": "+15017122661",
14  "from_formatted": "(415) 867-5308",
15  "group_sid": null,
16  "parent_call_sid": null,
17  "phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "price": "-0.03000",
19  "price_unit": "USD",
20  "sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21  "start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
22  "status": "completed",
23  "subresource_uris": {
24    "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
25    "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
26    "payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
27    "events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
28    "siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
29    "streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
30    "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
31    "user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
32    "user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
33  },
34  "to": "+14155551212",
35  "to_formatted": "(415) 867-5309",
36  "trunk_sid": null,
37  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
38  "queue_time": "1000"
39}

There are a few key parameters to drill into when making the outbound call.

From - the voice-enabled Twilio phone number you added to your account earlier
To - the person you'd like to call
TwiML - Instructions in the form TwiML that explains what should happen when the other party picks up the phone
Url - Optionally, instead of passing the TwiML parameter, you can provide a URL that returns TwiML Voice instructions.

What is TwiML?

TwiML is the Twilio Markup Language, which is just to say that it's an XML document with special tags defined by Twilio to help you build your SMS and voice applications. TwiML is easier shown than explained. Here's some TwiML you might use to respond to an incoming phone call:

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Say>Thanks for calling!</Say>
4</Response>

And here's some TwiML you might use to respond to an incoming SMS message:

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Message>We got your message, thank you!</Message>
4</Response>

Every TwiML document will have the root <Response> element and within that can contain one or more verbs. Verbs are actions you'd like Twilio to take, such as <Say> a greeting to a caller, or send an SMS <Message> in reply to an incoming message. For a full reference on everything you can do with TwiML, refer to our TwiML API Reference.

Make an outbound call with hosted TwiML

1# Download the helper library from https://www.twilio.com/docs/ruby/install
2require 'rubygems'
3require 'twilio-ruby'
4
5# Find your Account SID and Auth Token at twilio.com/console
6# and set the environment variables. See http://twil.io/secure
7account_sid = ENV['TWILIO_ACCOUNT_SID']
8auth_token = ENV['TWILIO_AUTH_TOKEN']
9@client = Twilio::REST::Client.new(account_sid, auth_token)
10
11call = @client
12       .api
13       .v2010
14       .calls
15       .create(
16         url: 'http://demo.twilio.com/docs/classic.mp3',
17         to: '+14155551212',
18         from: '+14155551212'
19       )
20
21puts call.sid

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "annotation": null,
4  "answered_by": null,
5  "api_version": "2010-04-01",
6  "caller_name": null,
7  "date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
8  "date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
9  "direction": "inbound",
10  "duration": "15",
11  "end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
12  "forwarded_from": "+141586753093",
13  "from": "+14155551212",
14  "from_formatted": "(415) 867-5308",
15  "group_sid": null,
16  "parent_call_sid": null,
17  "phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "price": "-0.03000",
19  "price_unit": "USD",
20  "sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21  "start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
22  "status": "completed",
23  "subresource_uris": {
24    "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
25    "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
26    "payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
27    "events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
28    "siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
29    "streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
30    "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
31    "user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
32    "user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
33  },
34  "to": "+14155551212",
35  "to_formatted": "(415) 867-5309",
36  "trunk_sid": null,
37  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
38  "queue_time": "1000"
39}

The TwiML used to make the outbound call

This XML document uses the <Say> and the <Play> TwiML tags to read a message and play an MP3 file for the user.

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Say voice="Polly.Amy">Thanks for trying our documentation. Enjoy!</Say>
4  <Play>https://demo.twilio.com/docs/classic.mp3</Play>
5</Response>

Of course, the TwiML you use to make the outbound call doesn't need to be a static file like in this example. Server-side code that you control can dynamically render TwiML to use for the outbound call. Check out our inbound call guide to see an example of a Ruby app which generates TwiML.

Where to next?

Great work! In a few lines of code, you've placed an outbound phone call from your Ruby code. If you're using Programmable Voice with Ruby, you might enjoy these other guides as well.

Happy hacking!