Como lidar com entradas do teclado do aparelho (DTMF) durante uma chamada telefônica no ASP.NET Core

O elemento fundamental de qualquer sistema de Resposta Interativa de Voz (IVR) é o processamento de entradas. Geralmente, existem dois tipos de entradas que podem ser obtidas programaticamente a partir de uma Rede Telefônica Pública Comutada (PSTN), sendo que ambas são compatíveis com a Vonage:

1. Multifrequência de Dois Tons (DTMF)— esses são eventos de entrada coletados do aparelho do usuário. Por exemplo: “digite 1 para vendas, 2 para atendimento ao cliente”

2. Reconhecimento Automático de Fala (ASR)— trata-se de eventos de reconhecimento de fala em que a entrada é a voz do usuário.

Neste tutorial, vamos usar a Voice API da Vonage para aprender como integrar rapidamente o DTMF em nossas aplicações ASP.NET Core. A coleta de DTMF de um usuário por meio de uma chamada PSTN envolverá o seguinte:

1. Configurando uma Account da API da Vonage , caso você ainda não tenha uma.

2. Criação de uma aplicação Vonage usando o CLI.

3. Escreva um código em C#.

4. Conecte nosso aplicativo à web.

Ir direto para o código

Se você quiser pular este tutorial e baixar um exemplo pronto para uso, pode encontrá-lo em GitHub.

Pré-requisitos

• O CLI da Vonage. Se você ainda não o tiver, pode instalá-lo com npm install @vonage/cli -g

• A versão mais recente SDK do .NET Core

• Visual Studio ou Visual Studio Code. Vou usar o Visual Studio 2019

• ngrok para testes. Você só precisa do plano gratuito.

Account da API da Vonage

Para concluir este tutorial, você precisará de uma Account na API da Vonage. Se você ainda não tiver uma, pode se cadastrar hoje mesmo e começar a desenvolver com crédito gratuito. Assim que tiver um Account, você poderá encontrar sua chave de API e seu segredo de API na parte superior do Painel da API da Vonage

Iniciar o ngrok

Vamos usar o ngrok para expor à internet nossa aplicação ASP.NET Core em execução local. Depois de instalar o ngrok, basta executar o comando ngrok http 5000 no seu console. Isso gerará algo parecido com isto:

ngrok

NOTA: Este tutorial utiliza o Kestral para depuração local. Se você preferir usar o IIS Express, consulte nosso guia explicativo sobre como usar o ngrok com o IIS Express.

O ponto fundamental a ser observado aqui é a URL de redirecionamento — no meu caso, essa URL é http://34332d9dca30.ngrok.io. Quando você receber uma chamada no seu número da Vonage, a Vonage enviará ao seu aplicativo o que é chamado de WebHook, que é apenas uma solicitação HTTP GET, solicitando algo chamado Objeto de Controle de Chamada (NCCO). Nosso aplicativo ficará à espera em /webhooks/answer , portanto, a URL completa de que vou precisar será http://34332d9dca30.ngrok.io/webhooks/answer.

Configuração da CLI

Se você ainda não configurou a CLI da Vonage, faça isso executando o comando vonage config:set <api_key> <api_secret> onde “API Key” e “Secret” são a chave e o segredo da API encontrados na página de configurações da sua conta

Compre um número e crie um aplicativo

Agora que sua CLI está configurada, vamos adquirir um número, criar uma Application da Vonage e vincular o número a essa Application, o que fará com que a Vonage encaminhe as chamadas para o seu aplicativo.

Compre um número

Para comprar um número, use o seguinte comando (substituindo o ID do seu país por US)

Digite confirm para concluir a operação; será exibido o número que você comprou.

Criar um aplicativo

A seguir, vamos criar uma aplicação. O comando “create application” aceita duas URLs: a URL de resposta — que será o número para o qual a Vonage encaminhará as chamadas recebidas — e a URL de evento, que será a URL para a qual a Vonage enviará os eventos gerados por um de seus números. Lembre-se de substituir 34332d9dca30 pelo hash aleatório da sua URL do ngrok:

Essa operação retornará um ID de aplicativo e uma chave privada. Salve esses dois valores. Neste tutorial, usaremos apenas o ID do aplicativo, mas você utilizará a chave privada para autorizar as solicitações do seu aplicativo.

Vincular o aplicativo

Em seguida, precisamos vincular nosso número recém-adquirido ao nosso aplicativo. Ao vincular nosso número, a Vonage será instruída a encaminhar todas as chamadas recebidas nesse número para a URL do webhook do nosso aplicativo. Para isso, precisaremos do ID do aplicativo que acabamos de receber da solicitação de criação do aplicativo (que terá o formato e7a25242-77a1-42cd-a32e-09febcb375f4) e o número de telefone que acabamos de adquirir, e executaremos um comando semelhante a este:

Crie nosso aplicativo

Agora só falta criar nosso aplicativo!

Criar o aplicativo

No seu terminal, acesse o diretório onde você costuma guardar seus códigos. Vamos criar um Web API aplicativo ASP.NET Core. Não vamos configurá-lo https, o que facilitará os testes. Você pode gerar a estrutura facilmente com o seguinte comando da CLI do dotnet:

Instale o SDK da Vonage

Execute o comando `cd` para acessar a VonageDtmf pasta do projeto e execute o comando a seguir para adicionar o SDK do Servidor Vonage ao seu projeto.

Criar o controlador de voz

Navegue até o diretório criado e abra o arquivo csproj no seu IDE de sua preferência. Na Controllers pasta, adicione um novo controlador de API vazio chamado VoiceController. No VoiceController, vamos adicionar, além do código padrão do ApiController, instruções using para System.Threading.Tasks, Vonage.Utility, Vonage.Voice.EventWebhookse Vonage.Voice.Nccos. Depois disso, o controlador deverá ficar assim.

using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;
using Vonage.Utility;
using Vonage.Voice.EventWebhooks;
using Vonage.Voice.Nccos;

namespace VonageDtmf.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class VoiceController : ControllerBase
    {
    }
}

Lidar com uma resposta

Agora vamos adicionar nossa rota para /webhooks/answer. Essa rota será uma solicitação GET, já que a Vonage irá obter um NCCO do nosso servidor. Esse método irá construir um NCCO com duas ações (que são instruções para a chamada). A primeira ação será uma ação de fala, que solicitará ao usuário que digite um dígito. Em seguida, a segunda ação será uma ação MultiInput. Essa ação coletará a entrada do usuário. Você pode especificar se deseja coletar entrada DTMF e/ou de voz com essa ação. Selecionaremos DTMF adicionando um DtmfSettings objeto à ação e definindo seu número máximo de dígitos como 1. Passaremos a ele a URL do evento — que será a URL base do nosso servidor em /webhooks/dtmf (definiremos essa rota em breve). Por fim, transformamos essas ações em um NCCO e retornamos o JSON dessa ação para a Vonage.

[Route("/webhooks/answer")]
[HttpGet]
public ActionResult Answer()
{
    var responseUrl = $"{Request.Scheme}://{Request.Host}/webhooks/dtmf";
    var talkAction = new TalkAction
    {
        Text = "Hello please enter a digit.",
        BargeIn = "true"
    };
    var inputAction = new MultiInputAction
    {
        Dtmf = new DtmfSettings { MaxDigits = 1 },
        EventUrl = new[] { responseUrl },
        EventMethod = "POST"
    };
    var ncco = new Ncco(talkAction, inputAction);
    return Ok(ncco.ToString());
}

Tratamento da entrada DTMF

Quando o usuário digitar um dígito no aparelho, nosso aplicativo receberá outro webhook da Vonage contendo os dígitos digitados pelo usuário. Extrairemos a MultiInput estrutura da solicitação. Em seguida, usaremos os dígitos contidos no Dtmf objeto dentro dessa estrutura para criar uma nova Talk Action e informar ao usuário qual foi a entrada digitada.

[Route("/webhooks/dtmf")]
[HttpPost]
public async Task<ActionResult> Dtmf()
{
    var input = await WebhookParser.ParseWebhookAsync<MultiInput>
        (Request.Body, Request.ContentType);
    var talkAction = new TalkAction
    {
        Text = $"Thank you for inputting: {input.Dtmf.Digits}"
    };
    var ncco = new Ncco(talkAction);
    return Ok(ncco.ToString());
}

Teste o aplicativo

Agora, só falta testar o aplicativo. Para executá-lo, use o seguinte comando:

NOTA: Se você optar por executar com o IIS Express, certifique-se de ler nosso artigo sobre uso do IIS Express com o ngrok. Certifique-se de que, no seu método de resposta, você use o cabeçalho `x-original-host` para formar o nome do host, em vez do `Request Host`.

Agora que nosso aplicativo está em execução, você pode ligar para o seu número da Vonage, e pronto! Você pode receber entradas DTMF do seu usuário.

E agora?

A capacidade de gerenciar entradas DTMF do usuário e responder a elas pela linha PSTN permite que você crie todos os tipos de integrações poderosas com Voice. Confira nosso guia sobre Resposta Interativa de Voz (IVR).

Você também pode conferir algumas outras integrações de voz legais das quais já falei, envolvendo voz e .NET, incluindo:

• Transmissão de áudio durante uma chamada

• Criação de um aplicativo de correio de voz

Recursos

• Uma cópia do projeto criado por esta postagem do blog pode ser encontrada em GitHub.