This is the third tutorial on how to use Voice APIs with ASP.NET series.
In previous tutorials, we learned how to make a Text-to-Speech phone call with ASP.NET and how to Play Audio to a Caller in ASP.NET Core. But how about receiving calls? The good news is the Vonage Voice API handles inbound calls as well.
Inbound calls are calls made to a Vonage number from another regular phone anywhere in the world. Both inbound and outbound calls follow the same call flow once answered. This call flow is controlled by an NCCO.
In this tutorial, we will create an ASP.NET app that handles inbound voice calls and returns a dynamic response.
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 an NCCO.
Run and test the code using Ngrok.
Visual Studio 2017.
A project setup for this tutorial series, which you can find on Github.
Optional: The Vonage CLI.
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.
To use The Vonage Voice API, we need to create a voice application.
The configuration steps are detailed in the "Vonage Voice API with ASP.NET: Before you start" post.
Once the application is configured successfully, we are ready to receive an inbound call with The Vonage Voice API!
When a call is received, the Vonage Voice API will make a request to the application to figure out how to respond to the caller.
To achieve this, we are going to use NancyFX alongside our ASP.NET Core project.
Nancy is a lightweight open-source framework that promotes the "super-duper-happy-path". This means that it has sensible defaults and conventions and tries to stay out of our way as much as possible.
First of all, we need to add Nancy to our project :
csharp PM> Install-Package Nancy PM> Install-Package Microsoft.AspNetCore.Owin
To 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());
}
}
}We are all good to go! The next step is to create a Nancy module to handle any requests to /webhook/answer.
using Nancy;
namespace NexmoVoiceASPNetCoreQuickStarts
{
public class VoiceModule : NancyModule
{
public VoiceModule()
{
Get["/webhook/answer"] = x => "Hello happy path";
}
}
}I'm using Postman to test, and as you can see our /webhook/answer route is returning exactly what's expected.
asp-post
This is a great start, but Vonage doesn't know what to do with that string. To properly respond to the call, we need to return an NCCO.
using Nancy;
using Newtonsoft.Json.Linq;
namespace NexmoVoiceASPNetCoreQuickStarts
{
public class VoiceModule : NancyModule
{
public VoiceModule()
{
Get["/webhook/answer"] = x => GetInboundNCCO();
}
private string GetInboundNCCO()
{
dynamic TalkNCCO = new JObject();
TalkNCCO.action = "talk";
TalkNCCO.text = "Thank you for calling from " + string.Join(' ', this.Request.Query["from"].ToString().ToCharArray()));
TalkNCCO.voiceName = "Kimberly";
JArray jarrayObj = new JArray();
jarrayObj.Add(TalkNCCO);
return jarrayObj.ToString();
}
}
}GetInboundNCCO() will create an NCCO object that will use Text-To-Speech to read the caller’s phone number back to them using the talk action within the NCCO.
We are accessing the phone number via the from param in the request.
webhook answer
That's all the code we need. To test this properly, 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 a Vonage phone number, the number we will be calling. If you don't have a number, you can purchase one using the dashboard or the CLI. javascript vonage numbers:buy PHONE_NUMBER US Similarly to link the number, you can use the dashboard or the CLI.
vonage numbers:buy PHONE_NUMBER USSimilarly to link the number, you can use the dashboard or the CLI.
vonage apps:link --number=PHONE_NUMBER APP_IDWe need to tell Vonage which URL to make a request to when a call is received (answer_url). For me, this URL is http://localhost:63286/webhook/answer and that's only running locally.
To expose our answer_url, we will use our good friend Ngrok.
ngrok http 63286 -host-header="localhost:63286"This will return a new URL (mine is http://5e18af56.ngrok.io) that can be used as the answer_url for the voice application. Update your answer_url to http://[id].ngrok.io/webhook/answer
Tada! Run the app and give it a go by calling the Vonage number you purchased. It should thank you for calling, then read out your phone number.
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.
