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.
To follow this tutorial, you need to have:
- A basic understanding of Ruby and Rails
- Rails installed on your machine
- NPM installed for the purpose of our CLI
- Followed our previous tutorial on receiving call event updates with Ruby on Rails
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.
$ nexmo link:app 14155550102 aaaaaaaa-bbbb-cccc-dddd-0123456789ab
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:
$ nexmo app:update aaaaaaaa-bbbb-cccc-dddd-0123456789ab "My Voice App" http://abc123.ngrok.io/inbound_calls http://abc123.ngrok.io/call_events --answer_method POST --event_method POST
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
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.
resources :inbound_calls, only: [:create]
class InboundCallsController < ApplicationController
# We disable CSRF for this webhook call
render json: [
text: 'Hello, thank you for calling. This is Jennifer from Nexmo. Ciao.'
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:
- set up our Rails application to receive an inbound voice call webhook
- informed Nexmo of where to find our server
- processed an incoming webhook
- provided instructions to Nexmo to play back a message
You can view the code used in this tutorial on GitHub.
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.