WAHA
Get Started

🏭 Engines

Engines

What is Engine?

WAHA is a Node.js application that acts as a unified “glue layer” on top of multiple community-driven WhatsApp engines.

Under the hood, each engine is an independent open-source library that handles the actual WhatsApp communication:

  • WEBJS and WPP use a real browser (Chromium or Chrome) via Puppeteer
  • NOWEB communicates directly over WebSocket using a Node.js/TypeScript
  • GOWS communicates directly over WebSocket using a Golang library

WAHA wraps all of them behind one consistent REST API and webhook interface, so you can switch engines with a single environment variable change and minimal code adjustments on your side.

If something doesn’t work in one engine — just try another one!

API responses and webhook payloads may differ significantly, test your system before changing the engine!

Each Engine Has Its Own Namespace

WAHA uses 🗄️ Storage Namespace to isolate 🏭 Engines data.

There are two environment variables that control namespaces:

  • WAHA_NAMESPACE — controls the main storage (apps, API keys, shared config). Defaults to the current engine name.
  • WAHA_SESSION_NAMESPACE — controls session-specific storage (auth data, session files). Defaults to the current engine name.

👉🏻 Set WAHA_NAMESPACE=all to share apps, API keys, and common config across engines while switching between them:

.env
WAHA_NAMESPACE=all

# To share session authentication between WEBJS/WPP engines
# WAHA_SESSION_NAMESPACE=webjs

⚠️ Keep WAHA_SESSION_NAMESPACE unset in most cases. Changing it is an advanced setup and is not backward compatible with existing session data.

WEBJSWPPGOWSNOWEB
Run a browser (chromium\chrome) to communicate with WhatsApp✔️✔️
Communicate with WhatsApp via websocket (no browser)✔️✔️

Run Engine

Under the hood WAHA allows you to use different engines.

You can control what you want to run by settings WHATSAPP_DEFAULT_ENGINE environment variables.

docker run -it -e "WHATSAPP_DEFAULT_ENGINE=WEBJS" devlikeapro/waha

All engines are available in both Core and Plus versions.

WEBJS

A WhatsApp API client that connects through the WhatsApp Web browser app. It uses Puppeteer to run a real instance of Whatsapp Web to avoid getting blocked.

WHATSAPP_DEFAULT_ENGINE=WEBJS
👉 Read more about WEBJS

WPP

WPP engine to connect through the WhatsApp Web browser app. It uses Puppeteer to run a real instance of WhatsApp Web to avoid getting blocked.

WHATSAPP_DEFAULT_ENGINE=WPP
👉 Read more about WPP

GOWS

GOWS engine does not require a browser to work with WhatsApp Web, it does so directly using a WebSocket.

🚀 It’s a new generation engine written in Golang, a future replacement for NOWEB engine.

WHATSAPP_DEFAULT_ENGINE=GOWS
👉 Read more about GOWS

NOWEB

NOWEB engine does not require a browser to work with WhatsApp Web, it does so directly using a WebSocket. Not running Chromium saves you CPU and Memory, so you can run more instances on a single server!

WHATSAPP_DEFAULT_ENGINE=NOWEB
👉 Read more about NOWEB

Docker images

WAHA provides few docker images with different setup.

👉 Go to Docker Image Configurator to generate the command with the latest version and your key.

ImageCPUBrowser
WAHA Plus
devlikeapro/waha-plus:latestx86Chromium
devlikeapro/waha-plus:chromex86Chrome (supports video)
devlikeapro/waha-plus:nowebx86None
devlikeapro/waha-plus:gowsx86None
devlikeapro/waha-plus:armARMChromium
-ARMChrome
devlikeapro/waha-plus:noweb-armARMNone
WAHA Core
devlikeapro/waha:latestx86Chromium
devlikeapro/waha:chromex86Chrome
devlikeapro/waha:nowebx86None
-ARMChrome
devlikeapro/waha:armARMChromium
devlikeapro/waha:noweb-armARMNone
devlikeapro/{image}:{browser}[-cpu][-version]

{image}:

{browser}:

  • Chromium (latest) - is the default browser for WAHA. It’s a good choice for most cases.
  • Chrome (chrome) - is a good choice if you need to receive videos in Plus version.
  • None (noweb) - is a good choice if you want to use NOWEB engine.

{cpu}:

  • x86 - is a good choice for most cases.
  • ARM (-arm) - is a good choice if you’re using ARM processors (like Apple Silicon M1\M2, Raspberry Pi, etc.)

{version}:

  • latest - is the latest version of WAHA.
  • pinned - you can pin WAHA version by adding -{version} at the end of image tag.

Features

Some engines may not support certain features. Here, you will find a list of supported endpoints and webhooks per engine.

SymbolMeaning
✔️The engines supports the feature.
#123Feature request or bug for the endpoint
The feature available in WAHA Plus.

If you don’t specify WHATSAPP_DEFAULT_ENGINE environment variable - look at WEBJS engine, it’s the engine WAHA runs by default.

🖥️ Sessions

Read more about 🖥️ Sessions

🖥️ Sessions - API
APIWEBJSWPPNOWEBGOWS
List sessions
GET /api/sessions/		✔️✔️✔️✔️
Get session
GET /api/sessions/{name}		✔️✔️✔️✔️
Create session
POST /api/sessions/		✔️✔️✔️✔️
Update session
POST /api/sessions/{name}/		✔️✔️✔️✔️
Delete session
DELETE /api/sessions/{name}/		✔️✔️✔️✔️
Start session
POST /api/sessions/{name}/start		✔️✔️✔️✔️
Stop session
POST /api/sessions/{name}/stop		✔️✔️✔️✔️
Restart session
POST /api/sessions/{name}/restart		✔️✔️✔️✔️
Logout from a session
POST /api/sessions/logout		✔️✔️✔️✔️
Get screenshot
GET /api/screenshot		✔️✔️➖➖
Get me
GET /api/sessions/{session}/me		✔️✔️✔️✔️
Get QR
POST /api/{session}/auth/qr		✔️✔️✔️✔️
Request code
POST /api/{session}/auth/request-code		✔️✔️✔️✔️

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.

🖥️ Sessions - Events
EventsWEBJSWPPNOWEBGOWS
session.status✔️✔️✔️✔️
engine.event✔️✔️✔️✔️
state.change✔️✔️✔️✔️

📤 Messages

Read more about 📤 Send Messages and 📥 Receive Messages

📤 Messages - API
APIWEBJSWPPGOWSNOWEB
POST /api/sendText✔️✔️✔️✔️
POST /api/sendSeen✔️✔️✔️✔️
PUT /api/{session}/chats/{chatId}/messages/{messageId}✔️✔️✔️✔️
DELETE /api/{session}/chats/{chatId}/messages/{messageId}✔️✔️✔️✔️
POST /api/sendImage➕➕➕ ️➕
POST /api/sendFile➕➕➕ ️➕
POST /api/sendVoice➕➕➕ ️➕
POST /api/sendVideo➕➕➕ ️➕
POST /api/sendList➕➕
POST /api/send/link-custom-preview➕ ️➕
POST /api/forwardMessage✔️
#588		✔️✔️
POST /api/sendLocation✔️✔️✔️✔️
POST /api/startTyping✔️✔️✔️✔️
POST /api/stopTyping✔️✔️✔️✔️
POST /api/{session}/presence✔️✔️✔️✔️
POST /api/reaction✔️✔️✔️✔️
POST /api/star✔️✔️✔️
POST /api/sendContactVcard✔️✔️✔️✔️
GET /api/messages✔️✔️✔️¹
GET /api/checkNumberStatus✔️✔️✔️✔️
POST /api/send/buttons/reply➕
POST /api/{session}/media/convert/voice➕➕➕➕
POST /api/{session}/media/convert/video➕➕➕➕
  1. NOWEB - you need to Enable Store to get chats, contacts and messages

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.

📤 Messages - Events
EventsWEBJSWPPNOWEBGOWS
message✔️✔️✔️✔️
message.reaction✔️✔️✔️✔️
message.any✔️✔️✔️✔️
message.ack✔️✔️✔️✔️
message.waiting✔️
message.edited✔️✔️✔️✔️
message.revoked✔️✔️✔️✔️

🟢 Status

Read more about 🟢 Status

🟢 Status - API
APIWEBJSWPPNOWEBGOWS
Send Text Status
POST /api/{session}/status/text		✔️✔️✔️✔️
Send Image Status
POST /api/{session}/status/image		✔️➕✔️✔️
Send Voice Status
POST /api/{session}/status/voice		✔️➕✔️✔️
Send Video Status
POST /api/{session}/status/video		✔️➕✔️✔️
Delete Status
POST /api/{session}/status/delete		✔️✔️
Get New Status Message ID
GET /api/{session}/status/new-message-id		✔️✔️

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.

💬 Chats

Read more about 💬 Chats

💬 Chats - API
APIWEBJSWPPGOWSNOWEB
Get all chats
GET /api/{session}/chats		✔️✔️✔️✔️¹
Get chats overview
GET /api/{session}/chats/overview		✔️✔️✔️✔️¹
Get chat picture
GET /api/{session}/chats/{chatId}/picture		✔️✔️✔️✔️¹
Unread chat
POST /api/{session}/chats/{chatId}/unread		✔️✔️✔️✔️¹
Archive chat
POST /api/{session}/chats/{chatId}/archive		✔️✔️✔️¹
Unarchive chat
POST /api/{session}/chats/{chatId}/unarchive		✔️✔️✔️¹
Delete chat
DELETE /api/{session}/chats/{chatId}		✔️✔️
Read messages
POST /api/{session}/chats/{chatId}/messages/read		✔️✔️✔️✔️¹
Get messages
GET /api/{session}/chats/{chatId}/messages		✔️✔️✔️✔️¹
Get message by id
GET /api/{session}/chats/{chatId}/messages/{messageId}		✔️✔️✔️✔️¹
Pin message
POST /api/{session}/chats/{chatId}/messages/{messageId}/pin		✔️✔️
Unpin message
POST /api/{session}/chats/{chatId}/messages/{messageId}/unpin		✔️✔️
Edit message
PUT /api/{session}/chats/{chatId}/messages/{messageId}		✔️✔️✔️
Delete message
DELETE /api/{session}/chats/{chatId}/messages/{messageId}		✔️✔️✔️
Delete all messages
DELETE /api/{session}/chats/{chatId}/messages		✔️
  1. NOWEB - you need to Enable Store to get chats, contacts and messages

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.

💬 Chats - Events
EventsWEBJSWPPNOWEBGOWS
chat.archive✔️

👤 Contacts

Read more about 👤 Contacts

👤 Contacts - API
APIWEBJSWPPNOWEBGOWS
Get all contacts
GET /api/contacts/all		✔️✔️✔️*1✔️
Get contact
GET /api/contacts		✔️✔️✔️*1✔️
Update contact
PUT /api/{session}/contacts/{chatId}		✔️✔️✔️
Check phone number exists
GET /api/contacts/check-exists		✔️✔️✔️✔️
Get “about” contact
GET /api/contacts/about		✔️✔️
Get profile picture
GET /api/contacts/profile-picture		✔️✔️✔️✔️
Block contact
POST /api/contacts/block		✔️✔️
Unblock contact
POST /api/contacts/unblock		✔️✔️
  1. NOWEB - you need to Enable Store to get chats, contacts and messages
👤 Lids - API
APIWEBJSWPPNOWEBGOWS
Get Known LIDs
GET /api/{session}/lids		✔️✔️✔️*1✔️
Get Count of LIDs
GET /api/{session}/lids/count		✔️✔️✔️*1✔️
Get Phone Number by LID
GET /api/{session}/lids/{lid}		✔️✔️✔️*1✔️
Get LID by Phone Number
GET /api/{session}/lids/pn/{phoneNumber}		✔️✔️✔️*1✔️
  1. NOWEB - you need to Enable Store to get chats, contacts and messages

📢 Channels

Read more about 📢 Channels

📢 Channels - API
APIWEBJSWPPNOWEBGOWS
Search public channels
POST /api/{session}/channels/search/by-view		➕➕➕
Search public channels
POST /api/{session}/channels/search/by-text		➕✔️➕➕
“Views” for Search
GET /api/{session}/channels/search/views		➕➕➕➕
“Countries” for Search
GET /api/{session}/channels/search/countries		➕➕➕➕
“Categories” for Search
GET /api/{session}/channels/search/categories		➕➕➕➕
Get Messages from Channels (preview)
GET /api/{session}/channels/{invite}/messages/preview		➕✔️➕➕
Create Channel
POST /api/{session}/channels		#439✔️✔️✔️
Get channel - by id and invite code
GET /api/{session}/channels/{ChannelID}		✔️✔️✔️✔️
List channels
GET /api/{session}/channels		✔️✔️✔️✔️
Delete channel
DELETE /api/{session}/channels/{ChannelID}		✔️✔️
Get messages
GET /api/{session}/chats/{ChannelID}/messages		✔️✔️✔️
#433
Send messages - Text
POST /api/sendText		✔️✔️✔️✔️
Send messages - Image
POST /api/sendImage		✔️➕✔️✔️
Send messages - Video
POST /api/sendVideo		✔️➕✔️✔️
Send messages - Poll
POST /api/sendPoll
Receive messages - Text
message event		✔️✔️✔️✔️
Receive messages - Media
message event		✔️✔️✔️✔️
Receive messages - Polls✔️
Receive messages - Polls Votes (in my channel)
Receive messages - Reactions (in my channel)
Channels - follow, unfollow✔️✔️
Channels - mute, unmute✔️✔️
Admins - Send Invite
Admins - Revoke Invite
Admins - Accept Invite
Admins - Demote Admin

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.

👥 Groups

Read more about 👥 Groups

👥 Groups - API
APIWEBJSWPPNOWEBGOWS
POST /api/{session}/groups✔️✔️✔️✔️
GET /api/{session}/groups✔️✔️✔️✔️
GET /api/{session}/groups/count✔️✔️✔️✔️
GET /api/{session}/groups/join-info✔️✔️✔️✔️
POST /api/{session}/groups/join✔️✔️✔️✔️
GET /api/{session}/groups/{id}✔️✔️✔️✔️
DELETE /api/{session}/groups/{id}✔️✔️
POST /api/{session}/groups/{id}/leave✔️✔️✔️✔️
GET /api/{session}/groups/{id}/picture✔️✔️✔️✔️
PUT /api/{session}/groups/{id}/picture➕✔️➕➕
DELETE /api/{session}/groups/{id}/picture➕✔️➕➕
PUT /api/{session}/groups/{id}/description✔️✔️✔️✔️
PUT /api/{session}/groups/{id}/subject✔️✔️✔️✔️
GET /api/{session}/groups/{id}/invite-code✔️✔️✔️✔️
POST /api/{session}/groups/{id}/invite-code/revoke✔️✔️✔️✔️
GET /api/{session}/groups/{id}/settings/security/info-admin-only✔️✔️✔️✔️
PUT /api/{session}/groups/{id}/settings/security/info-admin-only✔️✔️✔️✔️
GET /api/{session}/groups/{id}/settings/security/messages-admin-only✔️✔️✔️✔️
PUT /api/{session}/groups/{id}/settings/security/messages-admin-only✔️✔️✔️✔️
GET /api/{session}/groups/{id}/participants✔️✔️✔️✔️
POST /api/{session}/groups/{id}/participants/add✔️✔️✔️✔️
POST /api/{session}/groups/{id}/participants/remove✔️✔️✔️✔️
POST /api/{session}/groups/{id}/admin/promote✔️✔️✔️✔️
POST /api/{session}/groups/{id}/admin/demote✔️✔️✔️✔️
👥 Groups - Events
EventsWEBJSWPPNOWEBGOWS
group.v2.join✔️✔️✔️✔️
group.v2.leave✔️✔️✔️✔️
group.v2.participants✔️✔️✔️✔️
group.v2.update✔️✔️✔️✔️
group.join✔️✔️
group.leave✔️

✅ Presence

Read more about ✅ Presence

✅ Presence - API
APIWEBJSWPPNOWEBGOWS
POST /api/{session}/presence✔️✔️✔️✔️
GET /api/{session}/presence/{chatId}✔️✔️✔️✔️
POST /api/{session}/presence/{chatId}/subscribe✔️✔️✔️✔️
GET /api/{session}/presence✔️✔️✔️

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.

✅ Presence - Events
EventsWEBJSWPPNOWEBGOWS
presence.update✔️✔️✔️✔️

🏷️ Labels

Read more about 🏷️ Labels

🏷️ Labels - API
APIWEBJSWPPNOWEBGOWS
Get labels
GET /api/{session}/labels		✔️✔️✔️✔️
Create label
POST /api/{session}/labels		✔️✔️✔️✔️
Update label
PUT /api/{session}/labels/{labelId}		✔️✔️✔️✔️
Delete label
DELETE /api/{session}/labels/{labelId}		✔️✔️✔️✔️
Get chats by label id
GET /api/{session}/labels/{labelId}/chats		✔️✔️✔️✔️
Get labels by chat id
GET /api/{session}/labels/chats/{chatId}/		✔️✔️✔️✔️
PUT labels to chat
PUT /api/{session}/labels/chats/{chatId}/		✔️✔️✔️✔️

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.

🏷️ Labels - Events
EventsWEBJSWPPNOWEBGOWS
label.upsert✔️✔️
label.deleted✔️✔️
label.chat.added✔️✔️✔️
label.chat.deleted✔️✔️✔️

📅 Event Message

Read more about 📅 Event Message

📅 Event Message - API
APIWEBJSWPPNOWEBGOWS
Send Event Message
POST /api/{SESSION}/events		✔️
📅 Event Message - Events
EventsWEBJSWPPNOWEBGOWS
event.response✔️
event.response.failed✔️

📶 Polls

Read more about 📶 Polls

📶 Polls - API
EventsWEBJSWPPGOWSNOWEB
POST /api/sendPoll✔️✔️✔️✔️
POST /api/sendPollVote➕➕

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.

📶 Polls - Events
EventsWEBJSWPPNOWEBGOWS
poll.vote✔️✔️✔️✔️
poll.vote.failed✔️✔️✔️

📞 Calls

Read more about 📞 Calls

📞 Calls - API
APIWEBJSWPPGOWSNOWEB
Reject call
POST /api/{session}/calls/reject		✔️✔️✔️✔️
📞 Calls - Events
EventsWEBJSWPPGOWSNOWEB
call.received✔️✔️✔️✔️
call.accepted✔️✔️
call.rejected✔️¹✔️✔️
  1. WEBJS - call.rejected works only when you rejected the call via API

🗄️ Storages

Read more about 🗄️ Storages

🗄️ Storages
StorageWEBJSWPPNOWEBGOWS
Local - 🖥️ Session✔️✔️✔️
Local - 🖼️ Media✔️✔️✔️
PostgresSQL - 🖥️ Session➕➕➕
PostgresSQL - 🖼️ Media➕➕➕
S3 - 🖼️ Media➕➕➕
MongoDB - 🖥️ Session➕➕❌
  • PostgreSQL, S3 and MongoDB storages are available in ➕ WAHA Plus
  • MongoDB is deprecated and no new features will be added to it.
  • Any S3 Compatible storage can be used, such as AWS S3, MinIO, DigitalOcean Spaces, etc. For in-house solutions, you can use MinIO.

🔍 Observability

Read more about 🔍 Observability

🔄 Events

Read more about 🔄 Events.

🖥️ Sessions - Events
EventsWEBJSWPPNOWEBGOWS
session.status✔️✔️✔️✔️
engine.event✔️✔️✔️✔️
state.change✔️✔️✔️✔️
📤 Messages - Events
EventsWEBJSWPPNOWEBGOWS
message✔️✔️✔️✔️
message.reaction✔️✔️✔️✔️
message.any✔️✔️✔️✔️
message.ack✔️✔️✔️✔️
message.waiting✔️
message.edited✔️✔️✔️✔️
message.revoked✔️✔️✔️✔️
💬 Chats - Events
EventsWEBJSWPPNOWEBGOWS
chat.archive✔️
👥 Groups - Events
EventsWEBJSWPPNOWEBGOWS
group.v2.join✔️✔️✔️✔️
group.v2.leave✔️✔️✔️✔️
group.v2.participants✔️✔️✔️✔️
group.v2.update✔️✔️✔️✔️
group.join✔️✔️
group.leave✔️
🏷️ Labels - Events
EventsWEBJSWPPNOWEBGOWS
label.upsert✔️✔️
label.deleted✔️✔️
label.chat.added✔️✔️✔️
label.chat.deleted✔️✔️✔️
✅ Presence - Events
EventsWEBJSWPPNOWEBGOWS
presence.update✔️✔️✔️✔️
📶 Polls - Events
EventsWEBJSWPPNOWEBGOWS
poll.vote✔️✔️✔️✔️
poll.vote.failed✔️✔️✔️
📞 Calls - Events
EventsWEBJSWPPGOWSNOWEB
call.received✔️✔️✔️✔️
call.accepted✔️✔️
call.rejected✔️¹✔️✔️
  1. WEBJS - call.rejected works only when you rejected the call via API
Edit this page on GitHub
Prev
📞 Calls
Next
⚙️ Configuration