This is the fourth tutorial on how to use Voice APIs with ASP.NET series. In the previous tutorial, we learnt how to Receive a Phone Call with Vonage Voice API, ASP.NET Core, and NancyFX. This is a great start, but in a real life scenario we expect some sort of interaction with the caller. Maybe they will be prompted to pick an option or enter a PIN. We need a way to handle user input.
That's exactly the aim of this tutorial; we will create an ASP.NET app that handles inbound voice calls and respond to user input using the Vonage Voice API.
In this tutorial, we will:
Create an ASP.NET Core app.
Use NancyFX with ASP.NET Core.
Create a Vonage voice application.
Receive inbound calls within the app.
Create and return NCCOs.
Handle user input.
Run and test the code using Ngrok.
To complete this tutorial, you will need a Vonage 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 Vonage API Dashboard.
Visual Studio 2017.
A project setup for this tutorial series, which you can find on Github.
Optional: The Vonage CLI.
To use The Vonage Voice API, we need to create a voice application. The configuration steps are detailed in the “Nexmo Voice API with ASP.NET: Before you start” post. Once the configuration is done successfully, we are ready to receive an inbound call and handle user input with The Vonage Voice API!
When a call is received, the Vonage Voice API will make a request to your application to figure out how to respond. In this post, we will be using Text-To-Speech to greet the caller, and the input action to collect DTMF input from the caller.
DTMF (Dual Tone Multi Frequency) is a form of signalling used by phone systems to transmit the digits 0-9 and the * and # characters. Typically a caller presses these buttons on their telephone keypad and the phone then generates a tone made up of two frequencies played simultaneously (hence Dual Tone).
To capture DTMF in our application, we are going to use NancyFX alongside our ASP.NET Core project. First of all, we need to add Nancy to our project :
PM> Install-Package Nancy
PM> Install-Package Microsoft.AspNetCore.OwinTo allow Nancy to handle any HTTP requests, we need to tell ASP.NET Core to use Nancy via Owin in the Configure method of Startup.cs.
using Microsoft.AspNetCore.Builder;
using Nancy.Owin;
namespace NexmoVoiceASPNetCoreQuickStarts
{
public class Startup
{
public void Configure(IApplicationBuilder app)
{
app.UseOwin(x => x.UseNancy());
}
}
}The next step is to create a Nancy module in which we set up a route to /webhook/answer which will respond with the ncco returned by GetDTMFNCCO()
using Nancy;
using Newtonsoft.Json.Linq;
namespace NexmoVoiceASPNetCoreQuickStarts
{
public class VoiceModule : NancyModule
{
public VoiceModule()
{
Get["/webhook/answer"] = x => GetDTMFNCCO();
}
private string GetDTMFNCCO()
{
dynamic TalkNCCO = new JObject();
TalkNCCO.action = "talk";
TalkNCCO.text = "Hello. Please press any key to continue.";
JArray jarrayObj = new JArray();
jarrayObj.Add(TalkNCCO);
dynamic InputNCCO = new JObject();
InputNCCO.action = "input";
InputNCCO.maxDigits = "1";
InputNCCO.eventUrl = $"{Request.Url.SiteBase}/webhook/dtmf";
jarrayObj.Add(InputNCCO);
return jarrayObj.ToString();
}
}
}The above code will do the following:
When a call is received, Vonage will prompt the user to press any key by reading out the text "Hello. Please press any key to continue.". When the user presses a key, we pass that input to webhook/dtmf where it will be handled properly. To handle the DTMF, we need to tell the Nancy module how to respond once the request is received. In this case, we will simply read back to the caller which key they pressed.
public class VoiceModule : NancyModule
{
public VoiceModule()
{
Get["/webhook/answer"] = x => GetDTMFNCCO();
Post["/webhook/dtmf"] = x => GetDTMFInput();
}
private string GetDTMFNCCO()
{
dynamic TalkNCCO = new JObject();
TalkNCCO.action = "talk";
TalkNCCO.text = "Hello. Please press any key to continue.";
JArray jarrayObj = new JArray();
jarrayObj.Add(TalkNCCO);
dynamic InputNCCO = new JObject();
InputNCCO.action = "input";
InputNCCO.maxDigits = "1";
InputNCCO.eventUrl = $"{Request.Url.SiteBase}/webhook/dtmf";
jarrayObj.Add(InputNCCO);
return jarrayObj.ToString();
}
private string GetDTMFInput()
{
dynamic TalkNCCO = new JObject();
TalkNCCO.action = "talk";
TalkNCCO.text = $"You pressed {Request.Query["dtmf"]} ";
JArray jarrayObj = new JArray();
jarrayObj.Add(TalkNCCO);
return jarrayObj.ToString();
}
}We are done! To test this sample app, some more configuration steps are required.
If you've been following up so far, you've already configured your Vonage account and created a voice app as shown in this post. We need to link this app to the Vonage phone number that we are going to call. If you don't have a number, you can purchase one using the dashboard or the CLI:
vonage numbers:search US
vonage numbers:buy <phone_number> US
</phone_number>Similarly to link the number, you can use the dashboard or the CLI:
vonage link:app --number=PHONE_NUMBER APP_IDWe need to tell Vonage which URL to make a request to when a call is received - this is called the answer_url. For me, this URL is http://localhost:63286/webhook/answer and that's only running locally. To expose our webhook answer URL, we will use Ngrok.
ngrok http 63286We now have a new url (mine is http://5e18af56.ngrok.io) that can be used as the answer_url for the voice application. Update your application with your new answer_url. It should look like http://[id].ngrok.io/webhook/answerTada! Run the app and give it a go by calling the Vonage number you purchased.
Rabeb was a Developer Advocate at Nexmo focusing on cloud communication APIs and helping developers get the best experience possible when building their apps. Other than writing code for a living, Rabeb advocates for bringing more women and minorities into tech, thus her involvement with Women Who Code and different tech communities. She leads the Women Who Code Network in Bristol.
