We've built this example using Ruby 3.0.0 and Ruby on Rails 6.1.4.1, and the Vonage Voice API.
Have you ever dialed a company and been prompted to follow along with menu prompts? If you have then you have interacted with an Interactive Voice Response (IVR). The IVR acts on input provided by the caller, usually in the form of numeric keypad choices. You can build your own IVR using Ruby on Rails and the Vonage Voice API.
In this walkthrough, we will build a small Rails application that will host a simple IVR service. After we are done, you can expand on this application to build whatever you need. In this tutorial, our application will accept a numeric input (also called a DTMF code) from the caller, and then speak back the input entered to the caller.
Prerequisites
You will need the following to follow along in this tutorial:
ngrok so Vonage can access the service running locally on your machine
DT API Account
To complete this tutorial, you will need a DT API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the DT API Dashboard.
Getting Started
Create a Rails Application
The first thing we need to do is to create a new Rails application. You can do so on your command line with the following:
The above command will create our Rails app in /vonage-rails-ivr-demo
, and will also skip installing a database. In this tutorial we will not be persisting our data, so we do not need it.
Change directories into the vonage-rails-ivr-demo
folder and run bundle install
from the command line. While Vonage has a robust Ruby SDK gem, and a Rails initializer gem, we do not need to install either for this application.
Create an IVR Controller
Now that our application has been created our next step is to create the Controller that will respond to two routes with Nexmo Call Control Objects (NCCO). The first route will answer the call and request the caller to press a number on their keypad. The second route will speak back the number the caller entered.
To create our Controller run the following from the command line:
Once that has completed, open up the application in your preferred code editor and let's edit the newly generated /app/controllers/ivr_controller.rb
. We are going to add methods for our two routes now. First, let's create the #answer
method that will pick up the call:
# ivr_controller.rb
class IvrController < ApplicationController
skip_before_action :verify_authenticity_token
BASE_URL = ''
def answer
render json:
[
{
action: 'talk',
text: 'Welcome! This is the Vonage Ruby on Rails IVR Demo Application. Please enter a number on your keypad, followed by the hash key.',
language: "en-US",
style: 9
},
{
action: 'input',
submitOnHash: true,
eventUrl: ["#{BASE_URL}/event"]
}
].to_json
end
end
As shown above, the #answer
method provides two NCCO instructions. The first is the talk
action, wherein the caller is greeted by the application. I chose the United States locale and style number 9. The Voice API provides a robust selection of language and style options, see more in the text-to-speech guide. Note: the previous voiceName parameter is now deprecated. Read more.
The second action is the input
action, and we have set the optional parameter submitOnHash
to true
so that the input ends when the user presses the hash key on their phone. We also provide the required eventUrl
parameter with a URL that points to our other route that will respond to the user input.
Lastly, we see that the #answer
method uses a constant variable called BASE_URL
that is currently defined as an empty string. Later in this walkthrough, we will fill that in with our ngrok externally accessible URL.
Now, let's add our second and final Controller action, #event
. This will act upon the caller input by speaking back to the caller their number choice:
# ivr_controller.rb
def event
number = params['dtmf']
render json:
[
{
action: 'talk',
text: "You entered #{number}. Thank you for trying the Vonage Ruby on Rails IVR Demo Application!",
language: "en-US",
style: 9
}
].to_json
end
All together our Controller will look like this:
# ivr_controller.rb
class IvrController < ApplicationController
skip_before_action :verify_authenticity_token
BASE_URL = ''
def answer
render json:
[
{
action: 'talk',
text: 'Welcome! This is the Vonage Ruby on Rails IVR Demo Application. Please enter a number on your keypad, followed by the hash key.',
language: "en-US",
style: 9
},
{
action: 'input',
submitOnHash: true,
eventUrl: ["#{BASE_URL}/event"]
}
].to_json
end
def event
number = params['dtmf']
render json:
[
{
action: 'talk',
text: "You entered #{number}. Thank you for trying the Vonage Ruby on Rails IVR Demo Application!",
language: "en-US",
style: 9
}
].to_json
end
end
Define Routes
The next step we need to do is to define our routes. We do that by editing the /config/routes.rb
file and adding the two URL paths corresponding to our two Controller actions:
# routes.rb
Rails.application.routes.draw do
get '/answer', to: 'ivr#answer'
post '/event', to: 'ivr#event'
end
Configure ngrok
Starting with Rails 6, you must give your ngrok tunnel URL permission to access your development environment. The NGROK_URL will be replaced by your actual ngrok URL in the following step. Add the following to your development.rb
file.
Note: You must restart your rails server after editing development.rb
for changes to take effect.
#development.rb
config.hosts << "NGROK_URL.ngrok.io"
At this point, our Rails application is ready to run. Now let's set up our ngrok externally accessible URL. We will need that for the final step, which is creating our Vonage application and our Vonage provisioned phone number.
Connect to the Outside World
Set Up ngrok
There are several ways to make our local development server externally accessible, but one of the simplest ways is with ngrok. You can read this article for a more detailed explanation of how ngrok works.
However, for our purposes, we just need to get it running and copy the URL that it provides us.
In order to start ngrok, open up a new terminal window and execute the following from the command line:
You will now see a ngrok logging interface in your terminal window. Near the top of the interface is a line that begins with Forwarding
and contains two URLs. The first is the externally accessible ngrok URL, which ends with ngrok.io
followed by http://localhost:3000
, that being your local development server. Now, when you or Vonage contacts the ngrok.io
URL, it will forward it to your local server.
Now would be a good time to go back to the ivr_controller.rb
and replace the empty string with your ngrok URL for the BASE_URL
constant. You should also replace your ngrok URL for NGROK_URL in the development.rb
file. We will also be using it in our next step of setting up our Vonage account, phone number, and Voice application.
Get Connected with Vonage
Set Up a Vonage Account
In order for our voice application to work, we need a Vonage account, a Vonage provisioned phone number, a Vonage application, and, lastly, we need to link our application to our phone number.
You can create a Vonage account for free, and as an added bonus, your account will be credited with 2 euros to begin using your new application. Visit the Vonage API Developer Dashboard and follow the sign-up steps if you do not already have a Vonage API Developer account. Once you complete sign-up, you will see your Vonage API Developer Dashboard.
From the left-hand menu, click on the Voice menu
item. You will see the following options:
Click on the Getting started
option and you will be directed to a page where you can test the text-to-speech functionality or set up a new Vonage application. Find the following Create an application
form:
Complete the form with the following:
Application name
text field entervonage-rails-ivr-demo
Once you have finished, go ahead and click the Create Application
button.
After the application has been created you can generate a public/private key pair. We will not be using them for this tutorial, but it is good to know where they are in case you choose to expand upon this application with more functionality.
You now have created a Vonage Voice application. Our next step is to purchase a Vonage phone number and link it to this application. Click on the Configure application
As seen below:
This will redirect you to the settings page for your application. In the second half of the page, you can link your application to Vonage provisioned phone numbers. Click on the Buy numbers
button and you will be directed to a page where you can choose a country, features, type, and four digits you would like the number to have.
For our purposes: pick the country that you are currently in so that the call will be a local call for you; pick Voice
for features and either mobile or landline for type. You do not need to enter anything for the Number
text field. When you click Search
, you will see a list of phone numbers available.
Pick one by clicking the Buy
button, and click the black Buy
button once more in the confirmation prompt.
Once you own the number, you can now link it to your vonage-rails-ivr-demo
Voice application. To do so, click on the Your applications
option from the left-hand panel. Navigate back to your application page. Now you will see your newly purchased phone number listed in the second half of the page, as seen below:
Simply click the white link
button. The button will turn red and change to unlink.
Your Vonage phone number is now linked to your application. Our last step is to configure the Vonage application to accept phone calls and send them to the IVR Rails app. Click the edit
button in the top section, under your application's name. You will be redirected to a page called Edit vonage-rails-ivr-demo.
Scroll until you find the following Capabilities section:
Complete the form with the following:
Answer URL
text field enter your ngrok URL again:https://[ngrok url here]/answer
Event URL
text field enter your ngrok URL:https://[ngrok url here]/event
Scroll to the bottom of the page and click the save-changes
button.
With that last step, you have finished! You now have a fully functional simple IVR Rails application powered by Vonage. You can give it a go by starting your Rails server, and with ngrok also running, give your application a call at the phone number you just purchased.
Further Reading
To continue learning about what we discussed consider exploring the following:
Ben is a second career developer who previously spent a decade in the fields of adult education, community organizing and non-profit management. He worked as a developer advocate for Vonage. He writes regularly on the intersection of community development and tech. Originally from Southern California and a long time resident of New York City, Ben now resides near Tel Aviv, Israel.