@netgsm/sms NPM

@netgsm/sms

Official Node.js client for the Netgsm SMS API. This package enables you to easily use Netgsm SMS services in your Node.js applications.

Features

SMS sending (instant and scheduled)
Bulk SMS sending (different messages for each recipient)
SMS report querying
Message header listing
Balance querying
Inbox message listing
Canceling scheduled SMS
TypeScript support
Comprehensive error handling

Requirements

Node.js 14.0.0 or higher
Netgsm account and API access

Installation

Using NPM:

npm install @netgsm/sms

Using Yarn:

yarn add @netgsm/sms

Quick Start

CommonJS usage

// Option 1: Named imports
const { Netgsm, SmsStatus, BalanceType } = require('@netgsm/sms');

// Option 2: Default import
const Netgsm = require('@netgsm/sms').default;
// or
const { default: Netgsm } = require('@netgsm/sms');

// Configure Netgsm client
const netgsm = new Netgsm({
  username: 'YOUR_USERNAME',
  password: 'YOUR_PASSWORD',
  appname: 'YOUR_APP_NAME' // Optional
});

// Send SMS
async function sendSms() {
  try {
    const response = await netgsm.sendRestSms({
      msgheader: 'YOUR_HEADER', // SMS header
      encoding: 'TR', // Turkish character support
      startdate: '010620241530',       // Optional (format: ddMMyyyyHHmm)
      stopdate: '010620241630',        // Optional (format: ddMMyyyyHHmm)
      messages: [
        { msg: 'Message content', no: '5XXXXXXXXX' },
        { msg: 'Message content', no: '5YYYYYYYYY' }
      ]
    });
    
    console.log('SMS sent:', response);
    return response.jobid;
  } catch (error) {
    console.error('Error:', error);
  }
}

// Call the function
sendSms();

ES Modules / TypeScript usage

// Option 1: Default import (recommended)
import Netgsm from '@netgsm/sms';

// Option 2: Named imports
import { Netgsm, SmsStatus, BalanceType } from '@netgsm/sms';

// Configure Netgsm client
const netgsm = new Netgsm({
  username: 'YOUR_USERNAME',
  password: 'YOUR_PASSWORD',
  appname: 'YOUR_APP_NAME' // Optional
});

// Type-safe usage
async function checkBalance() {
  try {
    const balance = await netgsm.getBalance({
      type: BalanceType.CREDIT
    });
    
    console.log('Balance:', balance);
    return balance;
  } catch (error) {
    console.error('Error:', error);
  }
}

Usage Examples

For more examples, check the examples directory:

Basic Usage
Scheduled SMS
Bulk SMS
Additional Examples (Future-dated, multiple numbers, end-dated, Turkish character support, and IYS filtered deliveries)

API Reference

Configuration

const netgsm = new Netgsm({
  username: 'YOUR_USERNAME', // Required
  password: 'YOUR_PASSWORD',  // Required
  appname: 'YOUR_APP_NAME'    // Optional
});

Sending SMS

const response = await netgsm.sendRestSms({
  msgheader: 'YOUR_HEADER',
  encoding: 'TR',              // TR, ASCII
  startdate: '010620241530',   // Optional (format: ddMMyyyyHHmm)
  stopdate: '010620241630',    // Optional (format: ddMMyyyyHHmm)
  messages: [
    { msg: 'Message content', no: '5XXXXXXXXX' },
    { msg: 'Message content', no: '5YYYYYYYYY' }
  ]
});

Querying SMS Report

const report = await netgsm.getReport({
  bulkIds: ['12345678'] // Job ID received after sending  
});

Checking Balance

const balance = await netgsm.getBalance({
  type: BalanceType.CREDIT // 1: Package/campaign info, 2: Credit info
});

Listing Headers

const headers = await netgsm.getHeaders();

Listing Inbox Messages

const inbox = await netgsm.getInbox({
  startdate: '01012024', // Start date (format: ddMMyyyy)
  stopdate: '31012024'   // End date (format: ddMMyyyy)
});

Canceling Scheduled SMS

const cancelResult = await netgsm.cancelSms({
  jobid: '12345678' // Job ID of the delivery to cancel
});

For more detailed API reference, visit the API Documentation page.

Development

To set up the development environment:

# Clone the repository
git clone https://github.com/netgsm/netgsm-sms-js.git
cd netgsm-sms-js

# Install dependencies
npm install

# Run tests
npm test

# Build the library
npm run build