Como receber uma mensagem SMS com o ASP.NET Core MVC e o SignalR

Neste tutorial, vamos aprender como receber mensagens SMS da Messages API da Vonagee exibi-las em um navegador em tempo real. Usaremos o ASP.NET Core MVC para nosso servidor de API e nossa página da web, e utilizaremos o SignalR para nos permitir receber mensagens SMS em tempo real.

Ir direto para o código

Se você quiser apenas baixar o código desta demonstração, ele está disponível na íntegra em GitHub.

Pré-requisitos

• Você precisará de um Account na API da Vonage

• Você precisará da versão mais recente do SDK do .NET Core 3.1

• Você precisará do Visual Studio 2019, do Visual Studio para Mac ou do Visual Studio Code; vou usar o Visual Studio 2019 para esta demonstração

• Opcional: Eu usei o Ngrok para testar esta demonstração

Criar o aplicativo

Abra o Visual Studio e clique em “Criar um novo projeto”, selecione “Aplicativo Web ASP.NET Core” e clique em “Avançar”. Dê um nome ao seu aplicativo. Vou nomear meu aplicativo como “ReceiveSmsAspNetCoreMvc”. Em seguida, clique em “Criar”. Na página seguinte, selecione “Aplicativo Web (Model-View-Controller)” e clique em “Criar”.

Instalar dependências

Como estamos usando o SignalR, há dois tipos de dependências que precisamos adicionar. Primeiro, precisaremos adicionar as dependências dos nossos pacotes NuGet; depois, precisaremos adicionar as dependências dos nossos pacotes de cliente.

Dependências do NuGet

Precisamos instalar dois pacotes do NuGet:

Existem várias maneiras de fazer isso; vou usar apenas a CLI do .NET. Navegue até o diretório do seu projeto e simplesmente execute:

Pacotes do lado do cliente

Como dependemos da biblioteca do SignalR para o lado do cliente, também precisaremos adicioná-la.

No Visual Studio, clique com o botão direito do mouse nos seus projetos wwwrooot vá para Add > Client-Side Library. Isso abrirá uma pequena caixa de diálogo para ajudá-lo a adicionar a biblioteca. Para esta demonstração, usei o seguinte.

• Provedor: unpkg

• Biblioteca: @microsoft/signalr@latest

• Escolha arquivos específicos: Eu selecionei apenas Files/dist/browser/signalr.js e Files/dist/browser/signalr.min.js

• Localização de destino: wwwroot/js/signalr

Depois de preencher o formulário, ele ficará mais ou menos assim:

Adding a Client Side library in Visual Studio

Depois de preencher este formulário, você pode clicar em “Instalar”, e os arquivos necessários serão instalados na pasta wwwroot/js/signalr

Criar um hub de SMS

No funcionamento do SignalR, os navegadores dos clientes se conectam a algo chamado “Hubs”. Os Hubs enviam mensagens do servidor para cada um de seus clientes por meio de qualquer mecanismo disponível. Normalmente, isso é feito por meio de WebSocket, mas também pode ser realizado por meio de Server-Side-Events (SSE) ou Long-Polling. Precisamos criar um Hub em nosso servidor para conectá-lo aos nossos navegadores clientes.

Crie uma nova pasta no seu projeto chamada Hubs. Nessa pasta, crie um novo arquivo em C# SmsHub.cs. Esse arquivo não precisa fazer muita coisa. Ele apenas declarará uma classe que estende a classe Hub. O arquivo deve ficar mais ou menos assim.

using Microsoft.AspNetCore.SignalR;

namespace ReceiveSmsAspNetCoreMvc.Hubs
{
    public class SmsHub : Hub
    {
    }
}

Configurar o middleware

Configurar serviços

Agora precisamos acessar nosso startup.cs arquivo e adicionar os endpoints do SignalR ao nosso middleware. A adição do middleware permitirá que a rota do hub SMS seja ativada e nos possibilitará usar o SignalR em nossos clientes de navegador. Vamos abrir startup.cs e localizemos o ConfigureServices método. Adicione a linha services.AddSignalR(); a este método, o que adicionará o middleware do SignalR ao nosso servidor. Ao concluir nosso ConfigureServices ficará assim:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
    services.AddSignalR();
}

Configurar

Fique em startup.cs e encontre o Configure método. Esse método conterá uma chamada para app.UseEndpoints, que recebe uma função como argumento; dentro dessa função, vamos mapear o SmsHub para o caminho /smsHub. Após concluir a app.UseEndpoints , a chamada ficará assim:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHub<SmsHub>("/smsHub");
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
});

Crie um controlador de SMS

Agora que já organizamos o middleware, precisamos adicionar o método que receberá o SMS da Vonage. Para isso, usaremos um controlador MVC vazio. Clique com o botão direito do mouse na pasta “Controllers” e vá em “Adicionar” → “Controlador”; selecione “Controlador MVC – Vazio” e clique em “Adicionar”. Nomeie-o SmsController e clique em “Adicionar” novamente.

Injetar o contexto do nosso SmsHub

A primeira coisa que precisaremos fazer em nosso SmsController injeta o HubContext para o SmsHub. Declare uma IHubContext propriedade chamada HubContext, e, em seguida, declare um SmsController construtor que receba um IHubContext como argumento e atribua esse parâmetro à HubContext propriedade. Graças à mágica da injeção de dependências, o controlador recebe o contexto do hub no momento da criação.

/// <summary>
/// Allows access to all browser clients subscribed through the /smsHub
/// </summary>
public IHubContext<SmsHub> HubContext { get; set; }

public SmsController(IHubContext<SmsHub> hub)
{
    HubContext = hub;
}

Adicionar um manipulador de SMS recebidas

Agora que temos acesso ao Hub Context, precisamos adicionar uma rota de API para as SMS recebidas. Essa rota será a que a Vonage usará para enviar um webhook ao nosso aplicativo. Esse método receberá a solicitação, extrairá um objeto InboundSms dela e enviará um InboundSms sinal para todos os clientes conectados ao hub. Em seguida, esse método enviará o MSISDN e o texto da mensagem ao usuário. Para referência, o MSISDN é o número de origem da mensagem. Adicione o seguinte ao seu SmsController.

[HttpPost("webhooks/inbound-sms")]
public async Task<IActionResult> InboundSms()
{
    using (var reader = new StreamReader(Request.Body))
    {
        var json = await reader.ReadToEndAsync();
        var inbound = JsonConvert.DeserializeObject<InboundSms>(json);
        await HubContext.Clients.All.SendAsync("InboundSms", inbound.Msisdn, inbound.Text);
    }
    return NoContent();
}

Criar um front-end

Com isso resolvido, só precisamos adicionar uma interface ao nosso aplicativo. Para isso, vamos simplesmente adaptar a Visualização Inicial. Abra /Vies/Home/Index.cshtml e remova a div que contém o texto de boas-vindas; não vamos precisar dela.

A seguir, vamos apenas adicionar algumas importações de scripts. Vamos importar ~/js/sms.js (que vamos criar daqui a pouco) e ~/js/signalr/dist/browser/signalr.js que é a biblioteca do cliente que importamos anteriormente. Basta adicionar essas duas tags e estaremos prontos para continuar.

<a href="http://~/js/signalr/dist/browser/signalr.js">http://~/js/signalr/dist/browser/signalr.js</a>
<a href="http://~/js/sms.js">http://~/js/sms.js</a>

A última coisa que precisamos fazer aqui é adicionar a tabela onde exibiremos as mensagens. Vamos definir apenas duas colunas, From Number e Message - elas corresponderão às Msisdn e ao Text de nossas mensagens SMS recebidas.

<h1>Messages</h1>

<table class="table" id="messageList">
    <thead>
        <tr>
            <th>From Number</th>
            <th>Message</th>
        </tr>
    </thead>
    <tbody>

    </tbody>
</table>

Adicionar o manipulador de eventos do SignalR

A última coisa que precisamos fazer é adicionar um manipulador de eventos para o nosso InboundSms evento. Faremos isso no sms.js arquivo que acabamos de mencionar. Vá em frente e adicione um sms.js arquivo ao /wwwroot/js diretório. Há três coisas que precisamos fazer nesse arquivo.

1. Estabeleça a conexão do SignalR com o smsHub

2. Registre um manipulador de eventos para InboundSms que irá adicionar uma nova linha à nossa lista de mensagens

3. Inicie a conexão do SignalR.

Podemos fazer essas três coisas adicionando o seguinte ao sms.js arquivo.

"use strict";

var connection = new signalR.HubConnectionBuilder().withUrl("/smsHub").build();

connection.on("InboundSms", function (fromNumber, text) {
    var rowHtml =
        '<tr><td>' +
        fromNumber +
        '</td><td>' +
        text +
        '</td></tr>';
    $('#messageList tbody').append(rowHtml);
});

connection.start()
    .then(function () {
        console.log("connection started");
    })
    .catch(function (err) {
        console.log("Error encountered: " + err);
    })

Testes

Do ponto de vista do desenvolvimento, isso é tudo o que precisávamos fazer; então, vamos seguir em frente e passar para os testes. Vamos testar isso com o Ngrok para testar essa demonstração. O Ngrok nos permite criar um túnel acessível ao público para nosso aplicativo, o que é útil quando precisamos expor pontos de extremidade HTTP acessíveis ao público em nossos aplicativos. Se você for testar isso com o IIS Express, como eu, vale a pena conferir nosso guia explicativo sobre o assunto , pois há considerações especiais. Resumindo, precisamos adicionar uma --host-header opção ao iniciar o ngrok.

No Visual Studio, clique com o botão direito do mouse no arquivo csproj e acesse as propriedades. Lá, clique na guia “Depuração”. Por conveniência, durante os testes, vamos desmarcar a caixa de seleção “Ativar SSL”. Anote a URL do aplicativo e o número da porta que aparece no final dela.

The IIS configuration screen

Iniciar o Ngrok

A seguir, vamos iniciar o ngrok. Vamos direcionar as solicitações recebidas para a porta indicada na URL do nosso aplicativo, e faremos com que o host e a porta substituam o cabeçalho “host” das solicitações recebidas. Inicie o ngrok executando o seguinte comando em um novo terminal (substitua o número da porta pelo seu).

Esse comando fará com que o ngrok assuma o controle do seu terminal. Ele exibirá uma URL; ao acessá-la, as solicitações serão redirecionadas para o seu servidor local. Essa URL terá o formato http://randomhash.ngrok.io. Meu hash aleatório foi d98024d97b04, portanto, no restante deste guia, basta substituir esse valor pelo valor gerado para o seu caso.

Running Ngrok to give local access to our application

Depois de iniciar meu aplicativo no IIS Express, posso acessar minha URL do ngrok para verificar se ela está disponível publicamente.

Configurar Webhooks

Se você se lembra, anotamos nosso InboundSms método em nosso SmsController com [HttpPost("webhooks/inbound-sms")] isso estabelece uma rota para que eu http://d98024d97b04.ngrok.io/webhooks/inbound-sms fazer a chamada para o inbound-sms. A última coisa que preciso fazer antes de começar a testar é informar à Vonage para onde enviar minhas mensagens SMS, para a URL que acabei de mencionar.

Para fazer isso, vamos acessar ${CUSTOMER_DASHBOARD_URL}/settings. Na seção “Configurações padrão de SMS”, defina o campo “Mensagens recebidas” com essa URL e altere o método HTTP para POST-JSON. Clique em “Salvar alterações” e estamos prontos para testar. Acesse sua página inicial e envie uma mensagem de teste para o seu número virtual da API da Vonage. Se você não souber qual é o seu número virtual da Vonage, poderá encontrá-lo no seu painel, na seção “Numbers”. Após enviar a mensagem ao servidor, você verá as mensagens SMS chegarem ao seu servidor em tempo real ao acessar a página da web associada ao aplicativo.

Incoming SMS messages being displayed on the screen in the application we built

E isso é tudo o que precisamos fazer para receber mensagens e exibi-las em tempo real!

Recursos

• Todo o código desta demonstração pode ser encontrado em GitHub