zong-mobile-sms

Send SMS and bulk SMS through your Zong SIM using an Android phone as a gateway. Includes a Node.js SDK, REST API, Swagger docs, and a web panel.

PC/Laptop (Node.js)  →  WiFi  →  Android Phone (SMS Gateway App)  →  Zong SIM  →  SMS

Features

• Node.js SDK — use as npm package in your own projects
• REST API — POST /api/sms/send, bulk send, health check
• Web Panel — modern UI to send single/bulk SMS
• Swagger UI — interactive API documentation
• Pakistan number formatting — 03xx → +92xx automatically
• Bulk queue — rate-limited sending to avoid carrier blocks
• Setup wizard — first visit par UI se .env auto configure (no manual editing)

Requirements

• Node.js 18+
• Android phone with SMS Gateway for Android installed
• Zong SIM in the phone
• Phone and PC on the same WiFi network

Installation

From npm (after publish)

npm install zong-mobile-sms
npx zong-sms

The browser will open and the setup wizard starts automatically.

Local / development

git clone <your-repo-url>
cd zong-mobile-sms
npm install
npm run dev

On first run, the wizard at http://localhost:3000/setup.html creates your .env automatically.

Phone Setup (one-time)

1. Install app-release.apk from SMS Gateway releases
2. Open app → turn Local Server ON
3. Note from the app:
   • Local address → SMS_GATEWAY_URL (e.g. http://192.168.18.18:8080)
   • Username → SMS_GATEWAY_USER
   • Password → SMS_GATEWAY_PASSWORD
4. Keep phone on same WiFi as your PC

First-Time Setup Wizard

When someone runs npm install then npx zong-sms or npm run dev:

1. Browser → http://localhost:PORT/setup.html (auto redirect)
2. Step 1 — Install SMS Gateway app on phone
3. Step 2 — Enter URL, username, password from the app
4. Step 3 — SIM slot, sender number, delay, port
5. Test & Save — connection test + .env saved automatically

.env file location: current working directory (process.cwd())

You can still edit .env manually if already configured.

Environment Variables

The wizard writes all of these to .env:

| Variable | Description | Example | |----------|-------------|---------| | SMS_GATEWAY_URL | Phone local IP from app | http://192.168.18.18:8080 | | SMS_GATEWAY_USER | App username | sms | | SMS_GATEWAY_PASSWORD | App password | yourpassword | | ZONG_SIM_NUMBER | SIM slot (1 or 2) | 1 | | SMS_DELAY_MS | Delay between bulk SMS (ms) | 3000 | | PORT | API server port | 3000 | | SENDER_NUMBER | Your Zong number (display only) | +923001234567 |

Usage as npm Package (SDK)

Import ZongSmsGateway in any Node.js project:

import { ZongSmsGateway } from 'zong-mobile-sms';

const sms = new ZongSmsGateway({
  baseUrl: 'http://192.168.18.18:8080',
  username: 'sms',
  password: 'yourpassword',
  simNumber: 1,
  delayMs: 3000,
});

// Check phone connection
await sms.checkConnection();

// Send single SMS
await sms.sendSms('03459242192', 'Hello from SDK!');

// Bulk SMS — same message to many numbers
const result = await sms.sendBulk(
  ['03001234567', '03111234567'],
  'Bulk message here',
  {
    onProgress: ({ current, total }) => {
      console.log(`${current}/${total}`);
    },
  }
);

console.log(`Sent: ${result.sent}, Failed: ${result.failed}`);

Exported APIs

import {
  ZongSmsGateway,      // Main gateway class
  formatPakistanNumber, // "0300..." → "+92300..."
  formatNumbers,        // Array formatter
  isValidPakistanMobile,// Validation
  BulkQueue,            // Standalone queue utility
} from 'zong-mobile-sms';

ZongSmsGateway options

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseUrl | string | required | Phone gateway URL (local mode) | | username | string | required | App username | | password | string | required | App password | | simNumber | number | 1 | SIM slot for Zong | | mode | 'local' | 'cloud' | 'local' | Gateway mode | | delayMs | number | 3000 | Bulk send delay | | batchSize | number | 1 | Messages per batch |

Methods

| Method | Description | |--------|-------------| | checkConnection() | Verify phone gateway is reachable | | sendSms(to, message, options?) | Send one SMS | | sendBulk(recipients, message?, options?) | Bulk send with queue | | sendBulkBatch(numbers, message, options?) | Send to many in one API call | | getStatus(messageId) | Check delivery status | | waitForDelivery(messageId, options?) | Poll until delivered/failed |

Usage as CLI / Server

After install, start the full server (API + web panel + Swagger):

# Using npm script (in project folder)
npm run dev

# Or production
npm start

# Global CLI (after npm install -g zong-mobile-sms)
zong-sms

# Without global install
npx zong-sms

URLs

| Service | URL | |---------|-----| | Web Panel | http://localhost:3000 | | Swagger UI | http://localhost:3000/api/docs | | OpenAPI JSON | http://localhost:3000/api/docs/openapi.json |

REST API

Health check

curl http://localhost:3000/api/health

Send SMS

curl -X POST http://localhost:3000/api/sms/send \
  -H "Content-Type: application/json" \
  -d '{"to":"+923459242192","message":"Hello!"}'

Bulk SMS

curl -X POST http://localhost:3000/api/sms/send-bulk \
  -H "Content-Type: application/json" \
  -d '{"message":"Bulk msg","numbers":["03001234567","03111234567"]}'

Use Server Programmatically

import { start, app, gateway } from 'zong-mobile-sms/server';

// Start HTTP server (reads .env automatically)
start();

// Or use gateway instance directly
await gateway.sendSms('+923459242192', 'Hello');

Project Structure

zong-mobile-sms/
├── index.js              # Package entry (SDK exports)
├── server.js             # Express API + static panel
├── openapi.json          # OpenAPI / Swagger spec
├── bin/cli.js            # CLI: zong-sms command
├── src/
│   ├── ZongSmsGateway.js # Core gateway class
│   ├── phoneUtils.js     # Pakistan number helpers
│   └── bulkQueue.js      # Rate-limited queue
├── public/               # Web panel (HTML/CSS/JS)
└── examples/             # Usage examples

Publish to npm

1. Update package.json — set your author, repository, and homepage
2. Login to npm:

   npm login

3. Check package name is available (or use a scoped name):

   npm publish
   # Or scoped:
   # "name": "@yourusername/zong-mobile-sms"
   # npm publish --access public

4. Dry run first:

   npm pack
   # Inspects generated .tgz contents

Local npm link (test in another project)

# In zong-mobile-sms folder
npm link

# In your other project
npm link zong-mobile-sms

import { ZongSmsGateway } from 'zong-mobile-sms';

Troubleshooting

| Problem | Fix | |---------|-----| | fetch failed | Phone app Local Server OFF, or different WiFi | | EADDRINUSE | Port busy — change PORT in .env or kill old process | | SMS not sending | Check Zong balance, SIM slot in ZONG_SIM_NUMBER | | Bulk blocked | Increase SMS_DELAY_MS to 5000 or higher |

Windows — free port:

netstat -ano | findstr :3000
taskkill /PID <pid> /F

License

MIT