Installation

Tip

Checkout Quick Start for a more faster setup with the CLI tool.

Setup steps

Verify Node and package manager

node --version
npm --version

If node is missing or outdated, install a current LTS release first.

Initialize project

mkdir my-whatsapp-app
cd my-whatsapp-app
npm init -y

Install dependencies

Install the core library:

npm install whatsapp-web.js

Install a terminal QR renderer for local development:

npm install qrcode-terminal

puppeteer is managed by the dependency graph. Only override browser paths in special host environments.

Create baseline script

Create index.js with this setup:

const { Client, LocalAuth } = require('whatsapp-web.js')
const qrcode = require('qrcode-terminal')

const client = new Client({
  authStrategy: new LocalAuth(),
})

client.on('qr', qr => {
  qrcode.generate(qr, { small: true })
})

client.on('authenticated', () => {
  console.log('Authenticated')
})

client.on('ready', () => {
  console.log('Ready')
})

client.on('message_received', async msg => {
  if (msg.body === '!ping') {
    await msg.reply('pong')
  }
})

client.on('disconnected', reason => {
  console.log('Disconnected:', reason)
})

client.initialize()

Add scripts in package.json

{
  "scripts": {
    "start": "node index.js",
    "dev": "node index.js"
  }
}

First run

npm start

On first run, scan the QR code with WhatsApp Linked Devices.

Validation

Confirm these checkpoints:

authenticated appears after scanning.
ready appears next.
Sending !ping returns pong.
Restart does not require scanning again.

Common installation issues

Warning

If Chromium cannot start, stop and fix your runtime dependencies before adding more app logic.

Node version mismatch

Symptoms:

Install errors in dependencies.
Runtime errors on startup.

Fix:

Install current LTS.
Remove node_modules and package-lock.json.
Run npm install again.

Browser startup fails on servers

If your host has restricted sandbox settings or no GUI, use Puppeteer args explicitly.

const client = new Client({
  authStrategy: new LocalAuth(),
  puppeteer: {
    args: ['--no-sandbox', '--disable-setuid-sandbox'],
  },
})

QR code is not displayed

Verify that the process is still running.
Verify terminal rendering capability.
Add explicit logs inside the qr handler.