neonize-node

Simple, powerful WhatsApp API for Node.js — powered by Neonize.

Features

• 🚀 Simple API - Send messages in just a few lines of code
• 📱 Full WhatsApp Support - Messages, media, groups, reactions, polls & more
• 🔒 Multi-Device - Works with WhatsApp's multi-device protocol
• ⚡ High Performance - Native Go library via FFI
• 📦 Zero Config - Just install and connect

Installation

npm install @azizemad/neonize-node

The native library is automatically downloaded on install.

Supported Platforms

| Platform | Architecture | Status | |----------|--------------|--------| | Windows | x64 | ✅ | | Linux | x64 | ✅ | | Linux | ARM64 | ✅ | | macOS | x64 | ✅ | | macOS | ARM64 (M1+) | ✅ |

Quick Start

Simple API (Recommended)

import { WhatsApp } from '@azizemad/neonize-node';

const wa = new WhatsApp();

wa.onMessage((msg) => {
    console.log(`${msg.sender}: ${msg.text}`);
    
    if (msg.text === 'ping') {
        msg.reply('pong 🏓');
    }
});

wa.onConnected(() => {
    console.log('Connected! My number:', wa.myNumber);
});

wa.connect();

Send Messages

// Text message
wa.send('1234567890', 'Hello from neonize-node!');

// Image with caption
wa.sendImage('1234567890', './photo.jpg', 'Check this out!');

// Document
wa.sendDocument('1234567890', './file.pdf', 'document.pdf');

// Poll
wa.sendPoll('1234567890', 'Best pizza topping?', ['Pepperoni', 'Mushrooms', 'Pineapple']);

Message Actions

wa.onMessage((msg) => {
    // Reply with quoted context
    msg.reply('Thanks for your message!');
    
    // React to the message
    msg.react('👍');
    
    // Delete the message (your own messages only)
    msg.delete();
    
    // Download media
    if (msg.hasImage) {
        const buffer = msg.downloadMedia();
        fs.writeFileSync('image.jpg', buffer);
    }
});

Groups

// Get all groups
const groups = wa.getGroups();

// Get group info
const info = wa.getGroupInfo('123456789-1234567890');

// Send to group (no validation needed)
wa.sendToGroup('123456789-1234567890', 'Hello group!');
wa.sendImageToGroup('123456789-1234567890', './photo.jpg', 'Check this!');
wa.sendDocumentToGroup('123456789-1234567890', './file.pdf', 'document.pdf');

// Typing in group
wa.startTypingInGroup('123456789-1234567890');
wa.stopTypingInGroup('123456789-1234567890');

Options

// Create with options
const wa = new WhatsApp({
    db: 'session.db',          // Database file
    autoOnline: true,          // Auto set online when connected
    autoRead: true,            // Auto send read receipts
});

Note: All send methods automatically validate that the recipient is registered on WhatsApp before sending. If a number is not on WhatsApp, an error is thrown.

Typing Indicators

// Show typing indicator
wa.startTyping('1234567890');

// Stop typing indicator
wa.stopTyping('1234567890');

// Show recording audio indicator
wa.startRecording('1234567890');

Read Receipts

wa.onMessage((msg) => {
    // Mark message as read (send blue ticks)
    msg.markRead();
    
    // Or use the WhatsApp instance method
    wa.markRead(msg);
});

Online Status

// Appear online
wa.setOnline();

// Appear offline
wa.setOffline();

Number Validation

// Check if number is on WhatsApp
const isValid = wa.checkNumber('1234567890');

// Check multiple numbers
const results = wa.isOnWhatsApp(['123456789', '987654321']);
results.forEach(r => {
    console.log(`${r.number}: ${r.isOnWhatsApp ? '✅' : '❌'}`);
});

Advanced API

For full control, use the NewClient class directly:

import { NewClient, Event, EventType } from '@azizemad/neonize-node';

const client = new NewClient('session.db');

// Set up event handling
client.event.onMessage((client, message) => {
    console.log('Received:', message);
});

client.event.onConnected((client) => {
    console.log('Connected!');
    
    // Full API access
    client.sendMessage(jid, { conversation: 'Hello!' });
    client.sendReaction(chatJid, senderJid, messageId, '❤️');
    client.editMessage(chatJid, messageId, 'Edited text');
    // ... and 90+ more methods
});

await client.connect();

API Reference

WhatsApp Class (Simple API)

| Method | Description | |--------|-------------| | onMessage(handler) | Handle incoming messages | | onConnected(handler) | Handle connection | | onQR(handler) | Handle QR code display | | onDisconnected(handler) | Handle disconnection | | send(to, text) | Send text message | | sendImage(to, image, caption?) | Send image | | sendVideo(to, video, caption?) | Send video | | sendDocument(to, doc, filename) | Send document | | sendPoll(to, question, options) | Send poll | | getGroups() | Get joined groups | | getGroupInfo(groupId) | Get group details | | setOnline() | Set online status | | setOffline() | Set offline status | | startTyping(to) | Show typing indicator | | stopTyping(to) | Hide typing indicator | | startRecording(to) | Show recording indicator | | markRead(message) | Send read receipt | | isOnWhatsApp(numbers) | Check if numbers on WhatsApp | | checkNumber(number) | Check single number | | connect() | Start connection | | disconnect() | Close connection | | logout() | Logout and clear session |

Message Class

| Property | Description | |----------|-------------| | text | Message text content | | sender | Sender's phone number | | chatId | Chat identifier | | id | Message ID | | isGroup | Is from a group? | | isFromMe | Is from yourself? | | hasImage | Has image attachment? | | hasVideo | Has video attachment? | | hasDocument | Has document attachment? |

| Method | Description | |--------|-------------| | reply(text) | Reply with quoted context | | react(emoji) | React with emoji | | delete() | Delete/revoke message | | markRead() | Send read receipt | | downloadMedia() | Download media as Buffer |

Configuration

Database Location

The session is stored in a SQLite database. Default is neonize.db in the current directory.

const wa = new WhatsApp('my-session.db');

Logging

Enable debug logging:

const client = new NewClient('session.db', {
    logLevel: 'DEBUG' // DEBUG, INFO, WARN, ERROR
});

client.event.debug(true);

Requirements

• Node.js 18.0.0 or higher
• Windows, Linux, or macOS (x64 or ARM64)

Troubleshooting

"Could not find goneonize library"

The native library wasn't downloaded. Run manually:

node node_modules/@azizemad/neonize-node/scripts/download.js

"Couldn't link device" on QR scan

This usually means the session is corrupted. Delete the .db file and try again.

Credits

• Neonize - The Go library powering this package
• whatsmeow - WhatsApp Web API implementation

License

MIT © See LICENSE for details.