Como receber um comprovante de entrega de SMS com o Node.js

Introdução

Quando você envia uma mensagem de texto para um número de telefone usando as APIs da Vonage, a resposta HTTP da API pode indicar se a mensagem foi enviada com sucesso enviada. No entanto, ela não informa se a mensagem foi entregue ao destinatário. Felizmente, há um campo no seu Portal do Desenvolvedor da Vonage que permite que você veja quando o status da entrega é alterado por meio de um webhook.

Neste tutorial, você aprenderá como verificar se as mensagens SMS enviadas a partir do seu número virtual foram entregues usando o Node.js.

Se você quiser pular essa parte e simplesmente executar o aplicativo, pode encontrar uma versão totalmente funcional no GitHub.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

• Node.js instalado. O Node.js é um ambiente de execução de JavaScript de código aberto e multiplataforma.

• ngrok - É necessária uma conta gratuita. Essa ferramenta permite que os desenvolvedores exponham um servidor de desenvolvimento local à Internet.

Usando o ngrok para configurar um túnel local

O ngrok é um aplicativo multiplataforma que permite aos desenvolvedores expor um servidor de desenvolvimento local à Internet com o mínimo de esforço. Vamos usá-lo para expor nosso webhook (que criaremos em breve) à Internet pública.

Quando uma mensagem é entregue, a operadora de celular normalmente retorna um Confirmação de Entrega (DLR) à Vonage, informando o status de entrega da sua mensagem. Se você tiver configurado um endpoint de webhook, a Vonage encaminha esse comprovante de entrega para o seu endpoint.

Precisamos configurar o ngrok para criar um túnel local, para que possamos executar nosso código Node.js mais tarde.

Depois de configurar o ngrok e fazer login (novamente, o Account gratuito é suficiente), execute o seguinte comando:

ngrok http 5000

Depois que o ngrok for executado, ele fornecerá um URL de redirecionamento que usaremos como base para nosso Webhook mais adiante neste artigo. O meu é semelhante ao seguinte:

ngrok.png

Anote a URL de redirecionamento, pois vamos usá-la na próxima etapa.

Como ativar os comprovantes de entrega (DLR) no Painel do Desenvolvedor da Vonage

Para usar esse recurso, você precisa criar uma Account de Desenvolvedor da Vonage no portal do desenvolvedor. Se você ainda não tem uma conta, crie uma, pois oferecemos créditos para você começar. Não é necessário cartão de crédito.

Faça login no seu Account da Vonage e acesse Configurações. Role a página para baixo até Configurações de SMS, preencha os webhooks de recibos de entrega (DLR) com a URL de encaminhamento do ngrok e acrescente /receipt, e clique em “Salvar”.

smssettings.png

Sempre que você enviar uma mensagem pelo seu número virtual, será feita uma chamada de webhook de confirmação de entrega para essa URL, o que executará o código na sua máquina local. Vamos escrever um código com Node.js e Express para lidar com isso!

Configuração de um projeto Node.js

Agora que configuramos o ngrok e adicionamos um webhook de confirmação de entrega , vamos ver como devemos configurar nossa aplicação Node.js.

Comece abrindo uma janela de comando/terminal, criando um diretório de trabalho e inicializando um projeto Node.js.

Vamos dar andamento às solicitações com Express e usaremos o body-parser para analisar os corpos das solicitações recebidas. Instale ambos com o seguinte comando:

npm install express body-parser --save

Crie um index.js arquivo, instancie o Express e escute o servidor na porta 5000, já que configuramos o ngrok para essa porta.

const app = require('express')();
const bodyParser = require('body-parser');
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));

Vamos definir o endpoint para a URL do recibo como /receipt.

app
  .route('/receipt')
  .get(handleDeliveryReceipt)
  .post(handleDeliveryReceipt)

Em seguida, defina o função handleDeliveryReceipt da seguinte maneira:

function handleDeliveryReceipt(request, response) {
  const params = Object.assign(request.query, request.body)
  console.log(params)
  response.status(204).send()
}

app.listen(process.env.PORT || 5000)

Em seguida, o aplicativo registrará o recebimento na janela do console.

Executar o aplicativo

Digite o seguinte no prompt do comando/terminal para executar o aplicativo:

node index.js

Tente enviar mensagens de texto do seu número virtual da Vonage para o seu número de celular, a título de teste.

Se sua mensagem tiver sido enviada com sucesso para o seu celular, você deverá receber um comprovante com as informações, incluindo status, messageId, código-de-rede, etc. Essas informações são exibidas no terminal ou no prompt de comando.

Abaixo está um exemplo de como fica o meu:

{
  msisdn: '14259999999',
  to: '18339999999',
  'network-code': '310260',
  messageId: 'c0f9b0a4-f62a-481e-8698-d52231de9047',
  price: '0.00869000',
  status: 'delivered',
  scts: '9992241831',
  'err-code': '0',
  'api-key': '99999999',
  'message-timestamp': '2023-02-24 18:31:15'
}

Observação: nem todas as redes e países oferecem o recurso de comprovante de entrega. Consulte a documentação para obter mais informações.

Conclusão

Agora que você aprendeu a verificar se as mensagens SMS enviadas a partir do seu número virtual foram entregues usando o Node.js, você pode ampliar esse projeto para salvar a resposta em um banco de dados na nuvem ou experimentar nossa Messages API. Além disso, tente enviar uma mensagem de texto quando seu celular estiver desligado para ver os diversos estados do campo .

Se você tiver dúvidas ou sugestões, junte-se a nós no Slack dos desenvolvedores da Vonage ou me envie um tweet no Twitter, e eu entrarei em contato com você. Mais uma vez, obrigado pela leitura, e nos vemos no próximo artigo!