farazsms

FarazSMS · IranPayamak — فراز اس ام اس · ایران پیامک 🌐 farazsms.com · iranpayamak.com

Official lightweight client for the FarazSMS / IranPayamak web services — send pattern/OTP, simple & bulk SMS, pull reports, manage your phonebook, and reach all 63 endpoints through a low-level request().

Zero dependencies. Works on Node.js 18+ (built-in fetch), ESM and CommonJS, with TypeScript types.

Install

npm install farazsms

Quick start

import FarazSMS from "farazsms";          // ESM
// const FarazSMS = require("farazsms");   // CommonJS

const sms = new FarazSMS("YOUR_API_KEY"); // key from the FarazSMS panel → Web Service / API Key

console.log(await sms.balance());                                     // verify the key — free
await sms.sendPattern("SJ3FgPrE0C", "09120000000", { code: "1234" });  // OTP (instant, never queued)
await sms.sendSimple("Hello!", ["09120000000", "09130000000"]);       // bulk
console.log(await sms.inbox(1, 20));                                  // inbound replies

Recipients use the local format 09120000000 (no +98). The default sender line is 90008361.

Error handling

The client throws a FarazError whenever the API returns { status: "error" }, so you don't have to check manually:

import { FarazError } from "farazsms";
try {
  await sms.sendPattern("BAD_CODE", "09120000000", { code: "1" });
} catch (e) {
  if (e instanceof FarazError) console.error(e.status, e.body);
}

Bundled helpers

| Area | Methods | |------|---------| | Account | balance() · profile() · lines() | | Send | sendPattern() · sendSimple() · sendVariable() | | Patterns | createPattern() · patterns() | | Reports | inbox() · sendRequests() · sendRequestItems() | | Phonebook | phonebooks() · addContact() | | Reference | provinces() · numberBanks() |

Anything else (tickets, orders, voice, LBS, …) is reachable via the low-level call:

await sms.request("POST", "/ws/v1/ticket", { department: 1, subject: "Hi" });

License

MIT