Buzón de voz

Introducción

En API de voz de Vonage es la manera más fácil de crear aplicaciones de voz de alta calidad en la nube. En esta guía aprenderás a grabar audio de llamadas entrantes usando .NET y la Voice API de Vonage.

Esta guía proporciona instrucciones paso a paso que le muestran cómo:

  1. Configura una Account de Vonage
  2. Crear una aplicación de Vonage
  3. Configurar una aplicación de Vonage
  4. Crear una aplicación ASP.NET Core
  5. Añádele el paquete de Vonage
  6. Recibir una llamada y grabarla
  7. Recuperar la grabación de Vonage

Requisitos previos

Hay algunos requisitos previos que debes cumplir antes de poder trabajar con esta guía. Si ya has completado alguno de ellos, no dudes en saltarte ese paso.

Crear cuenta de Vonage

Puedes crear una Account de Vonage a través de la página Cuadro de mandos. Dentro del panel puedes crear Applications y comprar números de Vonage. También puedes realizar estas tareas usando el CLI de Vonage.

Instalar la CLI de Vonage

En CLI de Vonage le permite realizar muchas operaciones en la línea de comandos. Algunos ejemplos son la creación de aplicaciones, la compra de números y la vinculación de un número a una aplicación.

Para instalar el CLI con NPM ejecutar:

npm install --location=global @vonage/cli

Configura la CLI de Vonage para usar tu clave y secreto de API de Vonage. Puedes obtenerlos en la página página de configuración en el Cuadro de mandos.

Ejecute el siguiente comando en un terminal, sustituyendo API_KEY y API_SECRET con los tuyos:

vonage config:set --apiKey=API_KEY --apiSecret=API_SECRET

Cómo ejecutar Ngrok

Debes hacer que tu webhook sea accesible a las API de Vonage a través de la Internet pública. Una manera sencilla de lograrlo durante el desarrollo sin instalar tu propio servidor es usar Ngrok. Para saber más, lea nuestra documentación sobre Ngrok.

Descargue e instale ngrok, luego ejecute el siguiente comando para exponer su aplicación en el puerto 3000 a la Internet pública:

./ngrok http 3000

Si es abonado de pago, puede escribir:

./ngrok http 3000 -subdomain=your_domain

NOTA: En este ejemplo, Ngrok desviará los webhooks de Vonage que especificó al crear su aplicación de Vonage a localhost:3000. Aunque aquí se muestra el puerto 3000, puede utilizar cualquier puerto libre que le convenga.

Crear una aplicación de voz

Existen dos métodos para crear una aplicación de voz:

  1. Uso de la CLI de Vonage
  2. Uso del panel de control

Cada uno de estos métodos se describe en las secciones siguientes.

Cómo crear una aplicación de voz con la CLI de Vonage

Para crear tu aplicación utilizando la CLI de Vonage, introduce el siguiente comando en el intérprete de comandos sustituyendo a NGROK_HOST_NAME con el host ngrok que obtuvo cuando configuró ngrok:

vonage apps:create "AspNetTestApp" --voice_answer_url=http://NGROK_HOST_NAME/webhooks/answer --voice_event_url=http://NGROK_HOST_NAME/webhooks/events

Este comando crea una Aplicación de Vonage con Voz capacidad. Configura la Aplicación con tus URLs de webhooks de respuestas y eventos y genera un archivo de clave privada. private.keyque deberá guardar en el directorio de su proyecto.

El comando devuelve un ID de aplicación único. Utiliza este ID de aplicación para vincular tu número virtual de Vonage a tu aplicación ejecutando lo siguiente:

vonage apps:link APPLICATION_ID --number=VONAGE_NUMBER

Esto vinculará ese número virtual de Vonage a tu aplicación, lo que hará que todos los eventos de voz que se produzcan para ese número se enruten a tus URL designadas.

Cómo crear una aplicación de voz con el panel de control

Puede crear aplicaciones de voz en la sección Cuadro de mandos.

Para crear su aplicación utilizando el Panel de control:

  1. En Applications en el Panel de control, haga clic en el botón Crear una nueva aplicación botón.

  2. En NombreIntroduzca el nombre de la aplicación. Elija un nombre para facilitar futuras referencias.

  3. Pulse el botón Generar clave pública y privada. Esto creará un par de claves pública/privada y la clave privada será descargada por tu navegador. Guarde la clave privada generada.

  4. En Capacidades seleccione el Voz botón.

  5. En el Respuesta URL introduzca la URL de su webhook de llamadas entrantes, por ejemplo, http://example.com/webhooks/answer.

  6. En el URL del evento introduzca la URL de su webhook de estado de llamada, por ejemplo, http://example.com/webhooks/events.

  7. Haga clic en el botón Generar nueva aplicación botón.

  8. Ahora pasarás al siguiente paso del procedimiento Crear solicitud, donde deberás vincular tu número de Vonage a la solicitud.

Ya ha creado su aplicación.

NOTA: Antes de probar su aplicación, asegúrese de que sus webhooks están configurados y de que su servidor webhook está en funcionamiento.

Crear el archivo de proyecto de voz

Para empezar, creará una Voz csproj archivo. Para facilitar las pruebas, configure Kestrel con HTTPS desactivado.

En su terminal, ejecute el siguiente comando:

dotnet new mvc --no-https -n VonageVoice

Instalar paquete Vonage

Para instalar el paquete NuGet de Vonage, cambie de directorio al directorio VonageVoice y ejecute el siguiente comando:

dotnet add package Vonage

Ahora puede abrir el VonageVoice.csproj en Visual Studio.

Nota: Esta guía asume que usted está utilizando Visual Studio. Como alternativa, puede abrir el archivo VonageVoice en Visual Studio Code u otro editor, pero es posible que tenga que crear algunos de los andamios que Visual Studio genera para usted.

Añadir controlador de voz

Haga clic con el botón derecho del ratón en Controllers y seleccione add->Controller. Seleccione "Add Empty MVC Controller" y póngale un nombre VoiceController.

Añadir using declaraciones para Vonage.Voice, Vonage.Voice.Nccos, Vonage.Voice.Nccos.Endpoints, Vonage.Requesty Microsoft.Extensions.Configuration en la parte superior de este archivo.

Configuración de inyección

La dependencia inyecta un IConfiguration a través del constructor:

private readonly IConfiguration _config { get; set; }

public VoiceController(IConfiguration config)
{
    _config = config;
}

Añadir ruta de respuesta al buzón de voz

Añade una ruta a tu VoiceController para atender la llamada entrante. Se encontrará en /webhooks/answer y devolverá un OCN con un record que indica a Vonage que comience a grabar la llamada.

También debe especificar la URL de otro webhook - /webhooks/recording - al cual Vonage hará una solicitud cuando la grabación esté lista para descargar. Codificarás este webhook en el próximo paso.

[HttpGet("/webhooks/answer")]
public string Answer()
{
    var talkAction = new TalkAction
    {
        Text = "Hello, you have reached Steve's number," +
        " he cannot come to the phone right now. " +
        "Please leave a message after the tone."
    };
    var recordAction = new RecordAction
    {
        EndOnSilence = "3",
        BeepStart = "true",
        EventUrl = new[] { $"{Request.Scheme}://{Request.Host}/webhooks/recording" },
        EventMethod = "POST"
    };

    var ncco = new Ncco(talkAction, recordAction);
    return ncco.ToString();
}

Añadir ruta de grabación

Una vez que la llamada haya terminado de grabarse, Vonage enviará una solicitud a la URL del webhook que configuraste en la sección record en su OCN. Esta solicitud contendrá la URL desde la que podrá descargar el archivo de audio.

En esta guía, utilizará la función GetRecording API para descargar la grabación en su máquina local:

[HttpPost("/webhooks/recording")]
public async Task<IActionResult> Recording()
{
    var appId = _config["APPLICATION_ID"];
    var privateKeyPath = _config["PRIVATE_KEY_PATH"];
    var credentials = Credentials.FromAppIdAndPrivateKeyPath(appId, privateKeyPath);
    var voiceClient = new VoiceClient(credentials);
    var record = await Vonage.Utility.WebhookParser.ParseWebhookAsync<Record>(Request.Body, Request.ContentType);
    var recording = await voiceClient.GetRecordingAsync(record.RecordingUrl);
    await System.IO.File.WriteAllBytesAsync("your_recording.mp3", recording.ResultStream);
    return StatusCode(204);
}

Configurar la aplicación ASP.NET

Abra su appsettings.json y añádale los dos campos siguientes:

  • APPLICATION_ID: Identificador único de su Voice API Applications.
  • PRIVATE_KEY_PATH: La ubicación de la aplicación de su private.key archivo.

Ejecute su aplicación

En la consola, vaya a la sección csproj y ejecute el comando dotnet run --urls=http://localhost:3000. Esto iniciará la aplicación en http://localhost:3000. Abra esa URL en su navegador.

¿Y ahora qué?

Obtén más información sobre las capacidades de Vonage Voice API: