@insttechnologies/sms

Official server-side Node.js SDK for the InstSMS API.

Requirements

• Node.js 20 or newer
• An InstSMS API user ID and API key
• An approved sender ID

This package is intended for trusted server environments only. Never place an InstSMS API key in browser or mobile application code.

Installation

npm install @insttechnologies/sms

Quick start

import { InstSMS } from "@insttechnologies/sms";

const instsms = new InstSMS({
  userId: process.env.INSTSMS_USER_ID,
  apiKey: process.env.INSTSMS_API_KEY,
});

const response = await instsms.messages.send({
  senderId: "YOUR SENDER ID",
  recipient: "0771234567",
  message: "Your order is ready.",
});

console.log(response.data);

CommonJS is also supported:

const { InstSMS } = require("@insttechnologies/sms");

Send bulk SMS

const response = await instsms.messages.sendBulk({
  senderId: "YOUR SENDER ID",
  recipients: ["0771234567", "+94771234568"],
  message: "A service update from your business.",
});

Check account status

const response = await instsms.account.getStatus();

console.log(response.data.sms_credit_balance);
console.log(response.data.sender_id_balances);

Idempotency and retries

The SDK generates an idempotency key for every send request. This prevents a transient retry from creating the same operation twice. For application-level retries, supply and retain your own key for the business operation:

await instsms.messages.send({
  senderId: "YOUR SENDER ID",
  recipient: "0771234567",
  message: "Your verification code is 482913.",
  idempotencyKey: "verification-customer-184-request-7",
});

Network failures, timeouts, HTTP 408, HTTP 429, and server errors are retried automatically. Validation and authentication errors are not retried.

Error handling

import { InstSMS, InstSMSError } from "@insttechnologies/sms";

try {
  await instsms.messages.send({
    senderId: "YOUR SENDER ID",
    recipient: "0771234567",
    message: "Hello from InstSMS.",
  });
} catch (error) {
  if (error instanceof InstSMSError) {
    console.error(error.code, error.status, error.message);
  }
}

The SDK does not include credentials in URLs or error messages. See the InstSMS documentation for API setup and sender ID guidance.

License

MIT © Inst Technologies (Pvt) Ltd