Local Numbers for Voice Calls

While toll-free numbers can be expensive, they're also one of the least personal ways to provide a customer with a way to reach you. So with that in mind, we're going to replace your expensive toll-free number with multiple localized regional numbers. This will allow you to give your customers a friendly local number to dial while saving you on expensive toll-free number rental costs.

Additionally, with the power of local numbers, we will show you how you can take some smart steps to provide a more bespoke experience for anyone dialled in, while simultaneously collecting valuable information about your customers' ever-changing requirements.

In this guide you will be creating an application for an imaginary transit authority, allowing users to dial in with a local number, instantly getting an update on their local transit system, and additionally allowing them to get an update on other cities if desired.

Prerequisites

In order to work through this guide you'll need:

• A Vonage account
• The Vonage CLI installed and set up
• A publicly accessible web server so that Vonage can make webhook requests to your app. You can learn more about webhooks in our webhooks guide and it includes information on using ngrok to expose your local webserver
• Some knowledge of Ruby and the Sinatra web framework

Getting Started

We'll start by registering two Vonage numbers to use with this application. We need two so that we can demonstrate the use of different numbers linking to different locations. Follow the instructions for getting started with applications. This will walk you through buying a number, creating an application, and linking the two (do the buying and linking twice, once for each number).

You will need to give the answer_url of your publicly-accessible webserver or ngrok endpoint when you configure your application, this should be [YOUR_URL]/answer in this project. For example if your ngrok URL is https://25b8c071.ngrok.io then the your answer_url would be https://25b8c071.ngrok.io/answer

When you create an application, you will get a key to use for authentication. Save this into a file called app.key and keep it safe! You will need it later on to make outgoing phone calls.

Once the application is created, configured and linked to the phone numbers, take a look at the code and then go ahead and try it out.

Set Up and Run the Application Code

Clone or download the code for this application from https://github.com/Nexmo/800-replacement.

One you have it, you will need to:

• Run bundle install to get the dependencies
• Copy .env.example to .env and edit this new file with your own configuration settings including the two numbers you bought and linked to your application
• Start the app with ruby app.rb

Receive an Inbound Phone Call

Whenever someone calls one of the numbers that are linked to the Vonage application, Vonage will receive an incoming call. Vonage will then notify your web application of that call. It does this by making a webhook request to your web app's answer_url endpoint. You can read more information about the answer webhook in the developer docs.

User will call a city-specific number, so we need to know which number maps to which city. In our case we will configure the two numbers you bought into your application, but in most real environments this relationship is stored in a database. The configuration can be found in app.rb:

We can now handle an incoming call, extract the number dialled, and respond to the user with the current status of the transit in their city. The statuses will be delivered to the user as spoken text-to-speech messages.

The answer_url that we set earlier is the route that will be in use when we make a call. You can find this code in app.rb:

This code answers the call, checks the incoming phone number, and fetches the status that relates to that geographical number. Then it makes a call to the respond_with() function that takes care of building the Nexmo Call Control Object (NCCO). These objects tell Vonage what text-to-speech messages should be played to the caller and which other actions, such as accepting number input, should be performed.

Call your Vonage numbers and check that your application speaks the (imaginary) transport status for Chicago on one number, San Francisco on the other, and offers multiple options afterwards using the input NCCO action.

Prompt for Other Localities

We can offer any of the cities' information to any caller, but if they didn't call the number related to their desired location then we need to ask them for input, as you see above. Let's look at that input action in more detail:

The input puts the call into a listening mode. The configuration on this particular input block expects only one digit, but you can also accept multiple digits and end on the # symbol for example. The code here also sets the eventUrl: this is where the webhook containing the input data will be sent to. In this case, it's the /city endpoint on our application that will receive the data.

The button pressed will arrive in the dtmf field of the incoming webhook to that /city URL. Check out the more detailed webhook documentation for more information about webhook payloads.

Once you work out which city the user requested data for, you can look up the city and its status from the same configuration as before and re-use the respond_with() function to return the NCCO.

Conclusion

You have created a voice application, purchased phone numbers and linked them to a Vonage voice application. You have then built an application that receives an inbound call, maps the called number to a standard input, and then collects more input from the user to play back further info to them.

Where Next?

• Code on GitHub - all the code from this application
• Add a call whisper to an inbound call - how to announce details about an incoming caller before connecting the call
• Inbound call tracking - blog post on tracking which inbound marketing campaigns are working best
• Voice API Reference - detailed API documentation for the Voice API
• NCCO reference - detailed documentation for the webhooks