Verificando a situação do metrô de Londres com a SMS API da Vonage

Hoje vamos criar uma aplicação que nos permitirá verificar o status de uma determinada linha do Metrô de Londres usando a API SMS da Vonage SMS API. Vamos utilizar a API da Transport for London (API da TFL) para obter dados em tempo real sobre o status de uma linha do metrô escolhida pelo usuário. O gatilho será um SMS recebido em nosso número virtual. Parece um bom plano? Então, siga este tutorial. Obteremos o mesmo status que aparece no site deles diretamente no nosso celular por SMS. Isso é especialmente útil se, por algum motivo, você não tiver acesso à internet para consultar o Google Maps/Citymapper ou se tiver excedido seu limite mensal de dados.

O fluxo de trabalho do nosso aplicativo será semelhante ao do diagrama a seguir:

sketch diagram of workflow

Eu sei 😌 que é provável que você não more em Londres e talvez ache que este tutorial não seja relevante para você. No entanto, acredito sinceramente que este seja um exemplo muito ilustrativo do que é possível desenvolver com a Vonage.

Este tutorial irá guiá-lo por todas as etapas para criar este aplicativo do zero. No entanto, se você preferir obter o repositório já pronto, não deixe de dar uma olhada nele!

Pré-requisitos

Para a primeira parte do tutorial, vamos precisar de:

• Conhecimentos básicos de JavaScript/Node.js.

• Você precisará usar o ngrok para expor seu servidor local à internet, para que a Vonage possa acessá-lo. Temos um tutorial detalhado sobre isso.

Se você quiser implantar seu aplicativo no Heroku, também precisará de:

• A Account no Heroku (usaremos apenas o plano gratuito).

• Algumas noções básicas comandos do Git para implantar nosso aplicativo no Heroku.

Configurando nosso projeto

Crie uma pasta de projeto chamada tubestatus no seu computador e acesse essa pasta.

mkdir tubestatus && cd tubestatus

Vamos criar nosso arquivo principal, onde armazenaremos nosso código. Também criaremos nosso .env arquivo onde armazenaremos nossas credenciais da Vonage, bem como algumas outras variáveis.

O próximo passo é criar o package.json arquivo.

Vamos instalar e salvar as dependências necessárias.

Agora precisamos criar um aplicativo da Vonage e comprar um número.

Instale a CLI do Vonage globalmente com este comando:

npm install @vonage/cli -g

Em seguida, configure a CLI com sua chave e seu segredo da API da Vonage. Você pode encontrar essas informações no Painel do Desenvolvedor.

vonage config:set --apiKey=VONAGE_API_KEY --apiSecret=VONAGE_API_SECRET

Vamos executar o ngrok na mesma porta em que nosso servidor local está escutando (no meu caso, 3000).

ngrok http 3000

Agora, use a CLI para criar uma aplicação Vonage e configure um webhook para a sua URL do ngrok.

É bom você anotar esse ID que aparece impresso depois Application created:. Você vai precisar dele daqui a pouco.

Agora você precisa de um número para poder receber chamadas. Você pode alugar um usando o comando a seguir (substituindo o código do país pelo seu). Por exemplo, se você estiver nos EUA, substitua GB por US:

Agora, vincule o número ao seu aplicativo:

vonage apps:link --number=VONAGE_NUMBER APP_ID

Por fim, preencha o .env arquivo com a chave da API da Vonage para apiKey, o segredo da Vonage para apiSecrete o número que você acabou de adquirir para from. Em seguida, adicione seu TFL app_id e app_key.

Vamos começar com a parte divertida

Como sempre, vamos importar todas as dependências no início do nosso projeto. Usaremos o express framework para construir nosso aplicativo. Vamos usar a dotenv biblioteca para trabalharmos com variáveis de ambiente. Usaremos body-parser para analisar as solicitações recebidas do servidor da Vonage. Para as solicitações à API da TFL, escolhi a request biblioteca , pois a considero bastante simples, mas você pode usar qualquer outra, como axios. Por último, e o mais importante, 😊 precisamos da biblioteca da Vonage para enviar o status da linha de volta ao usuário.

Cole o código a seguir no arquivo recém-criado. Importamos todas as dependências instaladas e definimos uma variável que contém todos os nomes de linhas aceitos fornecidos pela API do TFL. Não queremos enviar uma solicitação à API do TFL se o usuário não fornecer um nome de linha válido (explicarei daqui a pouco por que todos os valores estão em maiúsculas). A variável chamada status conterá qualquer status relevante em relação ao status da referida linha. Além disso, adicione as diferentes credenciais necessárias para utilizar as APIs da Vonage e da TFL, respectivamente. Elas serão recuperadas do .env arquivo:

const Vonage = require('@vonage/server-sdk')
const express = require('express');
const bodyParser = require('body-parser');
const port = process.env.PORT || 3000;
const request = require('request');
const dotenv = require('dotenv');

let status = []

dotenv.config();

const lines =['CENTRAL','BAKERLOO', 'DISTRICT', 'VICTORIA', 'NORTHERN', 'CIRCULAR', 'HAMMERSMITH-CITY', 'JUBILEE', 'METROPOLITAN', 'PICCADILLY', 'WATERLOO-CITY' ];

const vonage = new Vonage({
  apiKey: process.env.apiKey,
  apiSecret: process.env.apiSecret
})

Nas linhas a seguir, estamos iniciando nosso aplicativo e definindo alguns middlewares básicos. Observe que definimos a porta 3000 para o nosso servidor ficar à escuta, mas você pode escolher outra. Leve em conta que há um espaço em branco (comentado) que será preenchido com nossa rota para as solicitações recebidas:

const app = express();

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended:true}));

//We will define our route here

app.listen(port, ()=>{console.log('App listening in port ', port)});

Vamos definir duas funções para organizar um pouco melhor o código. A primeira função sendSms() receberá dois parâmetros: o número de telefone do usuário e o texto a ser enviado de volta ao usuário. Vamos reutilizar um pouco do código.

function sendMessage(to, message){
  vonage.message.sendSms(process.env.from, to, message, (err, responseData) => {
    if (err) {
        console.log(err);
    } else {
        if(responseData.messages[0]['status'] === "0") {
            console.log("Message sent successfully.");
        } else {
            console.log(`Message failed with error: ${responseData.messages[0]['error-text']}`);
        }
    }
})
}

A segunda função checkLineStatus() receberá dois parâmetros: o nome da linha e o número de telefone do usuário, já que enviaremos uma mensagem de volta ao usuário com as informações solicitadas.

function checkLineStatus(Line, number) {

    var options = {
        json: true,
        url: 'https://api.tfl.gov.uk/Line/' + Line + '/status?app_id=' + app_id + '&app_key=' + app_key,
    }

    request(options, function (err, res, body) {
        if (err) {
            console.log(err)

        }
        else {
            if (body[0].lineStatuses[0].statusSeverityDescription === 'Good Service') {
                sendMessage(number, 'There is a ' + body[0].lineStatuses[0].statusSeverityDescription + ' operating on ' + body[0].name + ' line')

            }
            else {
                for (let i = 0; i < body.length; i++) {
                    for (let j = 0; j < body[i].lineStatuses.length; j++) {
                        status.push(body[i].lineStatuses[j].reason)
                    }
                }
                sendMessage(number, status)
                console.log(status)
            }
        }
    })
}

Se o status da linha em questão for “Serviço em bom funcionamento” (Observe que a API da TFL sempre retornará isso quando o serviço estiver funcionando normalmente), envie essa informação de volta ao usuário. Caso contrário, é importante levar em conta que, quando houver uma interrupção na linha, a API da TFL fornecerá um reason dentro do lineStatus objeto. É isso que estamos inserindo em nosso array para cada interrupção ocorrida (espero que não haja nenhuma, para o bem dos passageiros 😂). Não se esqueça de que, dentro dessa função, também estamos chamando a sendSms() função para retornar o status da linha ao usuário em ambos os cenários.

Por fim, vamos configurar nossa rota de entrada para receber as mensagens enviadas pelos usuários. Vamos dar uma olhada em como é uma mensagem recebida da Vonage.

Para atingir nosso objetivo, precisaremos armazenar dois dos parâmetros acima: o texto enviado pelo usuário (nome da linha) e o número do usuário. Esses dados serão armazenados em nossas novas variáveis (Tube_line e Number_msisdn respectivamente) assim que nossa /inbound rota for acionada.

É importante observar que estamos colocando a linha “tube” em maiúsculas. A razão para isso é que queremos comparar uma String específica com outra String, ignorando as diferenças entre maiúsculas e minúsculas (o usuário pode nos enviar Central, CENTRAL ou central). Ao colocar em maiúsculas a entrada do usuário e compará-la com nossa lines array (já em maiúsculas), conseguimos contornar esse problema. Adicione o código a seguir no espaço que reservamos para nossa rota.

app.post('/inbound', (req, res) => {
    let Tube_Line = req.body.text.toUpperCase()
    let Number_msisdn = req.body.msisdn

    if ((lines.indexOf(Tube_Line) > -1)) {
        checkLineStatus(Tube_Line, Number_msisdn)
    }
    else {
        sendMessage(Number_msisdn, 'Valid values are ' + lines)

    }

    res.status(204).send()
})

O (lines.indexOf(Tube_Line) > -1) bit nos permitirá verificar se o valor armazenado em Tube_line corresponde a algum dos valores na lines matriz. Esse método retorna o primeiro índice em que o item fornecido pode ser encontrado na matriz ou -1, caso ele não esteja presente na matriz. Queremos verificar o status de uma determinada linha apenas se a entrada corresponder a algum dos valores válidos. Caso contrário, receberemos um belo código de erro HTTP 404 da API do TFL. Supondo que sejamos gentis o suficiente para informar ao usuário que ele inseriu um valor incorreto, enviaremos a ele uma mensagem com os valores válidos. Isso é feito quando o método `indexOf` é igual a -1, conforme explicado acima.

Tudo bem, é hora de testar isso 🙈. Vamos pegar nosso celular e enviar um SMS com qualquer nome de linha que corresponda à nossa lines matriz para o seu número da Vonage. Por exemplo, vou consultar o nome da linha que me leva ao trabalho todos os dias.

demo of app performance on phone

💃💃 Como você pode ver, logo após enviarmos uma mensagem para o nosso número virtual configurado anteriormente, recebemos um SMS com o status da linha solicitada. Muito bem e obrigado por ter seguido o passo a passo até aqui!

Simulação de mensagens recebidas

Se, por algum motivo, você não tiver a possibilidade de usar seu celular ou não quiser enviar SMS manualmente para testar o aplicativo, também temos uma solução para você. Uma mensagem recebida é representada simplesmente como uma solicitação GET ou POST para o seu webhook. Você pode definir qual método deseja que a Vonage use para entregar suas mensagens recebidas nas Configurações do Painel da Vonage. Estou usando POST para este tutorial.

Levando isso em conta, podemos simular o comportamento de uma mensagem recebida acessando manualmente nosso servidor local exposto via ngrok para verificar se o aplicativo funciona como deveria. Vou usar o POSTMAN , mas fique à vontade para usar qualquer outro serviço de sua preferência. Vamos fazer uma solicitação POST para o nosso webhook de entrada, definindo um corpo JSON bruto genérico (como aquele que a Vonage enviaria para uma mensagem recebida). No entanto, lembre-se de alterar o msisdn para que nosso aplicativo saiba para onde responder. Além disso, substitua o text para testar diferentes valores de nome de linha; você pode digitar propositalmente um valor inválido para receber uma mensagem contendo os valores permitidos. Minha solicitação de API fica mais ou menos assim:

Nesse caso, o to parâmetro não é relevante, então eu o defini com um valor aleatório. É importante adicionar o Content-Type header e defini-lo como application/json para que nosso aplicativo saiba como lidar com esses dados. Como você pode ver no canto inferior direito, nosso aplicativo retorna um HTTP 204, conforme definido em nossa /inbound rota por meio de res.status(204).send()

E agora? Vamos fazer a implantação no Heroku

O Heroku é uma plataforma destinada a facilitar a implantação de sua aplicação web e a dimensionar seus serviços de acordo com suas necessidades. Eles também oferecem alguns complementos úteis para simplificar algumas tarefas diárias. Vamos utilizar o Heroku, pois ele é bastante fácil de usar e a documentação é excelente no site do Heroku. Ao usar o Heroku, podemos evitar o trabalho de alugar e configurar nosso servidor.

O conceito de dynos existe na plataforma do Heroku. Trata-se simplesmente de um contêiner onde sua aplicação será implantada. O uso da sua aplicação consumirá horas de dyno (apenas quando ela estiver em execução), mas não se preocupe, pois eles oferecem 550 horas gratuitas por mês por padrão ou 1.000 horas caso você concorde em Verify sua conta fornecendo um cartão de crédito. Você pode facilmente aumentar ou reduzir a escala do seu aplicativo levando em conta a demanda de tráfego, mas isso está fora do escopo deste tutorial.

Se você nunca implantou um aplicativo no Heroku, talvez valha a pena dar uma olhada na documentação deles ou, pelo menos, ler a parte em que explicam como implantar um aplicativo Node.js. Para determinar como iniciar seu aplicativo, o Heroku procura primeiro por um arquivo Procfile. Esse é um arquivo que especifica os comandos executados pelo aplicativo na inicialização. Se não houver um Procfile para um aplicativo Node.js, o Heroku tentará iniciar um processo web padrão por meio do script de inicialização no seu package.json.

Vamos editar nosso package.json, de modo que a parte que contém os propriedade tenha esta parte incluída:

"scripts": {
    "start": "node server.js"
  },

Em seguida, vamos criar um .gitignore arquivo para garantir que as variáveis de ambiente locais, as saídas relacionadas à compilação e os módulos não sejam enviados para o repositório do Git

/node_modules
npm-debug.log
.DS_Store
/*.env

A única desvantagem de usar o plano gratuito é que, quando o aplicativo fica inativo por 30 minutos, pode demorar um pouco até que ele seja reativado (ao receber uma nova solicitação). Na prática, isso significa que podemos observar um leve atraso ao receber a resposta da Vonage se o aplicativo estiver inativo há algum tempo. Isso ocorre porque a solicitação à API TFL só será processada assim que o aplicativo for reiniciado. Isso é aceitável, já que este aplicativo não é sensível ao tempo. No entanto, se você achar que isso não é suficiente, pode migrar para o serviço pago e ter um dyno dedicado em execução para o seu aplicativo.

Para determinar como iniciar seu aplicativo, o Heroku procura primeiro por um arquivo Procfile. Se não houver nenhum arquivo Procfile para um aplicativo Node.js, o Heroku tentará iniciar um processo web padrão por meio do script de inicialização contido no seu package.json. O comando em um processo do tipo web deve se conectar ao número de porta especificado na variável de ambiente PORT. Caso contrário, o dyno não será iniciado.

Verifique novamente se você tem o CLI do Heroku instalada e, em seguida, execute os seguintes comandos na pasta do seu projeto, um por vez:

Neste momento, já criamos um novo repositório Git, adicionamos todas as alterações ao nosso repositório e enviamos nosso primeiro commit. Vamos agora criar nosso aplicativo e implantá-lo no Heroku:

Nessas poucas linhas, criamos nosso aplicativo no Heroku e enviamos as alterações para o Heroku. Se tudo correu como esperado, você já deve ter seu próprio aplicativo criado. Eles também fornecerão a URL onde seu aplicativo poderá ser acessado assim que for implantado. Muito bem!

Por fim, precisamos informar ao nosso aplicativo onde encontrar as variáveis de ambiente, já que não fornecemos nenhuma .env file. Execute este comando para definir as variáveis de configuração necessárias

Você pode verificar se essas variáveis foram adicionadas corretamente consultando as configurações do seu aplicativo em Painel do Heroku. É assim que nosso aplicativo aparece no painel do Heroku. Se clicarmos em Revelar variáveis de configuração, veremos as variáveis de ambiente configuradas por meio da CLI do Heroku.

Concluindo, esse processo foi relativamente simples! Consegui colocar tudo em funcionamento em questão de poucos minutos, o que é excelente. Agora, basta atualizar nosso número para que ele aponte para o nosso novo webhook; basta repetir as etapas acima (quando configuramos nosso número por meio da API do Numbers). Lembre-se de incluir o /inbound no final da URL, de acordo com a rota em nosso script.

Espero que, se enviarmos um SMS depois de atualizarmos a URL do webhook de entrada para o nosso número, isso funcione como esperado. É assim que se apresenta um status de interrupção. Parece que teria sido necessário reprogramar nossa viagem se estivéssemos indo para Heathrow pela Linha District no momento em que eu estava testando isso.

Por hoje é só, mas se você quiser continuar explorando nossas APIs, talvez os links a seguir sejam úteis:

• Documentação sobre as diferentes APIs no portal do desenvolvedor

• Série de tutoriais sobre várias APIs da Vonage

• Se precisar de nós, experimente o canal da Comunidade Vonage no Slack

• Compartilhe sua opinião conosco enviando um tweet para @VonageDev