@wiicode/wiisender

Official TypeScript/JavaScript client for the WiiSender WhatsApp messaging API.

Features

• Send WhatsApp text messages
• Check if phone numbers have WhatsApp
• Batch number validation
• Connection status monitoring
• Automatic phone number formatting
• Full TypeScript support
• Zero dependencies (except for HTTP client)

Installation

npm install @wiicode/wiisender
# or
yarn add @wiicode/wiisender
# or
pnpm add @wiicode/wiisender

Quick Start

import { WiiSenderClient } from '@wiicode/wiisender';

const client = new WiiSenderClient({
  serverUrl: 'http://localhost:3000',
  apiKey: 'wsk_your_api_key_here'
});

// Send a message
const result = await client.sendText({
  number: '0612345678',
  text: 'Hello from WiiSender!'
});

console.log('Message sent:', result.messageId);

// Check connection status
const status = await client.getStatus();
console.log('Connected:', status.connected);

// Check if number has WhatsApp
const check = await client.checkNumber({ number: '0612345678' });
console.log('Has WhatsApp:', check.exists);

Configuration

interface WiiSenderConfig {
  /** URL of the WiiSender server */
  serverUrl: string;
  /** API key for authentication */
  apiKey: string;
}

Methods

sendText(options)

Send a text message via WhatsApp.

const result = await client.sendText({
  number: '0612345678',      // Phone number (any format)
  text: 'Hello!',            // Message content
  delay: 1000,               // Optional: delay in ms
  linkPreview: true          // Optional: enable link previews
});

// Response
{
  success: true,
  messageId: 'uuid',
  evolutionMessageId: 'abc123',
  recipient: '212612345678',
  sentAt: '2024-01-23T12:00:00.000Z'
}

Phone Number Formats Supported: | Input | Formatted | |-------|-----------| | 0612345678 | 212612345678 | | 06 12 34 56 78 | 212612345678 | | +212612345678 | 212612345678 | | +2120612345678 | 212612345678 | | +212+212612345678 | 212612345678 | | 00212612345678 | 212612345678 |

checkNumber(options)

Check if a single phone number exists on WhatsApp.

const result = await client.checkNumber({
  number: '0612345678'
});

// Response
{
  input: '0612345678',
  formatted: '212612345678',
  exists: true,
  jid: '[email protected]'
}

checkNumbers(options)

Check if multiple phone numbers exist on WhatsApp.

const result = await client.checkNumbers({
  numbers: ['0612345678', '+212712345678', '06 12 34 56 78']
});

// Response
{
  results: [
    {
      input: '0612345678',
      formatted: '212612345678',
      exists: true,
      jid: '[email protected]'
    },
    {
      input: '+212712345678',
      formatted: '212712345678',
      exists: false,
      jid: null
    }
  ]
}

getStatus()

Get WhatsApp instance connection status.

const status = await client.getStatus();

// Response
{
  instanceName: 'wiicode.verifier',
  connected: true,
  state: 'open'
}

Utility Functions

formatPhoneNumber(phone, defaultCountryCode?)

Format a phone number to E.164 format (without + prefix).

import { formatPhoneNumber } from '@wiicode/wiisender';

formatPhoneNumber('0612345678');           // '212612345678'
formatPhoneNumber('06 12 34 56 78');       // '212612345678'
formatPhoneNumber('+212612345678');        // '212612345678'
formatPhoneNumber('+2120612345678');       // '212612345678'
formatPhoneNumber('+33612345678');         // '33612345678'
formatPhoneNumber('0612345678', '33');     // '33612345678' (French default)

isValidPhoneNumber(phone)

Check if a phone number is valid.

import { isValidPhoneNumber } from '@wiicode/wiisender';

isValidPhoneNumber('0612345678');    // true
isValidPhoneNumber('123');           // false (too short)
isValidPhoneNumber('abc');           // false (not numeric)

isMoroccanNumber(phone)

Check if a phone number is Moroccan.

import { isMoroccanNumber } from '@wiicode/wiisender';

isMoroccanNumber('0612345678');      // true
isMoroccanNumber('+212712345678');   // true
isMoroccanNumber('+33612345678');    // false

Error Handling

import { WiiSenderClient, WiiSenderError } from '@wiicode/wiisender';

try {
  await client.sendText({ number: '0612345678', text: 'Hello!' });
} catch (error) {
  if (error instanceof WiiSenderError) {
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Response:', error.response);
  }
}

TypeScript Types

All types are exported for TypeScript users:

import {
  WiiSenderConfig,
  SendTextOptions,
  MessageResponse,
  CheckNumberOptions,
  CheckNumberResult,
  CheckNumbersOptions,
  CheckNumbersResponse,
  ConnectionStatusResponse,
  WiiSenderErrorResponse
} from '@wiicode/wiisender';

Examples

Send message with validation

import { WiiSenderClient, isValidPhoneNumber, formatPhoneNumber } from '@wiicode/wiisender';

const client = new WiiSenderClient({ serverUrl, apiKey });

async function sendMessage(phone: string, text: string) {
  if (!isValidPhoneNumber(phone)) {
    throw new Error('Invalid phone number');
  }

  console.log(`Sending to: ${formatPhoneNumber(phone)}`);

  return client.sendText({ number: phone, text });
}

Single number validation

import { WiiSenderClient } from '@wiicode/wiisender';

const client = new WiiSenderClient({ serverUrl, apiKey });

async function sendIfExists(phone: string, text: string) {
  const check = await client.checkNumber({ number: phone });

  if (check.exists) {
    return client.sendText({ number: phone, text });
  }

  console.log(`${phone} is not on WhatsApp`);
  return null;
}

Bulk number validation

import { WiiSenderClient } from '@wiicode/wiisender';

const client = new WiiSenderClient({ serverUrl, apiKey });

async function filterValidNumbers(numbers: string[]) {
  const result = await client.checkNumbers({ numbers });

  return result.results
    .filter(r => r.exists)
    .map(r => r.formatted);
}

const validNumbers = await filterValidNumbers([
  '0612345678',
  '0712345678',
  '0600000000'
]);

Send to multiple recipients

import { WiiSenderClient } from '@wiicode/wiisender';

const client = new WiiSenderClient({ serverUrl, apiKey });

async function broadcast(numbers: string[], message: string) {
  const results = await Promise.allSettled(
    numbers.map(number =>
      client.sendText({ number, text: message })
    )
  );

  return {
    sent: results.filter(r => r.status === 'fulfilled').length,
    failed: results.filter(r => r.status === 'rejected').length
  };
}

Environment Variables

You can configure the client via environment variables:

WIISENDER_SERVER_URL=http://localhost:3000
WIISENDER_API_KEY=wsk_your_api_key

const client = new WiiSenderClient({
  serverUrl: process.env.WIISENDER_SERVER_URL!,
  apiKey: process.env.WIISENDER_API_KEY!
});

API Compatibility

This SDK is compatible with WiiSender API v1.0+.

| SDK Version | API Version | |-------------|-------------| | 1.x | 1.0+ |

Support

For issues and feature requests, please visit: https://github.com/your-org/wiisender/issues

License

MIT