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

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Usage Examples
• API Reference
• Development
• Contributing
• License
• Security
• Contact

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

Contributing

If you want to contribute to this project, please review the CONTRIBUTING.md file. All contributions are evaluated under the Contributors Agreement.

License

This project is licensed under the MIT license. See the LICENSE file for details.

Security

For security vulnerabilities or concerns, please review the SECURITY.md file and follow the specified steps.

Contact

For technical support or questions about the SDK, please contact us at:

• Email: [email protected]
• Website: https://www.netgsm.com.tr

We're here to help you integrate Netgsm SMS services into your applications successfully.