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.