Envio de SMS em JavaScript (Node.js): API da biblioteca sms-node-client

Biblioteca sms-node-client: Envio de SMS a partir do Node.js

As aplicações web modernas frequentemente exigem integração com serviços de SMS para envio de notificações, confirmações de registro ou campanhas de marketing. A biblioteca sms-node-client fornece uma interface simples e conveniente para trabalhar com gateways SMS populares diretamente do Node.js. Ela abstrai a complexidade das requisições HTTP e autenticação, permitindo que o desenvolvedor se concentre na lógica de negócios.

Neste artigo, exploraremos os principais recursos da biblioteca: instalação, configuração da conexão com a API, envio de mensagens individuais e em massa, bem como o tratamento de erros comuns.

Instalação e importação

A biblioteca é distribuída via npm. Para instalá-la, execute o comando na raiz do seu projeto:

npm install sms-node-client

Após a instalação, importe a biblioteca no seu arquivo JavaScript:

const SMSClient = require('sms-node-client');

// ou usando módulos ES6 (se configurado)// import SMSClient from 'sms-node-client';

Configuração do cliente

Para trabalhar com a API, é necessário inicializar um objeto cliente, passando os parâmetros de conexão: apiKey (chave de acesso) e apiSecret (chave secreta). Geralmente, esses dados são fornecidos pelo seu provedor de SMS.

const client = new SMSClient({  apiKey: 'sua_chave_api',  apiSecret: 'seu_segredo_api',  // Opcional: é possível especificar uma URL base, se o provedor usar um endpoint não padrão  // baseUrl: 'https://custom-sms-gateway.com/api/v1'});

Métodos principais da biblioteca

A biblioteca fornece três métodos principais para envio de mensagens:

• sendSMS(phone, message, options?) — envio de um único SMS para um número.
• sendBulkSMS(messages, options?) — envio em massa para vários números.
• getStatus(messageId) — verificação do status de entrega pelo ID da mensagem.

Exemplo: Envio de um único SMS

O cenário mais simples é enviar uma mensagem para um único número. O método retorna uma Promise, portanto é conveniente usar async/await.

async function sendSingleSMS() {  try {    const result = await client.sendSMS(      '+551234567890',            // Número do destinatário no formato internacional      'Olá! Esta é uma mensagem de teste do Node.js.', // Texto da mensagem      { sender: 'MyApp' }       // Opcional: nome do remetente (deve estar registrado no provedor)    );

    console.log('SMS enviado com sucesso:', result);    // result.messageId - ID único da mensagem para rastrear o status  } catch (error) {    console.error('Erro ao enviar SMS:', error.message);  }}

sendSingleSMS();

Exemplo: Envio em massa

Para enviar o mesmo texto para vários números, use o método sendBulkSMS. Ele aceita um array de objetos com os números.

async function sendBulk() {  const recipients = [    { phone: '+551234567890' },    { phone: '+550987654321' },    { phone: '+550123456789' }  ];

  try {    const result = await client.sendBulkSMS(recipients, {      message: 'Prezado cliente! Seu pedido está pronto para retirada.',      sender: 'ShopBot'    });

    console.log(`Enviadas ${result.sentCount} mensagens`);    // result.messages - array com detalhes de cada número  } catch (error) {    console.error('Erro no envio em massa:', error);  }}

sendBulk();

Verificação do status de entrega

Após o envio, você pode verificar se a mensagem foi entregue ao destinatário. Para isso, use o messageId obtido no envio.

async function checkStatus(messageId) {  try {    const status = await client.getStatus(messageId);    console.log('Status da mensagem:', status);    // status.s