In Context

The next-generation communications blog from Nexmo

< Back

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

November 29, 2017 Published by

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!

Prerequisites for using Nexmo Voice API with ASP.NET


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!

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.

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.

Within NCCOHelpers.cs, we will add a method called CreateStreamNCCO, in which we will dynamically create a JObject representing the stream NCCO.

Then we save that object as a JSON file under wwwroot.

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.

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.

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.

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.

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.

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

Tags: , , ,

Categorised in: , ,

This post was written by