Отправка SMS на JavaScript (Node.js): API библиотеки sms-node-client

Библиотека sms-node-client: Отправка SMS из Node.js

Современные веб-приложения часто требуют интеграции с SMS-сервисами для отправки уведомлений, подтверждений регистрации или маркетинговых рассылок. Библиотека sms-node-client предоставляет простой и удобный интерфейс для работы с популярными SMS-шлюзами напрямую из Node.js. Она абстрагирует сложность HTTP-запросов и аутентификации, позволяя разработчику сосредоточиться на бизнес-логике.

В этой статье мы рассмотрим основные возможности библиотеки: установку, настройку подключения к API, отправку одиночных и массовых сообщений, а также обработку типовых ошибок.

Установка и подключение

Библиотека распространяется через npm. Для установки выполните команду в корне вашего проекта:

npm install sms-node-client

После установки импортируйте библиотеку в ваш JavaScript-файл:

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

// или используя ES6 модули (если настроено)
// import SMSClient from 'sms-node-client';

Настройка клиента

Для работы с API необходимо инициализировать объект клиента, передав ему параметры подключения: apiKey (ключ доступа) и apiSecret (секретный ключ). Обычно эти данные предоставляются вашим SMS-провайдером.

const client = new SMSClient({
  apiKey: 'ваш_api_ключ',
  apiSecret: 'ваш_api_секрет',
  // Опционально: можно указать базовый URL, если провайдер использует нестандартный эндпоинт
  // baseUrl: 'https://custom-sms-gateway.com/api/v1'
});

Основные методы библиотеки

Библиотека предоставляет три основных метода для отправки сообщений:

• sendSMS(phone, message, options?) — отправка одного SMS на один номер.
• sendBulkSMS(messages, options?) — массовая отправка на несколько номеров.
• getStatus(messageId) — проверка статуса доставки по ID сообщения.

Пример: Отправка одного SMS

Самый простой сценарий — отправить сообщение на один номер. Метод возвращает Promise, поэтому удобно использовать async/await.

async function sendSingleSMS() {
  try {
    const result = await client.sendSMS(
      '+71234567890',            // Номер получателя в международном формате
      'Привет! Это тестовое сообщение из Node.js.', // Текст сообщения
      { sender: 'MyApp' }       // Опционально: имя отправителя (должно быть зарегистрировано у провайдера)
    );

    console.log('SMS отправлено успешно:', result);
    // result.messageId - уникальный ID сообщения для отслеживания статуса
  } catch (error) {
    console.error('Ошибка отправки SMS:', error.message);
  }
}

sendSingleSMS();

Пример: Массовая рассылка

Для отправки одного и того же текста на несколько номеров используйте метод sendBulkSMS. Он принимает массив объектов с номерами.

async function sendBulk() {
  const recipients = [
    { phone: '+71234567890' },
    { phone: '+70987654321' },
    { phone: '+70123456789' }
  ];

  try {
    const result = await client.sendBulkSMS(recipients, {
      message: 'Уважаемый клиент! Ваш заказ готов к выдаче.',
      sender: 'ShopBot'
    });

    console.log(`Отправлено ${result.sentCount} сообщений`);
    // result.messages - массив с деталями по каждому номеру
  } catch (error) {
    console.error('Ошибка массовой рассылки:', error);
  }
}

sendBulk();

Проверка статуса доставки

После отправки вы можете проверить, дошло ли сообщение до адресата. Для этого используйте messageId, полученный при отправке.

async function checkStatus(messageId) {
  try {
    const status = await client.getStatus(messageId);
    console.log('Статус сообщения:', status);
    // status.state - может быть 'sent', 'delivered', 'failed' и т.д.
  } catch (error) {
    console.error('Не удалось получить статус:', error.message);
  }
}

// Пример использования
// checkStatus('abc123-def456');

Обработка ошибок

Библиотека выбрасывает исключения при проблемах с сетью, неверных параметрах или отклонении запроса API. Рекомендуется всегда оборачивать вызовы в блоки try/catch. Основные типы ошибок:

• AuthenticationError — неверный API-ключ или секрет.
• Validation