Cómo reproducir audio en una llamada con ASP.NET Core MVC

Cuando se crean aplicaciones habilitadas para voz, es decir, que pueden realizar y recibir llamadas telefónicas, lo más importante es poder reproducir audio en la llamada mediante programación.

Esto sirve como base para los IVR, un sistema de alerta de que vas a ser conectado a una llamada, como un aviso para hacer algo, o incluso sólo un mensaje en espera. Sin la capacidad de reproducir audio en una llamada, hay pocos casos de uso para las aplicaciones habilitadas para Voice más allá de la transmisión de voz.

En este tutorial, exploraremos cómo comenzar a reproducir audio en llamadas con Voice API de Vonage y ASP.NET Core MVC.

Ir directamente al código

Si quieres saltarte este tutorial y pasar directamente al código, está todo disponible en GitHub.

Requisitos previos

• Vamos a necesitar la última .NET Core SDK, estoy usando 3.1

• Vamos a utilizar Visual Studio Code para este tutorial. Por supuesto, esto también funcionará con Visual Studio y Visual Studio para Mac. Sólo puede haber algunos pasos ligeramente diferentes para la configuración y ejecución.

• Probaremos esto con ngrok - así que sigue sus instrucciones para configurarlo.

• Vamos a necesitar npm para obtener el vonage-cli

  Vonage API Account

  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.

  

  Ready to start building?

  Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Resumen del tema

Hay dos métodos que vamos a utilizar para reproducir audio en una llamada.

1. Cuando se llame a nuestra aplicación, ésta devolverá un archivo NCCO (objeto de control de llamadas de Nexmo) que le indica a Vonage qué reproducir en la llamada.

2. Utilizaremos la Voice API (VAPI) de Vonage para realizar una llamada y reproducir audio en la llamada que creemos.

En ambos casos, vamos a utilizar la función de transmisión de audio. Esto nos permite reproducir un archivo de audio en una llamada. Sin embargo, sería negligente por mi parte no señalar que, además de reproducir archivos de audio en las llamadas, no faltan posibilidades para personalizar lo que se reproduce en una solicitud, ya sea mediante la función texto a voz (TTS) o mediante websockets para reproducir secuencias de audio dinámicas en una llamada.

Configuración de Nexmo CLI

Con npm instalado podemos seguir adelante e instalar y configurar el Nexmo CLI usando:

Esto conseguirá la configuración Nexmo CLI y listo para funcionar.

Ejecutar Ngrok

Voy a estar tirando todo en localhost:5000. Ejecutar ngrok para acceder públicamente localhost:5000.

Toma nota de la URL en la que se está ejecutando ngrok. En mi caso, se está ejecutando en http://7ca005ad1287.ngrok.io. Esta va a ser la URL base para mis webhooks en el futuro.

Crear nuestra aplicación de Vonage

Una aplicación de Vonage es una construcción que nos permite vincular la ruta de nuestros números y webhooks fácilmente. Puedes crear una aplicación en el Panel de Vonageo puedes crearla ahora con la CLI.

Esto creará una aplicación de Vonage. Luego vinculará todas las llamadas entrantes a esa aplicación con la URL de respuesta: http://7ca005ad1287.ngrok.io/webhooks/answer. Todos los eventos de llamadas que se produzcan en esa aplicación se enrutarán a http://7ca005ad1287.ngrok.io/webhooks/events. Este comando imprimirá dos cosas.

1. Tu Id. de aplicación: puedes ver este Id. de aplicación en el Panel de Vonage

2. La clave privada de tu aplicación. Asegúrese de tomar esto y guardarlo en un archivo-estoy llamando a la mía private.key.

Vincula tu número de Vonage a tu aplicación

Cuando creas tu Account, se te asigna un número de Vonage. Puedes verlo en la sección sección Numbers del panel de control. También puedes ejecutar nexmo number:list en tu consola para obtener una lista de tus números. Toma tu número de Vonage y tu Id. de aplicación y ejecuta lo siguiente:

Una vez hecho esto, sus llamadas se dirigirán a su URL.

Crear proyecto

En tu consola, navega hasta el directorio de tu código fuente y ejecuta el siguiente comando:

Esto creará un directorio y un proyecto llamado PlayAudioMvcejecuta el comando cd para cambiar tu directorio a PlayAudioMvcy ejecuta lo siguiente para instalar la biblioteca de Vonage.

Ejecute code . para abrir Visual Studio Code.

Editar el controlador

Añadir sentencias Using

Vamos a utilizar el archivo HomeController.cs abra Controllers\HomeController.cs y añade las siguientes sentencias using en la parte superior:

using Microsoft.Extensions.Configuration;
using Vonage.Voice.Nccos.Endpoints;
using Vonage.Voice.Nccos;
using Vonage.Voice;
using Vonage.Request;

Configuración de inyección

Vamos a aprovechar la inyección de dependencia para obtener algunos de los elementos configurables para nuestra aplicación, a saber, el appId y la clave privada. Para ello, añadiremos un campo IConfiguration al campo HomeControllery luego añade un campo IConfigurationParameter al constructor y asigna ese campo IConfiguration al parámetro. Tu constructor debería tener ahora este aspecto. Mientras estamos aquí, también vamos a añadir una constante a esta clase para apuntar a un archivo de audio en la web, hay uno útil que Vonage proporciona para los casos de prueba que vamos a enlazar:

const string STREAM_URL = "https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3";

private readonly IConfiguration _config;

public HomeController(ILogger<HomeController> logger, IConfiguration config)
{
    _config = config;
    _logger = logger;
}

Añadir punto final de respuesta

Vamos a tratar el caso 1: cuando recibimos una llamada de un usuario, y queremos reproducir un archivo de audio en ella. Vamos a necesitar añadir una acción a nuestro controlador que devuelva una cadena JSON. Añade lo siguiente a nuestra HomeController clase:

[HttpGet("/webhooks/answer")]
public string Answer()
{
    var streamAction = new StreamAction{
        StreamUrl = new string[]
        {
            STREAM_URL
        }
    };
    var ncco = new Ncco(streamAction);
    return ncco.ToString();
}

Cuando alguien marque, Vonage realizará una solicitud Get en esta URL. Este método aprovecha nuestro creador de NCCO para crear una NCCO; luego convertimos la NCCO en una cadena y la devolvemos. Esto devolverá una cadena JSON que se verá así:

[{"streamUrl":["https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"],"action":"stream"}]

Añadir marcación de salida

La siguiente acción que vamos a tener que añadir es una acción para marcar. Esto es un poco más complicado. Necesitará obtener nuestro appId y clave de la configuración. También necesita un número al cual llamar y un número desde el cual llamar, tu número de Vonage, luego creará un cliente de Voice, creará una estructura de solicitud y realizará la llamada:

[HttpPost]
public IActionResult MakePhoneCall(string toNumber, string fromNumber)
{
    var appId = _config["APPLICATION_ID"];
    var privateKeyPath = _config["PRIVATE_KEY_PATH"];

    var streamAction = new StreamAction{ StreamUrl = new string[] { STREAM_URL }};
    var ncco = new Ncco(streamAction);

    var toEndpoint = new PhoneEndpoint{Number=toNumber};
    var fromEndpoint = new PhoneEndpoint{Number=fromNumber};

    var credentials = Credentials.FromAppIdAndPrivateKeyPath(appId, privateKeyPath);
    var client = new VoiceClient(credentials);
    var callRequest = new CallCommand { To = new []{toEndpoint}, From = fromEndpoint, Ncco= ncco};
    var call = client.CreateCall(callRequest);
    ViewBag.Uuid = call.Uuid;
    return View("Index");
}

Añadir un frontend

Siguiendo con el tema de aprovechar nuestro Home Controller, también vamos a aprovechar nuestra Home View. Abra Views\Home\Index.cshtmly quita el div de plantilla que hay ahí. Vamos a añadir un formulario básico que se enviará a nuestra acción MakePhoneCall y cuando la acción finalice, mostraremos el UUID de nuestra llamada telefónica. Con esto en mente, vamos a añadir lo siguiente a nuestro archivo:

@using (Html.BeginForm("MakePhoneCall", "home", FormMethod.Post))
{
    <div class="form-vertical">
        <h4>Call<h4>
                @Html.ValidationSummary(true, "", new { @class = "text-danger" })
                <div class="form-group">
                    @Html.Label("To")
                    <div>
                        @Html.Editor("toNumber", new { htmlAttributes = new { @class = "form-control" } })
                    </div>
                </div>

                <div class="form-group">
                    @Html.Label("From")
                    <div>
                        @Html.Editor("fromNumber", new { htmlAttributes = new { @class = "form-control" } })
                    </div>
                </div>
                <div class="form-group">
                    <div class="col-md-offset-2 col-md-10">
                        <button type="submit">Send</button>
                    </div>
                </div>
    </div>
}
@if(@ViewBag.Uuid != null){
    <h2>Call UUID: @ViewBag.Uuid</h2>
}

Configure su aplicación

Añadir variables de configuración

Recuerda que estamos usando el IConfiguration para obtener nuestro appId y la ruta de nuestra clave privada. Con esto en mente, abramos appsettings.json y añadamos las siguientes claves:

"APPLICATION_ID":"APPLICATION_ID",
"PRIVATE_KEY_PATH":"C:\\path\\to\\your\\private.key"

Configurar Kestrel o IIS Express

Como estoy utilizando VS Code, mi aplicación va a utilizar naturalmente kestrel. Independientemente de si está utilizando kestrel o IIS Express, vaya a properties\launchSettings.json y desde el menú PlayAudioMvc->applicationUrl suelta el https://localhost:5001 ya que no estamos usando SSL con ngrok, y estamos apuntando al puerto 5000. Si estás usando IIS Express, en iisSettings->iisExpressconfigure applicationUrl a http://localhost:5000 y el sslPort a 0.

Pruebe su aplicación

Con esto hecho, todo lo que necesitas hacer es ejecutar el comando dotnet run y tu aplicación se iniciará y se alojará en el puerto 5000. Todo lo que queda por hacer ahora es llamar a tu aplicación: puedes llamar a tu número de Vonage y realizar una llamada desde tu aplicación. Puedes realizar la llamada navegando a localhost:5000 y completando y enviando el formulario.

Recursos

• Puede obtener más información sobre la Voice API consultando nuestra sitio web de documentación

• Puede aprender MUCHO sobre el funcionamiento de las Voice API, en particular de la NCCOS, consultando nuestra Referencia NCCO

• Todo el código de este tutorial está disponible en GitHub