Como lidar com entradas do usuário no ASP.NET Core

Este é o quarto tutorial da série sobre como usar Voice APIs com ASP.NET. No tutorial anterior, aprendemos como receber uma chamada telefônica com a Voice API da Vonage, o ASP.NET Core e o NancyFX. Esse é um ótimo começo, mas, em um cenário real, esperamos algum tipo de interação com quem está ligando. Talvez a pessoa seja solicitada a escolher uma opção ou digitar um PIN. Precisamos de uma maneira de lidar com as entradas do usuário.

Esse é exatamente o objetivo deste tutorial; vamos criar um aplicativo ASP.NET que processe chamadas de voz recebidas e responda às entradas do usuário usando a Voice API da Vonage.

Objetivos de aprendizagem

Neste tutorial, vamos:

• Crie um aplicativo ASP.NET Core.

• Use o NancyFX com o ASP.NET Core.

• Crie uma aplicação de voz da Vonage.

• Receba chamadas recebidas dentro do aplicativo.

• Criar e devolver os NCCOs.

• Processar as entradas do usuário.

• Execute e teste o código usando o Ngrok.

Pré-requisitos

• Visual Studio 2017.

• Uma configuração de projeto para esta série de tutoriais, que você pode encontrar no GitHub.

• Opcional: O CLI da Vonage.

Configuração

Para usar a Voice API da Vonage, precisamos criar um aplicativo de voz. As etapas de configuração estão detalhadas na postagem “Voice API da Nexmo com ASP.NET: Antes de começar”. Assim que a configuração for concluída com sucesso, estaremos prontos para receber uma chamada e processar as entradas do usuário com a Voice API da Vonage!

Recebendo uma chamada telefônica e processando entradas com o ASP.NET

Quando uma chamada é recebida, a Voice API da Vonage enviará uma solicitação ao seu aplicativo para determinar como responder. Nesta postagem, usaremos a função de conversão de texto em fala para cumprimentar o chamador e a input ação para coletar a entrada DTMF do chamador.

DTMF (Dual Tone Multi Frequency) é uma forma de sinalização utilizada por sistemas telefônicos para transmitir os dígitos 0-9 e os * e # caracteres. Normalmente, quem liga pressiona essas teclas no teclado do telefone, e o aparelho gera um tom composto por duas frequências reproduzidas simultaneamente (daí o nome “Dual Tone”).

Para capturar sinais DTMF em nosso aplicativo, vamos usar o NancyFX em conjunto com nosso projeto ASP.NET Core. Primeiro, precisamos adicionar o Nancy ao nosso projeto:

PM> Install-Package Nancy
PM> Install-Package Microsoft.AspNetCore.Owin

Para que o Nancy possa processar quaisquer solicitações HTTP, precisamos configurar o ASP.NET Core para usar o Nancy por meio de Owin no Configure método de Startup.cs.

using Microsoft.AspNetCore.Builder;
using Nancy.Owin;

namespace NexmoVoiceASPNetCoreQuickStarts
{
    public class Startup
    {
        public void Configure(IApplicationBuilder app)
        {
            app.UseOwin(x => x.UseNancy());
        }
    }
}

O próximo passo é criar um módulo do Nancy no qual configuraremos uma rota para /webhook/answer que responderá com o ncco retornado por GetDTMFNCCO()

using Nancy;
using Newtonsoft.Json.Linq;

namespace NexmoVoiceASPNetCoreQuickStarts
{
    public class VoiceModule : NancyModule
    {
        public VoiceModule()
        {
            Get["/webhook/answer"] = x => GetDTMFNCCO();
        }

        private string GetDTMFNCCO()
        {
            dynamic TalkNCCO = new JObject();
            TalkNCCO.action = "talk";
            TalkNCCO.text = "Hello. Please press any key to continue.";

            JArray jarrayObj = new JArray();
            jarrayObj.Add(TalkNCCO);

            dynamic InputNCCO = new JObject();
            InputNCCO.action = "input";
            InputNCCO.maxDigits = "1";
            InputNCCO.eventUrl = $"{Request.Url.SiteBase}/webhook/dtmf";

            jarrayObj.Add(InputNCCO);

            return jarrayObj.ToString();

        }
    }
}

O código acima fará o seguinte:

Quando uma chamada é recebida, a Vonage solicita que o usuário pressione qualquer tecla, lendo a mensagem “Olá. Por favor, pressione qualquer tecla para continuar.” Quando o usuário pressiona uma tecla, repassamos essa entrada para webhook/dtmf onde será processada adequadamente. Para lidar com o DTMF, precisamos informar ao módulo Nancy como responder assim que a solicitação for recebida. Nesse caso, simplesmente repetiremos para o chamador qual tecla ele pressionou.

public class VoiceModule : NancyModule
{
    public VoiceModule()
    {
        Get["/webhook/answer"] = x => GetDTMFNCCO();
        Post["/webhook/dtmf"] = x => GetDTMFInput();
    }
    private string GetDTMFNCCO()
    {
        dynamic TalkNCCO = new JObject();
        TalkNCCO.action = "talk";
        TalkNCCO.text = "Hello. Please press any key to continue.";

        JArray jarrayObj = new JArray();
        jarrayObj.Add(TalkNCCO);

        dynamic InputNCCO = new JObject();
        InputNCCO.action = "input";
        InputNCCO.maxDigits = "1";
        InputNCCO.eventUrl = $"{Request.Url.SiteBase}/webhook/dtmf";

        jarrayObj.Add(InputNCCO);

        return jarrayObj.ToString();

    }

    private string GetDTMFInput()
    {
        dynamic TalkNCCO = new JObject();
        TalkNCCO.action = "talk";
        TalkNCCO.text = $"You pressed {Request.Query["dtmf"]} ";

        JArray jarrayObj = new JArray();
        jarrayObj.Add(TalkNCCO);

        return jarrayObj.ToString();

    }
}

Pronto! Para testar este aplicativo de exemplo, são necessárias mais algumas etapas de configuração.

Se você acompanhou tudo até aqui, já configurou sua conta da Vonage e criou um aplicativo de voz, conforme mostrado em esta postagem. Precisamos vincular esse aplicativo ao número de telefone da Vonage para o qual vamos ligar. Se você não tiver um número, pode adquirir um usando o painel de controle ou pela CLI:

vonage numbers:search US
vonage numbers:buy <PHONE_NUMBER> US

Da mesma forma que para vincular o número, você pode usar o painel ou a CLI:

vonage link:app --number=PHONE_NUMBER APP_ID

Precisamos informar à Vonage para qual URL enviar uma solicitação quando uma chamada for recebida — isso é chamado de answer_url. No meu caso, essa URL é http://localhost:63286/webhook/answer e está rodando apenas localmente. Para disponibilizar nossa URL de resposta do webhook, usaremos o o Ngrok.

ngrok http 63286

Agora temos uma nova URL (a minha é http://5e18af56.ngrok.io) que pode ser usada como answer_url para o aplicativo de Voice. Atualize seu aplicativo com o novo answer_url. Deve ficar assim http://[id].ngrok.io/webhook/answerPronto! Execute o aplicativo e teste-o ligando para o número da Vonage que você adquiriu.

Saiba mais

Referências e ferramentas da API

• API do aplicativo.

• Voice API.

• Cliente REST da Nexmo para .NET.

Guias de introdução da Vonage para ASP.NET

• Como enviar mensagens SMS com ASP.NET.

• Como receber mensagens SMS com o ASP.NET.

• Como obter um comprovante de entrega de SMS no ASP.NET.

• Como fazer uma chamada telefônica com conversão de texto em fala usando ASP.NET.

• Como reproduzir áudio para quem está ligando no ASP.NET.

• Como receber uma chamada telefônica com a Voice API da Nexmo, ASP.NET Core e NancyFX.

• Introdução às Number Insight APIs e ao ASP.NET.