Como reproduzir áudio durante uma chamada com o ASP.NET Core MVC

Ao desenvolver aplicativos com recursos de voz — ou seja, que podem fazer e receber chamadas telefônicas —, o aspecto mais fundamental que você precisa saber fazer é reproduzir áudio durante a chamada por meio de programação.

Isso serve de base para os IVRs — um sistema de alerta de que você está prestes a ser conectado a uma chamada, um aviso para realizar alguma ação ou até mesmo uma mensagem de espera. Sem a capacidade de reproduzir áudio durante uma chamada, há poucos casos de uso para aplicativos com recursos de voz além do proxy de voz.

Neste tutorial, vamos explorar como dar os primeiros passos na reprodução de áudio em chamadas com a Voice API da Vonage e ASP.NET Core MVC.

Ir direto para o código

Se você quiser pular este tutorial e ir direto para o código, tudo está disponível no GitHub.

Pré-requisitos

• Vamos precisar do SDK mais recente do .NET Core; estou usando a versão 3.1

• Vamos usar o Visual Studio Code neste tutorial. É claro que isso também funciona com o Visual Studio e o Visual Studio para Mac. Pode ser que haja apenas algumas etapas ligeiramente diferentes na configuração e na execução.

• Vamos testar isso com ngrok — então, siga as instruções deles para configurá-lo.

• Vamos precisar de o npm para baixar o vonage-cli

Visão geral do tópico

Existem dois métodos que vamos abordar para reproduzir áudio durante uma chamada.

1. Quando nosso aplicativo for chamado, ele retornará um NCCO (Nexmo Call Control Object) informando à Vonage o que deve ser reproduzido na chamada.

2. Usaremos a Voice API da Vonage (VAPI) para fazer uma chamada e reproduzir um áudio durante a chamada que criarmos.

Em ambos os casos, vamos utilizar a funcionalidade de streaming de áudio. Isso nos permite reproduzir um arquivo de áudio durante uma chamada. No entanto, seria negligente da minha parte não destacar que, além de reproduzir arquivos de áudio durante as chamadas, há amplas possibilidades de personalizar o que é reproduzido em uma solicitação — seja utilizando o API de conversão de texto em fala (TTS) ou por meio de websockets para reproduzir fluxos de áudio dinâmicos durante uma chamada.

Configurar a CLI do Nexmo

Com o npm instalado, podemos prosseguir e instalar e configurar a CLI do Nexmo da seguinte forma:

Isso vai configurar a CLI do Nexmo e deixá-la pronta para uso.

Executar o Ngrok

Vou colocar tudo no localhost:5000. Execute o ngrok para acessar publicamente localhost:5000.

Anote a URL em que o ngrok está sendo executado. No meu caso, ele está sendo executado em http://7ca005ad1287.ngrok.io. Essa será a URL base para meus webhooks daqui em diante.

Criar nosso aplicativo da Vonage

Um aplicativo da Vonage é uma estrutura que nos permite vincular e direcionar nossos números e webhooks com facilidade. Você pode criar um aplicativo no Painel da Vonageou simplesmente criá-la agora usando a CLI.

Isso vai criar uma aplicação da Vonage. Em seguida, todas as chamadas recebidas nessa aplicação serão direcionadas para a URL de resposta: http://7ca005ad1287.ngrok.io/webhooks/answer. Todos os eventos de chamada que ocorrerem nesse aplicativo serão encaminhados para http://7ca005ad1287.ngrok.io/webhooks/events. Este comando exibirá duas informações.

1. O ID do seu aplicativo — você pode visualizar esse ID no Painel da Vonage

2. A chave privada do seu aplicativo. Certifique-se de copiá-la e salvá-la em um arquivo — vou chamar o meu de private.key.

Vincule seu número da Vonage ao seu aplicativo

Ao criar sua conta, você recebe um número da Vonage. Você pode conferi-lo na seção de números do painel de controle. Ou, como alternativa, basta executar nexmo number:list no seu console para listar seus Numbers. Pegue seu número da Vonage e seu ID de aplicativo e execute o seguinte:

Feito isso, suas chamadas serão direcionadas corretamente para a sua URL.

Criar projeto

No seu terminal, acesse o diretório do código-fonte e execute o seguinte comando:

Isso criará um diretório e um projeto chamado PlayAudioMvc. Execute o comando `cd` para mudar para o diretório PlayAudioMvce execute o seguinte para instalar a biblioteca do Vonage.

Execute code . para abrir o Visual Studio Code.

Editar o controlador

Adicionar instruções “Using”

Vamos aproveitar o HomeController.cs arquivo, abrir Controllers\HomeController.cs e adicionar as seguintes instruções `using` no início:

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

Injetar configuração

Vamos utilizar a injeção de dependências para obter alguns dos itens configuráveis do nosso aplicativo, a saber, o appId e a chave privada. Para isso, adicione um IConfiguration campo ao HomeControllere, em seguida, adicione um IConfigurationParameter ao construtor e atribua esse IConfiguration campo ao parâmetro. Seu construtor agora deve ficar assim. Já que estamos aqui, vamos também adicionar uma constante a essa classe para apontar para um arquivo de áudio na web; há um que serve bem, fornecido pela Vonage para casos de teste, ao qual vamos criar um link:

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;
}

Adicionar ponto final de resposta

Vamos abordar o caso 1: quando recebemos uma chamada de um usuário e queremos reproduzir um arquivo de áudio para ele. Precisaremos adicionar uma ação ao nosso controlador que retorne uma string JSON. Adicione o seguinte à nossa HomeController classe:

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

Quando alguém ligar, a Vonage enviará uma solicitação GET para esta URL. Este método utiliza nosso gerador de NCCO para criar um NCCO; em seguida, convertemos o NCCO em uma string e a retornamos. Isso retornará uma string JSON com a seguinte aparência:

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

Adicionar chamada de saída

A próxima ação que precisaremos adicionar é uma ação para fazer uma chamada. Isso é um pouco mais complicado. Ela precisará obter nosso appId e nossa chave da configuração. Também precisará de um número para ligar e de um número de origem, o seu número da Vonage; em seguida, ela criará um Voice Client, criará uma estrutura de solicitação e fará a chamada:

[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");
}

Adicionar um front-end

Seguindo a linha de aproveitar nosso Home Controller, também vamos aproveitar nossa Home View. Abra Views\Home\Index.cshtmle remova a div padrão que está lá. Vamos adicionar um formulário básico que enviará dados para nossa MakePhoneCall ação e, quando a ação for concluída, exibiremos o UUID da chamada telefônica. Com isso em mente, vamos adicionar o seguinte ao nosso arquivo:

@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 seu aplicativo

Adicionar variáveis de configuração

Lembre-se de que estamos usando o IConfiguration para obter nosso appId e o caminho da nossa chave privada. Com isso em mente, vamos abrir o arquivo appsettings.json e adicionar as seguintes chaves:

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

Configurar o Kestrel ou o IIS Express

Como estou usando o VS Code, meu aplicativo vai, naturalmente, usar o Kestrel. Independentemente de você estar usando o Kestrel ou o IIS Express, acesse properties\launchSettings.json e, na PlayAudioMvc->applicationUrl remova o https://localhost:5001 ponto de extremidade — já que não estamos usando SSL com o ngrok e estamos apontando para a porta 5000. Se você estiver usando o IIS Express, em iisSettings->iisExpress, defina o applicationUrl para http://localhost:5000 e o sslPort para 0.

Testando seu aplicativo

Feito isso, basta executar o comando dotnet run e seu aplicativo será iniciado e ficará hospedado na porta 5000. Agora, basta acessar seu aplicativo — você pode acessá-lo pelo seu número da Vonage e fazer uma chamada a partir dele. Para fazer a chamada, acesse localhost:5000, preencha o formulário e envie-o.

Recursos

• Você pode saber muito mais sobre a Voice API acessando nosso site de documentação

• Você pode aprender MUITO sobre como funcionam as Voice APIs, especialmente as NCCOS, consultando nossa referência sobre o NCCO

• Todo o código deste tutorial está disponível no GitHub