Welcome to the second tutorial in our how to use Voice APIs with ASP.NET series. To check out other tutorials, please go to the Learn more section at the end of this post.
In the previous post, we learnt how to make a text-to-speech phone call in an ASP.NET web application. In this post, we will learn how to play audio to a caller. Sounds like fun, right? But that’s not all. We will also discover how to dynamically create Vonage Call Control Objects (NCCOs) in code and use them within our app. Bonus: We will be using an ASP.NET Core project for this demo.
Let’s get started!
are you ready gif
Visual Studio 2017
A project set-up 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.
This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.
Since you may or may not have read the first tutorial in this series—which you should, btw—let’s go through what we need before diving into the code.
To be able to use The Vonage Voice API, you'll need a voice application to store configuration data and generate a public/private key pair.
How to do so? Don’t worry, I’ve got you covered. The Vonage Voice API with ASP.NET: Before you start post has a great outline of all the necessary configuration steps.
In your project, in the appsettings.json file, make sure to initialize Vonage with your API credentials as well as the App ID and private key you just created.
Now, let’s write some code!
wonder woman gif
As mentioned at the beginning of this post, when the user answers the call, we want to play an audio file to them. The NCCO file available at our answer_url contains this information. To execute this action, the NCCO must be valid and have the right action. The action required to send the audio file to a call or conversation is stream.
For this demo, we will only need to specify streamUrl, which is the array containing the audio file. The latter must be an mp3 or wav. We do provide a sample stream NCCO; you can use it to try this demo. But for real-life scenarios, you may want to create your own.
Under NexmoVoiceASPNetCoreQuickstarts, add a new folder called Helpers, and then add a new class NCCOHelpers.cs to this folder. We will create all the NCCOs we need in this folder. For the sake of simplicity, we will save our NCCO files directly under wwwroot.
ncco helpers
As explained in the configuration steps, adding the following line to the Configure method in Startup.cs will allow us to serve up the NCCO json file.
app.UseStaticFiles();Using tools like ngrok will make it reachable by the Vonage API.
ngrok status
Within NCCOHelpers.cs, we will add a method called CreateStreamNCCO, in which we will dynamically create a JObject representing the stream NCCO.
public void CreateStreamNCCO(string rootpath, string[] streamUrl, int level, bool bargeIn, int loopTimes)
{
dynamic StreamNCCO = new JObject();
StreamNCCO.action = "stream";
StreamNCCO.streamUrl = new JArray { streamUrl };
StreamNCCO.level = level;
StreamNCCO.bargeIn = bargeIn;
StreamNCCO.loop = loopTimes;
SaveFile(rootpath, "StreamNCCO.json", StreamNCCO);
}Then we save that object as a JSON file under wwwroot.
private void SaveFile(string rootpath, string filename, dynamic StreamNCCO)
{
var pathToFile = Path.Combine(rootpath, filename);
using (StreamWriter s = File.CreateText(pathToFile))
{
s.Write(StreamNCCO.ToString());
}
}Later on, we will be using CreateStreamNCCO to allow users to create their own stream NCCO via the website.
Under NexmoVoiceAspNetCoreQuickstarts, we created a controller called VoiceController.cs in which we will create an action method called PlayAudioToCaller.
Above the method, add a HttpGetAttribute to allow the user to navigate to the corresponding view.
[HttpGet]
public ActionResult PlayAudioToCaller()
{
return View();
}Under the Voice Views folder, create a new view PlayAudioToCaller.cshtml. Within this view, we will add two forms:
The first will allow us to create a stream NCCO.
The second will be used to make the phone call.
Back to the VoiceController. Make sure you have the following `using` statement on the top of the file.
using VonageInside the constructor, we will pass the hosting environment, which will be used to specify the root path to where we will save the NCCO file. We will also instantiate the NCCO helpers class.
private readonly IHostingEnvironment _hostingEnvironment;
private NCCOHelpers _nccohelper;
public VoiceController(IHostingEnvironment hostingEnvironment)
{
_hostingEnvironment = hostingEnvironment;
_nccohelper = new NCCOHelpers();
}Add an action method named CreateStreamNCCO with the following parameters:
string[] streamUrl : an array containing a single url to the audio file to stream.
int level=0 : the audio level. This is defaulted to zero.
bool bargeIN defaulted to false.
int loop =1 so the audio is only repeated once. Inside this method, we will call the CreateStreamNCCO method from the NCCO helpers class.
[HttpPost]
public ActionResult CreateStreamNCCO(string\[] streamUrl, int level=0, bool bargeIN = false, int loop =1)
{
_nccohelper.CreateStreamNCCO(_hostingEnvironment.WebRootPath, streamUrl, level, bargeIN, loop);
ViewData\["NCCOButtonText"] = "NCCO Created";
return View("PlayAudioToCaller");
}Add another action method named PlayAudioToCaller with a string parameter: to. Within this method, you will make a call using the parameter as the to. The from number is your Nexmo virtual number (retrieved from the appsettings.json), the answer_url is the stream NCCO whether you choose to use Nexmo’s community NCCO example mentioned above or the NCCO you created and made reachable via ngrok.
public ActionResult PlayAudioToCaller(string to)
{
var NEXMO_FROM_NUMBER = Configuration.Instance.Settings\["appsettings:NEXMO_FROM_NUMBER"];
var NEXMO_TO_NUMBER = to;
var NEXMO_CALL_ANSWER_URL = "https://raw.githubusercontent.com/nexmo-community/ncco-examples/gh-pages/first_call_speech.json";
var results = Call.Do(new Call.CallCommand
{
to = new\[]
{
new Call.Endpoint {
type = "phone",
number = NEXMO_TO_NUMBER
}
},
from = new Call.Endpoint
{
type = "phone",
number = NEXMO_FROM_NUMBER
},
answer_url = new\[]
{
NEXMO_CALL_ANSWER_URL
}
});
return RedirectToAction("Index", "Home");
}Now, let's run the app and make a phone call.
When it is successful, it retrieves the NCCO from your webhook, the audio will be played, and then the call is terminated. 
"null"
API references and tools
Vonage Getting Started Guide for ASP.NET
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.
