pedroslopez /whatsapp-web.js
A WhatsApp client library for NodeJS that connects through the WhatsApp Web browser app
★ 22,911⑂ 5,206👁 359⑃ 1,385● 3,088▤ 125
+2
日增长
+60
周增长
+172
月增长
22,911
stars
5,206
forks
359
watchers
1,385
prs
3,088
issues
125
releases
README
About
whatsapp‑web.js is a powerful [Node.js][nodejs] library that lets you interact with WhatsApp Web, making it easy to build a dynamic WhatsApp API with nearly all features of the web client. It uses [Puppeteer][puppeteer] to access WhatsApp Web’s internal functions and runs them in a managed browser instance to reduce the risk of being blocked.
Links
- [GitHub][gitHub]
- [Guide][guide] ([source][guide-source])
- [Documentation][documentation] ([source][documentation-source])
- [Discord Server][discord]
- [npm][npm]
Installation
Node.js v18.0.0 or higher, is required.
sh
npm install whatsapp-web.js
yarn add whatsapp-web.js
pnpm add whatsapp-web.js
Having trouble installing? Take a peak at the [Guide][guide] for more detailed instructions.
Example usage
js
const { Client } = require('whatsapp-web.js');
const qrcode = require('qrcode-terminal');
const client = new Client();
client.on('qr', (qr) = {
qrcode.generate(qr, { small: true });
});
client.on('ready', () = {
console.log('Client is ready!');
});
client.on('message', (msg) = {
if (msg.body == '!ping') {
msg.reply('pong');
}
});
client.initialize();
Take a look at [example.js][examples] for additional examples and use cases.
For more details on saving and restoring sessions, check out the [Authentication Strategies][auth-strategies].
Supported features
| Feature | Status |
| ------------------------------------------------ | -------------------------------------------- |
| Multi Device | ✅ |
| Send messages | ✅ |
| Receive messages | ✅ |
| Send media (images/audio/documents) | ✅ |
| Send media (video) | ✅ [(requires Google Chrome)][google-chrome] |
| Send stickers | ✅ |
| Receive media (images/audio/video/documents) | ✅ |
| Send contact cards | ✅ |
| Send location | ✅ |
| Send buttons | ❌ [(DEPRECATED)][deprecated-video] |
| Send lists | ❌ [(DEPRECATED)][deprecated-video] |
| Receive location | ✅ |
| Message replies | ✅ |
| Join groups by invite | ✅ |
| Get invite for group Top issues
#3834Error: No LID for user33 comments · 2025-09-25#5728Detached Frame Error After ~1 Hour Runtime30 comments · 2026-01-17#201838Puppeteer error r: r on getChatById after latest WhatsApp Web update23 comments · 2026-07-15#201862Errors r: r on client.getChats() and t: t on client.sendMessage(media)18 comments · 2026-07-27#201833Message.downloadMedia() throws opaque r: r for all incoming media16 comments · 2026-07-15#2764Group Messages - "Waiting for this message. This may take a while."14 comments · 2024-02-06#201908downloadMedia() fails for uncached images with InvalidMediaFileType when mimetype is not forwarded13 comments · 2026-09-02#201845Client.getState() and Client.getChats() throws r: r despite client being CONNECTED and WhatsApp Web fully loaded13 comments · 2026-07-16
Latest release
v1.34.8 v1.34.8 2026-11-12What's Changed fix: block unblock contact by @BenyFilho in https://github.com/wwebjs/whatsapp-web.js/pull/201753 refactor: auth store handling by @RC047 in https://github.com/wwebjs/whatsapp-web.js/pull/201667 feat: support big file downloads (read from WA cache + streaming) by @Adi1231234 in https://github.com/wwebjs/whatsapp-web.js/pull/201697 fix: prevent duplicate ready events on SPA re-injection by @Adi1231234 in https://github.com/wwebjs/whatsapp-web.js/pull/201653 fix: use WWebJS.getChat for inviteV4 fallback in addParticipants by @ashmitmittal in https://github.com/wwebjs/whatsapp