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.
Prerequisites
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.
|
1 2 |
$ nexmo link:app 14155550102 aaaaaaaa-bbbb-cccc-dddd-0123456789ab Number updated |
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:
|
1 2 |
$ 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 Application updated |
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:
|
1 2 3 4 5 6 |
{ "from": "14155550104", "to": "14155550102", "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab", } |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
# config/routes.rb Rails.application.routes.draw do resources :inbound_calls, only: [:create] end # app/controllers/inbound_calls_controller.rb class InboundCallsController < ApplicationController # We disable CSRF for this webhook call skip_before_action :verify_authenticity_token def create Call.where(conversation_uuid: params[:conversation_uuid]) .first_or_create .update_attributes( to: params[:to], from: params[:from] ) render json: [ { action: 'talk', voiceName: 'Jennifer', text: 'Hello, thank you for calling. This is Jennifer from Nexmo. Ciao.' } ] end end |
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.
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.
Developer
