How to Handle Inbound Phone Calls with Ruby on Rails

Published December 21, 2017 by Chris Guzman

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

In the previous article, you learned how to set up a Rails application to be publicly accessible by Nexmo and then receive a Call Event Update for a call in progress. In this article, you will learn how to receive an inbound call by implementing a similar webhook endpoint in Ruby on Rails.

View the source code on GitHub.


To follow this tutorial, you need to have:

What Is an “Inbound Call”?

When someone calls the Nexmo number that was purchased in the first tutorial, it will be received by Nexmo. We will then make an HTTP call to the answer_url for the Nexmo Application associated with that number.

To receive this webhook, you will need to set up a webhook endpoint and tell Nexmo where to find it. For a refresher on how to set up ngrok for your application, read our post on connecting your local development server to the Nexmo API using an ngrok tunnel.

Set the Webhook Endpoint with Nexmo

The first step is to use the Nexmo CLI tool to link the Nexmo Application created in the previous tutorial to the purchased Nexmo number. We pass in the phone number and the application’s UUID.

This command tells Nexmo to make an HTTP call to the answer_url of the Nexmo Application every time the Nexmo Number receives an inbound call. We already set the answer_url in the first tutorial of this series, but if you need to update it you can do so as follows:

Handle an Incoming Call WebHook

The hard part is really done at this point. When a call comes in on your Nexmo number, Nexmo will notify your application by sending a webhook to the answer_url. A typical payload for this webhook will look something like this:

In this payload, the sending conversation is identified by the conversation_uuid parameter, and the from and to specify the caller and the Nexmo number called. Let’s add a new controller to process this payload and store a new call record.

Although storing and updating the call details is not really necessary, it’s useful to keep track of current call statuses, durations, and any other information that might benefit your application. This action returns a new Nexmo Call Control Object (NCCO) that will play back a simple voice message to the recipient as specified. There are many more actions you can specify in the NCCO—have a play with them if you want.

OK, now start your server, ensure you have something like ngrok running, and make a voice call to your Nexmo number! Can you hear Jennifer?

To Sum Things Up

That’s it for this tutorial. We’ve completed all the steps for receiving an inbound call in Ruby on Rails:

  1. set up our Rails application to receive an inbound voice call webhook
  2. informed Nexmo of where to find our server
  3. processed an incoming webhook
  4. provided instructions to Nexmo to play back a message

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

Next Steps

That’s it for this series on Ruby on Rails tutorials for now. As a reminder, you can see the source code for all of the SMS and Voice tutorials in our Ruby on Rails Quickstart repo.

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