StarSender SDK 🚀

Modern, Zero-Dependency TypeScript SDK for the StarSender WhatsApp Gateway API V3.
Supports both Node.js (18+), Bun, and Deno with native fetch, fully typed interfaces, and custom exception mappings.

✨ Features

• ⚡ Zero Dependency: Built purely on native fetch (requires Node 18+ or Bun/Deno).
• 📦 Dual Format: Native support for both ES Modules (ESM) and CommonJS (CJS).
• 🛡️ Full Type-Safety: 100% written in TypeScript with generated type declarations (.d.ts).
• 🔑 Flexible Authentication: Pass a default credentials key to the client instance, or override apiKey in individual requests as needed.
• 🚀 Fully Documented API v3: Aligns accurately with official StarSender V3 endpoints.
• 🧩 Custom Exception System: Catch specific structured errors (StarSenderAuthError, StarSenderValidationError, etc.) rather than generic messages.

📦 Installation

npm install starsender-sdk
# or
yarn add starsender-sdk
# or
pnpm add starsender-sdk
# or
bun add starsender-sdk

🚀 Quick Start

Initialize the StarSender class with your default API key (Device or User/Account key depending on your requirements).

import { StarSender } from 'starsender-sdk';

// Initialize with a default key
const ws = new StarSender('YOUR_DEFAULT_API_KEY');

// Or configure baseUrl and custom timeout
const wsCustom = new StarSender({
  apiKey: 'YOUR_DEFAULT_API_KEY',
  baseUrl: 'https://api.starsender.online', // default
  timeout: 15000,                          // 15 seconds (default is 30s)
});

💬 Messages API

All messaging operations are grouped under the .messages module.

Send a Text Message

await ws.messages.sendText('08123456789', 'Hello from StarSender SDK! 👋');

// With options (e.g., adding delay or schedule)
await ws.messages.sendText('08123456789', 'This is delayed', {
  delay: 10, // 10 seconds delay
});

Send a Media Message

await ws.messages.sendMedia(
  '08123456789',
  'https://images.unsplash.com/photo-1579546929518-9e396f3cc809', // URL of image/file
  'Look at this beautiful gradient! 🎨'                             // Optional Caption
);

Advanced Message Sending

await ws.messages.send({
  messageType: 'text',
  to: '08123456789',
  body: 'This is scheduled for the future!',
  delay: 5,
  schedule: Date.now() + 3600000, // Unix milliseconds (1 hour in the future)
});

Send Messages via Rotator

Distribute massive volume campaigns across multiple WhatsApp gateway devices to avoid spam detection and number bans.

await ws.messages.sendRotator({
  mode: 'round_robin', // 'round_robin' or 'batch'
  devices: [
    { device_id: 1641, limit: 50 },
    { device_id: 42800, limit: 50 }
  ],
  messages: [
    { to: '08123456789', body: 'Message distributed for User A' },
    { to: '08987654321', body: 'Message distributed for User B' }
  ]
});

Check WhatsApp Registration Status

const check = await ws.messages.checkNumber('08123456789');
if (check.data.status) {
  console.log('WhatsApp is registered! ✅');
} else {
  console.log('WhatsApp number is not registered. ❌');
}

Send a Message to a WhatsApp Group

You can send text or media messages directly to WhatsApp Groups using Group IDs or Group Names.

// Send a simple text message to a group
await ws.messages.sendGroupText('[email protected]', 'Hello everyone in the group! 👥');

// Send media to a group
await ws.messages.sendGroupMedia(
  '[email protected]',
  'https://example.com/slide.pdf',
  'Here is the presentation file 📄'
);

// Advanced group send with delay & schedule options
await ws.messages.sendGroup({
  messageType: 'text',
  to: '[email protected]',
  body: 'This is scheduled for tomorrow!',
  delay: 5,
  schedule: Date.now() + 86400000,
});

Retrieve Message Details

const detail = await ws.messages.getDetail(99);
console.log(`Message status: ${detail.data.status}`);

📱 Devices API

All gateway device operations are grouped under the .devices module.

[!NOTE]
Device endpoints require your Account/User API Key (from the Profile settings page) rather than a Device API Key.

// List all devices
const devicesList = await ws.devices.list();
console.log(devicesList.data.devices);

// Get detail of a single device
const device = await ws.devices.getDetail(1641);
console.log(`Device status: ${device.data.status}`);

// Relogin / request scan trigger
await ws.devices.relog(1641);

// Add device and get QR Code Base64
const qrResponse = await ws.devices.create('Marketing Server');
// Returns Base64 QR: qrResponse.data.kode_gambar

// Delete a device
await ws.devices.delete(1641);

📣 Campaigns API

Manage marketing campaigns easily with the .campaigns module. Campaign endpoints require your Account/User API Key.

// Create a new campaign
await ws.campaigns.create({
  device_api_key: 'YOUR_DEVICE_API_KEY',
  name: 'Summer Promo',
  syntax: 'Promo#Nama#Alamat',
  welcome_message: 'Hi! Thank you for subscribing to our summer campaign ☀️',
  number: '08123456789'
});

// Add member/subscriber to a campaign
await ws.campaigns.addMember({
  campaign_id: 1,
  number: '08987654321',
  syntax: 'Promo#Rian#Bandung',
  welcome_message: true // Optional
});

// Move a member from one campaign to another campaign
await ws.campaigns.moveMember({
  campaign_id_from: 1,
  campaign_id_to: 2,
  number: '08987654321'
});

👥 Contacts API

Organize and move target recipients inside contact groups using the .contacts module. Contact endpoints require your Account/User API Key.

// Create a new contact
await ws.contacts.create({
  name: 'Budi Santoso',
  number: '08123456789',
  variabel: ['Customer VIP', 'Jakarta'], // Optional variables
  group_id: 1 // Optional Group ID
});

// List all contact groups
const groupsResponse = await ws.contacts.listGroups();
console.log(groupsResponse.data);

// Remove a contact from a group
await ws.contacts.removeGroupMember({
  group_id: 1,
  number: '08123456789'
});

// Move a contact to another group
await ws.contacts.moveGroupMember({
  group_id_from: 1,
  group_id_to: 2,
  number: '08123456789'
});

📱 WhatsApp Group Listing API

Fetch native WhatsApp group structures linked to your devices under the .whatsapp module.

[!IMPORTANT]
Listing WhatsApp groups requires your Device API Key in the request headers (or as instance default).

// List all WhatsApp groups connected to the device
const whatsappGroups = await ws.whatsapp.listGroups({
  apiKey: 'YOUR_DEVICE_API_KEY' // Override to provide correct device key
});
console.log(whatsappGroups.data); // Array of WhatsAppGroup

🤖 Chat GPT Blacklist API

Prevent specific WhatsApp numbers from interacting with ChatGPT automated bots on your linked devices via the .chatgpt module.

[!IMPORTANT]
ChatGPT Blacklist operations require your connected device's Device API Key in the Authorization header.

// 1. List blacklisted numbers (supports pagination limit & page parameters)
const listResponse = await ws.chatgpt.listBlacklist({ limit: 10, page: 1 }, {
  apiKey: 'YOUR_DEVICE_API_KEY'
});
console.log(`Total blacklisted: ${listResponse.data.total_records}`);
console.log(listResponse.data.blacklist); // Array of ChatGPTBlacklistItem

// 2. Check if a specific number is currently blacklisted
const checkResponse = await ws.chatgpt.checkBlacklist('08123456789', {
  apiKey: 'YOUR_DEVICE_API_KEY'
});
if (checkResponse.data.blacklisted) {
  console.log(`Number is blacklisted since ${new Date(checkResponse.data.blacklist.created_at).toLocaleString()}`);
} else {
  console.log('Number is not blacklisted');
}

// 3. Add a number to the ChatGPT blacklist
const addResponse = await ws.chatgpt.addBlacklist('08123456789', {
  apiKey: 'YOUR_DEVICE_API_KEY'
});
console.log('Blacklist entry created:', addResponse.data.blacklist);

// 4. Remove a number from the ChatGPT blacklist
const removeResponse = await ws.chatgpt.removeBlacklist('08123456789', {
  apiKey: 'YOUR_DEVICE_API_KEY'
});
console.log(removeResponse.message); // "Success to delete blacklist"

⚓ Webhook Payload Typings

The SDK exports strongly-typed interfaces for incoming webhooks of all plan levels (Basic, Media, Group, and Premium with Quoted Messages):

import { 
  StarSenderWebhookPayload, 
  StarSenderWebhookWithDevicePayload,
  StarSenderWebhookMediaPayload, 
  StarSenderWebhookGroupPayload, 
  StarSenderWebhookPremiumPayload 
} from 'starsender-sdk';

// Inside your Express/Next.js/Bun API route:
app.post('/webhook', (req, res) => {
  const payload = req.body as StarSenderWebhookPremiumPayload;
  
  console.log(`New incoming chat from: ${payload.from}`);
  console.log(`Message type: ${payload.chat_type}`); // 'personal' or 'group'
  console.log(`Text body: ${payload.message}`);
  
  if (payload.quoted_message) {
    console.log(`This is replying to: ${payload.quoted_message}`);
  }
  
  res.sendStatus(200);
});

🔑 On-The-Fly API Key Overrides

Since StarSender uses different keys for sending messages (Device keys) versus managing servers (Account/User tokens), the SDK supports passing a local override option to any method call:

// Using overriding apiKey just for this specific list request
const overrideOptions = { apiKey: 'YOUR_USER_ACCOUNT_API_KEY' };

const devices = await ws.devices.list(overrideOptions);

🚨 Error Handling

The SDK provides semantic custom classes matching common HTTP statuses, allowing you to catch errors gracefully.

| Exception Class | HTTP Status | Scenario | | :--- | :---: | :--- | | StarSenderAuthError | 401 | Unauthorized: Invalid or missing API Key | | StarSenderValidationError | 400 | Bad Request: Invalid or missing parameters | | StarSenderRateLimitError | 429 | Rate limit hit | | StarSenderNetworkError | 0 | Request timed out or network connectivity failed | | StarSenderError | any | Base SDK exception class |

import { StarSender, StarSenderAuthError, StarSenderValidationError } from 'starsender-sdk';

const ws = new StarSender('INVALID_KEY');

try {
  await ws.messages.sendText('08123456789', 'Hello!');
} catch (error) {
  if (error instanceof StarSenderAuthError) {
    console.error('Authentication failed: Please check your API key.');
  } else if (error instanceof StarSenderValidationError) {
    console.error('Validation failed:', error.responseBody);
  } else {
    console.error('An unexpected error occurred:', error.message);
  }
}

📄 License

Distributed under the MIT License. See LICENSE for details.