Como criar um aplicativo de correio de voz com o ASP.NET Core

É possível criar soluções de contact center extremamente poderosas e flexíveis com a Voice API da Vonage. Mas o que acontece se não houver ninguém do outro lado para atender o telefone? Bem, suponho que você poderia simplesmente deixar o telefone tocar ou reproduzir uma mensagem pedindo que liguem mais tarde. Provavelmente, o que a maioria das pessoas faria, inclusive eu, seria registrar a mensagem do cliente na forma de uma mensagem de voz. Com a Voice API da Vonage e nosso SDK .NET, isso é muito fácil de fazer no ASP.NET Core!

Visão geral

Existem várias maneiras de gravar chamadas telefônicas com a Voice API da Vonage. Neste tutorial, usaremos um webhook de atendimento, que retornará um Nexmo Call Control Object (NCCO) contendo uma ação que instrui a Vonage a gravar a chamada e, em seguida, enviar a URL da gravação para o nosso servidor quando a chamada for concluída. Um webhook é simplesmente um endpoint HTTP disponível publicamente ao qual a Vonage acessará para obter instruções ao receber uma chamada.

Ir direto para o código

Se você quiser pular este tutorial e apenas dar uma olhada no código, poderá encontrar todo o código deste tutorial no GitHub.

Pré-requisitos

• Vamos testar isso com ngrok. Siga as instruções deles para configurá-lo.

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

• Vamos precisar do SDK mais recente do .NET Core. Estou usando a versão 3.1 neste tutorial.

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

Configurar a CLI do Nexmo

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

Ao executar este comando, a CLI do Nexmo será configurada e estará pronta para uso.

Executar o Ngrok

Vou colocar tudo no localhost:5000. Executar o ngrok vai nos permitir 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 URL 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.

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

1. O ID do seu aplicativo. Você pode encontrar o ID do seu aplicativo no Painel da Vonage

2. A chave privada do seu aplicativo. Certifique-se de anotá-la e salvá-la em um arquivo — estou chamando a minha 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 vê-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.

Crie seu projeto

Para criar seu projeto:

• Abra o Visual Studio

• Clique em “Criar um novo projeto”

• Selecione o aplicativo web ASP.NET Core

• Clique em “Próximo”

• Dê um nome ao seu projeto: VonageVoicemail

• Clique em “Criar”

• Selecionar API

• Clique em “Criar”

Instalar dependências

A única dependência que isso terá é o Vonage pacote NuGet. Vá em frente e baixe-o usando o método de sua preferência. O que eu faço é acessar o VonageVoicemail.csproje executar:

Criar o controlador

Se você estiver com preguiça, pode aproveitar o WeatherForecastController que já está pré-gerado. Mas, para nossos propósitos, vamos criar um novo controlador clicando com o botão direito do mouse na Controllers pasta -> Adicionar -> Controlador -> Selecionar API Controller - Empty -> clicar em Adicionar -> nomear este VoiceController.

Essas etapas criarão um controlador de API vazio.

Configuração da injeção de dependências

Para isso, precisaremos de acesso à configuração do aplicativo. No VoiceController, declare um objeto IConfiguration e, em seguida, injetar a dependência de um IConfiguration no construtor do controlador.

private readonly IConfiguration _config;

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

Adicionar rota de resposta

Agora que já criamos nosso controlador de API, vamos adicionar uma rota de resposta. Vamos adicionar um Answer no final dessa rota, que criará um NCCO com duas ações:

1. Ele avisará o usuário de que você está indisponível no momento.

2. Uma ação de gravação que será encerrada após 3 segundos de silêncio, emitirá um bipe antes de iniciar a gravação e enviará uma solicitação POST ao final da chamada, contendo as informações da gravação.

[HttpGet]
[Route("webhooks/answer")]
public async Task<string> Answer()
{
   var host = Request.Host.ToString();
   //remove the next line if using ngrok without --host-header option
   host = Request.Headers["X-Original-Host"];
   var sitebase = $"{Request.Scheme}://{host}";

   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.",
       VoiceName = "Joey"
   };

   var recordAction = new RecordAction
   {
       EndOnSilence = "3",
       BeepStart = "true",
       EventUrl = new[] { $"{sitebase}/webhooks/recording" },
       EventMethod = "POST"
   };

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

Importante: host = Request.Headers["X-Original-Host"]; permite que você obtenha a URL de retorno de chamada adequada ao usar o ngrok com a -host-header opção. Remova isso se não estiver usando.

Adicionar rota pós-gravação

Após gravar a chamada, a Vonage enviará uma resposta para você na EventUrl que você forneceu. A partir dessa solicitação POST, extrairemos a URL da gravação. Em seguida, criaremos um cliente de voz a partir de nossas credenciais, que armazenaremos na configuração. Com o cliente de voz, obteremos a gravação e a salvaremos como um arquivo MP3 em nosso disco.

[HttpPost]
[Route("webhooks/recording")]
public IActionResult Recording()
{
   Record record;
   var appId = _config["APP_ID"];
   var privateKeyPath = _config["PRIVATE_KEY_PATH"];
   var credentials = Credentials.FromAppIdAndPrivateKeyPath(appId, privateKeyPath);
   var voiceClient = new VoiceClient(credentials);
   using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
   {
       record = JsonConvert.DeserializeObject<Record>(reader.ReadToEndAsync().Result);
       var recording = voiceClient.GetRecording(record.RecordingUrl);
       System.IO.File.WriteAllBytes("your_recording.mp3", recording.ResultStream);
   }

   Console.WriteLine($"Record event received on webhook - URL: {record?.RecordingUrl}");
   return StatusCode(204);
}

Esse é todo o código em C# de que você vai precisar para isso. Agora, vamos configurar o aplicativo!

Configurar o aplicativo

Há dois tipos de configuração que precisaremos realizar.

1. Adicione as chaves de configuração para APP_ID e PRIVATE_KEY_PATH ao arquivo appsettings.json

2. Atualize as configurações no arquivo launchsettings.json para que o Kestrel/IIS Express escute no http://localhost:5000

Adicionar chaves de configuração

Abra appsettings.json e adicione as chaves APP_ID e PRIVATE_KEY_PATH a ele, utilizando o ID do aplicativo e a chave privada que geramos anteriormente com a CLI. Essas chaves em JSON terão a seguinte aparência:

"APP_ID": "7h15-w111-83-y0u2-4pp-1d",
"PRIVATE_KEY_PATH": "C:\\path\\to\\your\\private.key"

Atualizar o arquivo launchSettings.json

Agora precisamos atualizar o arquivo de configurações de inicialização para que o IIS Express ou o Kestrel fiquem escutando na porta http://localhost:5000. Abra properties/launchSettings.json; se você estiver usando o IIS Express, altere a URL do aplicativo no objeto iisSettings para http://localhost:5000 e defina o sslPort como 0 para desativar o SSL. Se você estiver usando o Kestrel, remova o https://localhost:5001 ponto de extremidade, deixando apenas o http://localhost:5000 ponto de extremidade.

Teste

Isso é tudo o que precisamos fazer antes de executar o aplicativo. Você pode executar o aplicativo no Visual Studio pressionando F5 ou pela linha de comando, executando dotnet run. Se você ligar para o seu número da API da Vonage, a mensagem de saída será reproduzida, a chamada será gravada após o bipe e, ao final da ligação, a gravação será salva no seu disco.

Recursos

• O código deste tutorial está disponível em GitHub.