1. Vonage Learn
  2. Blog
  3. 2017
  4. 11
  5. 29
  6. How to Play Audio to a Caller in Asp Net Core Dr
How to Play Audio to a Caller in ASP.NET Core

< Tutorial />

How to Play Audio to a Caller in ASP.NET Core

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 Nexmo 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

Prerequisites for using Nexmo Voice API with ASP.NET

  • Visual Studio 2017
  • A project setup for this tutorial series, which you can find on Github
  • Optional: The Nexmo CLI


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 Nexmo 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 Nexmo Voice API with ASP.NET: Before you start post outlines all the necessary configuration steps.

In your project, in the appsettings.json file, make sure to initialize Nexmo 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

Creating a stream NCCO

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.


Using tools like ngrok will make it reachable by the Nexmo 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))

Later on, we will be using CreateStreamNCCO to allow users to create their own stream NCCO via the website.

Playing audio in the call

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.

public ActionResult PlayAudioToCaller()
  return View();

Under the Voice Views folder, create a new view PlayAudioToCaller.cshtml. Within this view, we will add two forms:

  1. The first will allow us to create a stream NCCO.

  2. 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 Nexmo.Api ``` Inside 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.
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\[]

    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.

Learn more

API references and tools

Nexmo Getting Started Guide for ASP.NET

Comments currently disabled.