waha-node

v1.0.0

Published

4 months ago

Unofficial WhatsApp HTTP API (WAHA) Node.js Client - Complete implementation of WAHA API

Downloads

0High
0Medium
0Low

teguh02

waha whatsapp api client node nodejs typescript

WAHA Node.js

Unofficial Node.js client library for WAHA (WhatsApp HTTP API) - a powerful solution to interact with WhatsApp Web through HTTP API.

Features

✅ Complete API Coverage - Support for all WAHA endpoints

📤 Send Messages: Text, Image, Video, Voice, File, Location, Contact, Poll
📥 Receive Messages: Webhooks and Event Handling
💬 Chats Management: List, Archive, Read, Delete
👤 Contacts Management: Get, Update, Block, Check Existence
👥 Groups Management: Create, Manage, Admin Controls
🟢 Status Management: Send and Manage WhatsApp Status
📢 Channels Management: Create and Manage Channels
🔐 Session Management: Create, Start, Stop, QR Code
And much more!

✅ Simple & Intuitive - Clean, modern API design ✅ TypeScript Support - Full TypeScript definitions ✅ Error Handling - Comprehensive error handling ✅ Documentation - Complete documentation and examples

Installation

npm install waha-node

Or using yarn:

yarn add waha-node

Or using pnpm:

pnpm add waha-node

Or install from source:

git clone https://github.com/teguh02/waha-node.git
cd waha-node
npm install
npm run build

Quick Start

1. Start WAHA Server

First, you need to have WAHA server running. Follow the Quick Start Guide:

docker pull devlikeapro/waha
docker run -it --env-file .env -v "$(pwd)/sessions:/app/.sessions" --rm -p 3000:3000 --name waha devlikeapro/waha

2. Use the Node.js Client

import { WahaClient } from 'waha-node';

// Initialize the client
const client = new WahaClient(
  'http://localhost:3000',
  'your-api-key-here'  // Optional, if you set WAHA_API_KEY
);

// Send a text message
const result = await client.messages.sendText(
  'default',
  '[email protected]',
  'Hello from Node.js! 👋'
);

console.log(result);

3. Create Session with QR Code

// Create a new session
const session = await client.sessions.create(
  'my_session',
  {
    webhooks: [{
      url: 'https://your-webhook-url.com/webhook',
      events: ['message']
    }]
  }
);

// Get QR code for authentication
const qrCode = await client.sessions.getQr('my_session', 'image', true);
console.log(`QR Code (Base64): ${qrCode.data}`);

// Scan the QR code with your WhatsApp app
// The session status will change to WORKING

4. Receive Messages with Webhooks

Create a webhook server (example with Express):

import express from 'express';
import { WahaClient } from 'waha-node';

const app = express();
const client = new WahaClient('http://localhost:3000', 'your-api-key');

app.use(express.json());

app.post('/webhook', async (req, res) => {
  const data = req.body;
  
  if (data.event === 'message') {
    const payload = data.payload;
    const fromNumber = payload.from;
    const messageText = payload.body || '';
    
    console.log(`Received: ${messageText} from ${fromNumber}`);
    
    // Reply to the message
    await client.messages.sendText(
      data.session,
      fromNumber,
      `You said: ${messageText}`
    );
  }
  
  res.json({ status: 'ok' });
});

app.listen(3001, () => {
  console.log('Webhook server running on port 3001');
});

Complete Examples

Send Different Types of Messages

import { WahaClient } from 'waha-node';

const client = new WahaClient('http://localhost:3000', 'your-api-key');

// Send text message
await client.messages.sendText(
  'default',
  '[email protected]',
  'Hello World!'
);

// Send image with URL
await client.messages.sendImage(
  'default',
  '[email protected]',
  { url: 'https://example.com/image.jpg', mimetype: 'image/jpeg' },
  'Check this out!'
);

// Send image from file
await client.messages.sendImage(
  'default',
  '[email protected]',
  'path/to/image.jpg',
  'My image'
);

// Send video
await client.messages.sendVideo(
  'default',
  '[email protected]',
  { url: 'https://example.com/video.mp4', mimetype: 'video/mp4' }
);

// Send voice message
await client.messages.sendVoice(
  'default',
  '[email protected]',
  { url: 'https://example.com/voice.opus', mimetype: 'audio/ogg; codecs=opus' }
);

// Send document
await client.messages.sendFile(
  'default',
  '[email protected]',
  { url: 'https://example.com/document.pdf', mimetype: 'application/pdf' }
);

// Send location
await client.messages.sendLocation(
  'default',
  '[email protected]',
  38.8937255,
  -77.0969763,
  'My Location'
);

// Send contact
await client.messages.sendContact(
  'default',
  '[email protected]',
  [{
    fullName: 'John Doe',
    organization: 'Company',
    phoneNumber: '+91 11111 11111',
    whatsappId: '911111111111'
  }]
);

// Send poll
await client.messages.sendPoll(
  'default',
  '[email protected]',
  {
    name: 'How are you?',
    options: ['Awesome!', 'Good!', 'Not bad!'],
    multipleAnswers: false
  }
);

Manage Sessions

// List all active sessions
const sessions = await client.sessions.list();

// List all sessions including stopped ones
const allSessions = await client.sessions.list(true);

// Get specific session
const session = await client.sessions.getSession('default');

// Create session
const newSession = await client.sessions.create('my_session', { webhooks: [] });

// Start session
await client.sessions.start('my_session');

// Stop session
await client.sessions.stop('my_session');

// Restart session
await client.sessions.restart('my_session');

// Logout session
await client.sessions.logout('my_session');

// Delete session
await client.sessions.delete('my_session');

// Get QR code
const qr = await client.sessions.getQr('default', 'image', true);

// Request pairing code
const codeInfo = await client.sessions.requestCode('default', '12132132130');
console.log(`Pairing code: ${codeInfo.code}`);

Manage Chats

// List all chats
const chats = await client.chats.list('default');

// Get chat picture
const picture = await client.chats.getPicture('default', '[email protected]');

// Archive chat
await client.chats.archive('default', '[email protected]');

// Unarchive chat
await client.chats.unarchive('default', '[email protected]');

// Mark as unread
await client.chats.unread('default', '[email protected]');

// Read messages
await client.chats.readMessages('default', '[email protected]');

// Get messages
const messages = await client.chats.getMessages('default', '[email protected]', 100);

// Get specific message
const message = await client.chats.getMessage('default', '[email protected]', 'message_id_here');

// Delete chat
await client.chats.delete('default', '[email protected]');

Manage Contacts

// List all contacts
const contacts = await client.contacts.listAll('default');

// Get specific contact
const contact = await client.contacts.getContact('default', '1234567890');

// Update contact
await client.contacts.update('default', '[email protected]', 'John', 'Doe');

// Check if phone exists
const result = await client.contacts.checkExists('default', '1234567890');
if (result.numberExists) {
  console.log(`Chat ID: ${result.chatId}`);
}

// Get contact about
const about = await client.contacts.getAbout('default', '1234567890');

// Get profile picture
const profilePic = await client.contacts.getProfilePicture('default', '1234567890');

// Block contact
await client.contacts.block('default', '[email protected]');

// Unblock contact
await client.contacts.unblock('default', '[email protected]');

Manage Groups

// List all groups
const groups = await client.groups.list('default');

// Get specific group
const group = await client.groups.get('default', '[email protected]');

// Create group
const newGroup = await client.groups.create('default', 'My New Group', ['[email protected]']);

// Update group name
await client.groups.updateSubject('default', '[email protected]', 'Updated Name');

// Update group description
await client.groups.updateDescription('default', '[email protected]', 'Description');

// Get invite code
const inviteCode = await client.groups.getInviteCode('default', '[email protected]');

// Revoke invite code
await client.groups.revokeInviteCode('default', '[email protected]');

// Get participants
const participants = await client.groups.getParticipants('default', '[email protected]');

// Add participants
await client.groups.addParticipants('default', '[email protected]', ['[email protected]']);

// Remove participants
await client.groups.removeParticipants('default', '[email protected]', ['[email protected]']);

// Promote to admin
await client.groups.promoteAdmin('default', '[email protected]', ['[email protected]']);

// Demote from admin
await client.groups.demoteAdmin('default', '[email protected]', ['[email protected]']);

// Leave group
await client.groups.leave('default', '[email protected]');

Manage Status (Stories)

// Send text status
await client.status.sendText('default', 'My status update');

// Send image status
await client.status.sendImage('default', { url: 'https://example.com/image.jpg', mimetype: 'image/jpeg' });

// Send video status
await client.status.sendVideo('default', { url: 'https://example.com/video.mp4', mimetype: 'video/mp4' });

// Send voice status
await client.status.sendVoice('default', { url: 'https://example.com/voice.opus', mimetype: 'audio/ogg; codecs=opus' });

// Delete status
await client.status.delete('default', 'message_id_here');

// Get new message ID
const messageId = await client.status.getNewMessageId('default');

Manage Channels

// List all channels
const channels = await client.channels.list('default');

// Get specific channel
const channel = await client.channels.get('default', 'channel_id');

// Create channel
const newChannel = await client.channels.create('default', 'My Channel', 'Description');

// Get channel messages
const messages = await client.channels.getMessages('default', 'channel_id', 100);

// Delete channel
await client.channels.delete('default', 'channel_id');

Message Reactions and Actions

// Add reaction
await client.messages.addReaction('default', 'message_id_here', '👍');

// Remove reaction
await client.messages.addReaction('default', 'message_id_here', '');

// Star message
await client.messages.starMessage('default', '[email protected]', 'message_id_here');

// Unstar message
await client.messages.starMessage('default', '[email protected]', 'message_id_here', false);

// Edit message
await client.messages.editMessage('default', '[email protected]', 'message_id_here', 'Updated message');

// Delete message
await client.messages.deleteMessage('default', '[email protected]', 'message_id_here');

// Forward message
await client.messages.forwardMessage('default', '[email protected]', 'message_id_here');

// Pin message
await client.messages.pinMessage('default', '[email protected]', 'message_id_here');

// Unpin message
await client.messages.unpinMessage('default', '[email protected]', 'message_id_here');

Error Handling

import { WahaClient, WahaAuthenticationException, WahaNotFoundException } from 'waha-node';

try {
  const client = new WahaClient('http://localhost:3000', 'wrong-key');
  const result = await client.messages.sendText('default', '[email protected]', 'Hello');
} catch (error) {
  if (error instanceof WahaAuthenticationException) {
    console.log('Authentication failed');
  } else if (error instanceof WahaNotFoundException) {
    console.log('Resource not found');
  } else {
    console.log('Error:', error.message);
  }
}

Requirements

Node.js 14.0+
axios library
WAHA server running (see Quick Start Guide)

Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Support

npm Package: https://www.npmjs.com/package/waha-node
GitHub Issues: https://github.com/teguh02/waha-node/issues
WAHA Documentation: https://waha.devlike.pro

Important Disclaimer

This is an UNOFFICIAL community project and is not affiliated, associated, authorized, endorsed by, or in any way officially connected with:

WhatsApp LLC or any of its subsidiaries or affiliates
WAHA (devlikeapro) team

The official WhatsApp website can be found at whatsapp.com.
The official WAHA documentation can be found at waha.devlike.pro.

"WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners.

Usage Warning

This library interacts with WhatsApp through unofficial means. There are risks associated with using unofficial WhatsApp clients:

Account suspension or banning
Security risks
Data privacy concerns
No official support

Use at your own risk. For business applications, we recommend using the official WhatsApp Business API.