Make an Outbound Text-to-Speech Phone Call with Ruby on Rails

Published November 02, 2017 by Chris Guzman

This is the first article in a series of “Getting Started with Nexmo Voice APIs and Ruby on Rails” tutorials. It continues the “Getting Started with Nexmo SMS and Ruby on Rails” series.

With the help of the Nexmo Voice API you can make worldwide outbound and inbound calls in 23 languages with varieties of voices and accents. All you need is your virtual phone number, the Ruby Gem, and a few lines of code.

In this tutorial—and the ones to follow—I will take you through some real-life examples of how to integrate Nexmo into your Rails application. I’ll explain how to set up the basics, and then we will write some code together to properly integrate Nexmo and start making and receiving phone calls. Let’s get started!

View the source code on GitHub


For this tutorial I assume you will have:

  • A basic understanding of Ruby and Rails
  • Rails installed on your machine
  • NPM installed for the purpose of our CLI

Get your API keys

Before we can make our first API call you will need to sign up for a Nexmo account. After you’ve signed up you can head over to the Settings page to fetch your API credentials.

Nexmo Credentials

Buy a Nexmo number using the CLI

One of the easiest ways to purchase virtual phone numbers, set up applications, and configure them all is by using the Nexmo CLI tool. In this tutorial, we will use this as our main way of preparing our application.

The Nexmo CLI is a Node module and therefore does require NPM to have been installed.

With this in place, we can run the following commands to find and purchase a Voice-enabled number:

Alternatively, head over to the Numbers page on the Nexmo Dashboard and purchase a number via the web interface.

Create a Nexmo Application

In our previous series of SMS tutorials, we were able to configure a phone number directly with an endpoint. In this tutorial, we will be using the new, more powerful and more secure Nexmo Applications API for configuring our callbacks.

Make voice calls

Diagram: Using the Voice API to call your mobile phone

Our first step is to create an application by providing an application name and some callback URLs. Don’t worry about these URLs yet as we’ll be updating them later in a future tutorial.

This will create a Nexmo Application with UUID aaaaaaaa-bbbb-cccc-dddd-0123456789ab and a private key stored in a file called private.key. Make sure you don’t lose this key; Nexmo does not keep a copy and it’s used to sign your API calls.

Install the Nexmo Ruby Gem

The easiest way to interact with the Nexmo Voice API with Ruby is using the nexmo gem.

This gem conveniently provides an easy wrapper around the Nexmo REST API. To initialize it, we will need to pass it the Application UUID and private key that we created earlier. Create a file named make-call.rb with the following contents, replacing application_id with your application ID:

Make a voice call with Ruby

With our API client in place, making the first voice call is easy; we simply call the create_call method on the initialized client and pass in a configuration specifying who to call to, what number to call from, and an answer_url that will return a Nexmo Call Control Object (NCCO) containing the actions to play back to the receiver. To get us up and running quickly, we’ll provide a predefined NCCO URL that’s hosted on Github.

Add the following code to make-call.rb:

This will play back a simple voice message to the recipient as specified by first_call_talk.json. Run ruby make-call.rb now, and wait for a call from Nexmo that will read you a simple voice message.

There are a lot more parameters that we could pass into this method. Have a look at the reference documentation for full details.

Make an outbound call from Ruby on Rails

In a Rails application, we’d probably have a Model for Calls where we can store the to, from, and maybe the text to play to the recipient before making the Nexmo API call. For this example you could create a migration for a Call like so:

In my demo application, I’ve also whipped up a simple form for the Call model.


Make call form

When the form is submitted, we store the Call record and then make the call. In a real application, you might use a background queue for this, though in this case, we will just pass the Call record to a new method.

Next, we can pass the call information to the Nexmo API.

The response object will contain a uuid if the call was initiated successfully. We can store the uuid and the current call status on the Call record. The uuid can be used to track the status of the Call, specifically when a Call Update comes in via a webhook.

Provide an NCCO to play back text

When we called the create_call method we used outbound_call_url(call) in the answer_url array. That answer_url needs to be available to the public internet so that it is reachable by the Nexmo APIs. You can do so by using ngrok. For more detailed instructions see Aaron’s post explaining how to connect your local development server to the Nexmo API using an ngrok tunnel.

After setting up ngrok like so:

You will have an answer_url that looks something like this:

When the call is initiated, Nexmo will make an HTTP request to that endpoint expecting an NCCO object with the actions to perform. In our case, we want to simply play back the text we specified on the Call object.

Now go ahead, submit the form and within a few seconds you will receive a call playing back the message you just specified! There are many more actions you can specify in the NCCO. Have a play with them if you want.

Receive call

To sum things up

That’s it for this tutorial. We’ve successfully:

  1. Created a Nexmo account.
  2. Installed the CLI.
  3. Bought a number and created a Nexmo Application.
  4. Installed and initialized the Ruby gem.
  5. Created a deep integration into our Rails application.

You can view the code used in this tutorial on GitHub.

Next steps

In the next tutorials, we will look at receiving Call Events for calls we’ve created, and how to receive inbound calls as well.

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at