Como enviar e receber mensagens SMS com o Node.js

Este artigo foi atualizado em junho de 2025.

Introdução

A Messages API da Vonage permite que você envie e receba mensagens por SMS, MMS, Facebook Messenger, Viber, WhatsApp e, agora, até mesmo por RCS! Assim, você pode se comunicar com seus clientes pelo canal que eles mais gostarem.

Neste artigo, vamos nos concentrar em como enviar e receber mensagens SMS com Node.js e Express.

Para começar, faremos a implementação mais simples da API e enviaremos uma mensagem SMS usando o Node.js e a Messages API da Vonage.

A seguir, vamos criar um Webhook capaz de receber mensagens SMS do seu celular usando o Express e executar uma ação assim que a mensagem de texto for recebida.

Por fim, vamos apresentar algumas medidas que você pode tomar para ampliar a funcionalidade do aplicativo.

Você pode consultar a documentação para obter mais detalhes.

Pré-requisitos

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

• A Account da API da Vonage

  Abra sua página de configurações da API para acessar sua chave e seu segredo da API da Vonage, ambos exibidos conforme mostrado na captura de tela abaixo. A chave da API está localizada na parte superior da página e, para acessar seu segredo da API, consulte a subseção “Segredo da Account”. 

  Observação: caso você não se lembre do seu segredo de API criado anteriormente, clique em “+ Criar novo segredo” e guarde-o em um local seguro.

  

• 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.

• CLI do Vonage - Depois que o Node.js estiver instalado, você pode usar npm install -g @vonage/cli para instalá-lo. Essa ferramenta permite que você crie e gerencie suas Applications Vonage.

Como enviar um SMS com o Node.js

Na primeira parte deste tutorial, vamos abordar como enviar mensagens de texto com o Node.js. Usaremos a Messages API da Vonage para trabalhar com o Node.js e processar mensagens SMS. Para enviar um SMS com o Node.js e a Messages API da Vonage, siga estas etapas:

1. Instale o SDK do Vonage para Node.js

2. Executar o ngrok

3. Criar um aplicativo com suporte a SMS

4. Enviar a mensagem SMS

1. Instale o SDK do Vonage para Node.js

Com a Messages API, é fácil enviar um SMS usando o Node.js. Para utilizá-la, precisaremos instalar o SDK do Vonage para Node.js.

npm install @vonage/server-sdk

Embora a Vonage disponha de duas APIs diferentes capazes de enviar e receber SMS, você só pode usar uma de cada vez, pois isso alterará o formato dos webhooks que você recebe.

Certifique-se de que a Messages API esteja definida como padrão em Chaves de APIe, em seguida, nas Configurações de SMS da sua conta.

Set Messages API as the default API for sending SMS messages Altere a configuração para Messages APIe, em seguida, pressione Salvar alterações.

2. Execute o ngrok

Depois que a Messages API estiver instalada, o próximo passo é executar o ngrok.

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 serviço à Internet. Se você ainda não usou o ngrok, há uma postagem no blog que explica isso com mais detalhes. Depois de configurar o ngrok e fazer login (novamente, o Account gratuito é suficiente), execute o seguinte comando:

ngrok http 3000

Depois que o ngrok for executado, ele fornecerá um URL de redirecionamento que usaremos como base para nossos Webhooks mais adiante neste artigo.

3. Criar um aplicativo com suporte a SMS

Para interagir com a Messages API, precisaremos criar um aplicativo da API da Vonage para autenticar nossas solicitações.

Pense nas Applications mais como contêineres e metadados para agrupar todos os seus dados na plataforma da Vonage. Vamos criaremos um usando o Painel da API da Vonage.

Digite um nome (como “Enviar e receber mensagens SMS”) e clique em Gerar chave pública e privada. Será solicitado que você salve um arquivo de chave no disco — a chave privada. Geralmente, é recomendável mantê-lo na pasta do seu projeto, pois você precisará dele mais tarde. Os aplicativos funcionam com um sistema de chaves pública e privada; portanto, quando você cria um aplicativo, uma chave pública é gerada e mantida pela Vonage, enquanto uma chave privada é gerada, não é mantida pela Vonage e é fornecida a você durante a criação do aplicativo. Usaremos a chave privada para autenticar nossas chamadas à biblioteca mais adiante.

Em seguida, você precisa ativar as recurso e definir uma URL de entrada e uma URL de status.

Use a URL do ngrok que você obteve na etapa anterior e preencha cada campo, acrescentando /webhooks/inbound e /webhooks/status, para a URL de entrada e URL de status.

Quando uma mensagem chega à Messages API, os dados relativos a ela são enviados para a URL de entrada. Ao enviar uma mensagem usando a API, os dados sobre o status da mensagem são enviados para a URL de status.

Por fim, vincule um ou mais dos seus números virtuais a este aplicativo. Quaisquer mensagens recebidas nesses números serão encaminhadas para o seu URL de entrada.

Create Messages enabled Vonage Application

4. Enviar a mensagem SMS

Por fim, vamos criar o código em Node.js para enviar mensagens SMS.

Crie uma nova pasta onde deseja armazenar o código-fonte do aplicativo que estamos criando. Quando terminar, digite npm init para inicializar um novo aplicativo Node.js. Por fim, crie um index.js arquivo e inicialize a biblioteca do node da Vonage instalada anteriormente.

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage({
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH
});

Como boa prática, você deve usar variáveis de ambiente ao incluir os seguintes valores em seu código.

Substitua o VONAGE_APPLICATION_ID pelo ID do aplicativo fornecido para o aplicativo da Vonage que você criou. Substitua o VONAGE_APPLICATION_PRIVATE_KEY_PATH pelo caminho para a chave privada que foi baixada automaticamente para você. Observação: copiei meu private.key arquivo na raiz do meu aplicativo e consigo acessá-lo especificando que o privateKey é igual a './private.key'

Para enviar uma mensagem SMS com a Messages API, usaremos o vonage.messages.send método da biblioteca Vonage para Node.js. Esse método aceita objetos como parâmetros, contendo informações sobre o destinatário, o remetente e o conteúdo. Essas informações variam de acordo com os diferentes canais; portanto, você precisará consultar a documentação da API para os outros canais mencionados.

Para SMS, precisaremos especificar um destinatário e um remetente. Por fim, o content objeto aceita um type de text e uma mensagem de texto. O callback retorna um objeto de erro e um de resposta, e vamos registrar mensagens sobre o sucesso ou a falha da operação.

const text = "👋Hello from Vonage";

vonage.messages
  .send({
    text: text,
    message_type: "text",
    to: TO_NUMBER,
    from: FROM_NUMBER,
    channel: "sms",
  })
  .then((resp) => console.log(resp.message_uuid))
  .catch((err) => console.error(err));

Substitua TO_NUMBER pelo número de telefone de destino como uma string e adicione o número de telefone atribuído a você ao FROM_NUMBER campo e, em seguida, execute o código com:

node index.js

É isso aí; você acabou de enviar um SMS usando o Node.js e a Messages API do Vonage!

Você pode notar que a Messages API é um pouco mais detalhada, mas ainda assim requer apenas um método para Verify se a mensagem recebida veio da Vonage. Inclua o seguinte:

const verifyJWT = (req) => {
// Verify if the incoming message came from Vonage
const jwtToken = req.headers.authorization.split(" ")[1];
if(!verifySignature(jwtToken, process.env.VONAGE_API_SIGNATURE_SECRET)) {
console.error("Unauthorized request");
throw new Error('Not a messages API request');
}

console.log('JWT verified');
}

Como receber mensagens SMS com o Node.js

Quando um número da Vonage recebe uma mensagem SMS, a Vonage encaminha essa mensagem para um webhook pré-definido. Você já configurou a URL do webhook ao criar o aplicativo da Vonage habilitado para mensagens: YOUR_NGROK_URL/webhooks/inbound

Para receber mensagens SMS usando o Node.js, siga as etapas abaixo:

1. Criar um servidor web

2. Criar um webhook para a URL de entrada

3. Enviar e receber uma mensagem de teste

1. Criar um servidor web

Vamos criar nosso servidor web usando Express , pois é um dos frameworks Node.js mais populares e fáceis de usar para essa finalidade. Também analisaremos os corpos das solicitações para a URL de entrada, por isso precisaremos instalar express a partir do npm.

npm install express --save

Vamos criar um novo arquivo para isso e chamá-lo de server.js. Ele pode ficar na mesma pasta que criamos anteriormente.

Vamos criar um express aplicativo que usa o analisador JSON do express e define a urlencoded opção para true. Vamos preencher o server.js arquivo que criamos. Usaremos a porta 3000 para o servidor escutar, e já temos o ngrok rodando na porta 3000.

const express = require("express");

const { json, urlencoded } = express;

const app = express();

app.use(json());

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

app.listen(3000, () => {
  console.log("Server listening at http://localhost:3000");
});

2. Criar um webhook para a URL de entrada

Vamos criar um manipulador de solicitação POST para /webhooks/inbound a URL de entrada e registraremos o corpo da solicitação no console. Como a Vonage possui um mecanismo de repetição de tentativas, ela continuará reenviando a mensagem caso a URL não responda com 200 OK, por isso, devolveremos um 200 status.

app.post("/webhooks/inbound", (req, res) => {
  console.log(req.body);

  res.status(200).end();
});

Você pode executar o código da seguinte maneira:

node server.js

3. Enviar e receber uma mensagem de teste

Agora envie uma mensagem SMS do seu celular para o seu número da Vonage. Verifique o seu terminal — se tudo estiver funcionando, você deverá ver algo assim:

Conclusão

E pronto, você acabou de enviar seu primeiro SMS! Agora que você aprendeu a enviar e receber mensagens SMS com a Messages API e o Node.js, pode ampliar esse projeto para responder a mensagens SMS recebidas ou incluir elementos interativos mais complexos para suas necessidades atuais ou futuras relacionadas a SMS.

Mais uma vez, obrigado pela leitura. Até a próxima!

Leituras complementares

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

• Crie um agendador de mensagens com Node e Vonage