DEV Community: WAHA -Self-Hosted WhatsApp API

WAHA 2025.2 - Search Channels API, Profile API and more!

WAHA -Self-Hosted WhatsApp API — Fri, 28 Feb 2025 05:05:50 +0000

🎉 We are thrilled to announce the changes we made during the WAHA 2025.2 🎉

https://waha.devlike.pro/blog/waha-2025-2/

WAHA 2025.1 - PostgreSQL support, GOWS engine and More!

WAHA -Self-Hosted WhatsApp API — Sun, 02 Feb 2025 07:38:49 +0000

WAHA 2025.1

GOWS engine

Meet GOWS – a new, fast, super-reliable, and stable Engine for your WAHA instance!

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

It's a new-generation engine written in Golang, intended as a future replacement for the NOWEB engine.

You can test it by setting the WHATSAPP_DEFAULT_ENGINE=GOWS environment variable:

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

Read more about GOWS; it doesn't support all features yet, but we're working on it!

PostgreSQL support

Now you can use PostgreSQL as a Storage solution for your WAHA instance!

Storage	WEBJS	NOWEB	GOWS
Session - PostgreSQL	✔️	✔️	✔️
Media - PostgreSQL	✔️	✔️	✔️

It works with both Session Storage and Media Storage, supports all engines, and is available in WAHA Plus.

How to connect to your PostgreSQL instance?

Connect Session Storage:

docker run -p 3000:3000/tcp -it -e WHATSAPP_SESSIONS_POSTGRESQL_URL=postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable devlikeapro/waha-plus

Set WHATSAPP_SESSIONS_POSTGRESQL_URL with your credentials and database name.

Connect Media Storage:

docker run -p 3000:3000/tcp -it -e WAHA_MEDIA_STORAGE=POSTGRESQL -e WAHA_MEDIA_POSTGRESQL_URL=postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable devlikeapro/waha-plus

Set WAHA_MEDIA_POSTGRESQL_URL with your credentials and database name.
Set WAHA_MEDIA_STORAGE=POSTGRESQL to enable PostgreSQL as a media storage.

You can use the same connection URL for WAHA_MEDIA_POSTGRESQL_URL and WHATSAPP_SESSIONS_POSTGRESQL_URL if you want to use the same database for both storages.

And More!

Check out the full WAHA 2025.1 Changelog for more details!

WAHA 2024.11 | What Have We Done 😱

WAHA -Self-Hosted WhatsApp API — Tue, 03 Dec 2024 02:02:57 +0000

🎉 We are thrilled to announce the release of WAHA 2024.11 🎉

👉 You can read it in the blog

WAHA 2024.10 - Receive Media in Core, n8n Integration, and more!

WAHA -Self-Hosted WhatsApp API — Tue, 01 Oct 2024 04:30:53 +0000

🎉 We are thrilled to announce the release of WAHA 2024.10 🎉

WAHA Core - Receive Media

We published 📥 Receive messages in free WAHA Core version, so you can receive media files in your WhatsApp API for free!

We’ll continue to publish features from ➕ WAHA Plus to WAHA Core, so you can use them for free!

n8n Low Code Integration

Meat the new WAHA integration with n8n!

You can build your WhatsApp automation with using n8n and WAHA in pair!

For that we’ve built @devlikeapro/n8n-nodes-waha directly from our Swagger specification, so all available API calls are available in n8n.

Install it on your n8n instance and start building your first workflow:

@devlikeapro/n8n-nodes-waha

Read more about 🧩 n8n Integration

Stability fixes

We’re working on internal things to stabilize the product, to avoid any issues with the API.

Check the full 🆕 Changelog for more details!

WhatsApp Automation No Code Low Code Step-By-Step Guide - WAHA + n8n

WAHA -Self-Hosted WhatsApp API — Mon, 09 Sep 2024 04:31:11 +0000

https://waha.devlike.pro/blog/waha-n8n/

Here's how you can start developing your WhatsApp automation with using n8n and WAHA in pair so you can create
your own no-code or low-code WhatsApp automation:

Installation

Here's a quick docker-compose we have prepared for you to start using n8n with WAHA:

wget https://raw.githubusercontent.com/devlikeapro/waha/core/docker-compose.n8n.yaml
mv docker-compose.n8n.yaml docker-compose.yaml

If you're using WAHA Plus (donation version) - kindly go to https://portal.devlike.pro and docker pull the image with your credentials:

docker login -u devlikeapro -p <dckr_pat_1111111111>
docker pull devlikeapro/waha-plus
docker logout

If you're using WAHA Core (free version) - you can use the image from Docker Hub:

sed -i 's/devlikeapro\/waha-plus/devlikeapro\/waha/g' docker-compose.yaml

Now you're ready to run:

docker compose up 
# to run in background:
# docker compose up -d

After that, open:

n8n at https://localhost:5678 and set up your email/password
WAHA at https://localhost:3000/dashboard (waha/waha)

Install WAHA n8n node

We provide WAHA Node, which you can install at your n8n installation.

Go to your n8n => Settings => Community nodes and install:

@devlikeapro/n8n-nodes-waha

If you need help with that, check the
Install community nodes

First WhatsApp workflow

We'll build simple workflow - when your WhatsApp account got any message,
it responds with "Hi there" message

Step 1: Add WAHA API credentials

Before starting using the node, you need to add WAHA API credentials.

Go to your n8n => Home => Credentials => Add first credential
Find WAHA API in dropdown
Host URL - http://waha:3000 or use your domain
API Key - 321 or your API key set in docker-compose.yaml
Click Save - it'll check the connection and save the credentials

If you need help with that, check the
Create credentials

Step 2: Create a new workflow

Go to n8n => Home => Workflows => Create new workflow.
Remove Manual trigger

Step 3: Add WAHA Trigger

Add WAHA Trigger node.

Step 4: Add Send a text message action

Add Send a text message WAHA Action and connect it to message WAHA Trigger output:

Step 5: Activate the workflow

Click Save and Activate the workflow:

Step 6: Start a new session

Open the WAHA Trigger and expand Webhook URLs => Production URL

Go to http://localhost:3000/dashboard/ (waha/waha) and
Start New session with the URL you got from the WAHA Trigger:

Scan QR and wait till session in WORKING state:

Step 7: Send a message

Now you can send any message to your WhatsApp account, and it'll respond with "Hi there" message!

Workflow Templates

👉 Check out
https://waha-n8n-workflows.devlike.pro
for workflow templates!

Troubleshooting

If you're experiencing any issues or have a feature request, please check the below resources:
WAHA:

n8n:

If that doesn't help - kindly open an issue in the
devlikeapro/n8n-nodes-waha
GitHub repository, we're happy to help you out!

🎉WAHA 2024.9 - S3, Session API, Metadata, Dashboard and more!🎉

WAHA -Self-Hosted WhatsApp API — Tue, 27 Aug 2024 12:05:49 +0000

🎉 We are thrilled to announce the release of WAHA 2024.9 🎉

Kingly go and read the blog, it's hard to copy-paste everything 😅

https://waha.devlike.pro/blog/waha-2024-9/

Thank you all for your support! 🙏

All these changes were made possible by the amazing community of supporters!

We are grateful for your contributions and feedback. 🚀

WAHA Scaling - How To Handle 500+ WhatsApp Sessions

WAHA -Self-Hosted WhatsApp API — Sun, 18 Aug 2024 03:30:12 +0000

Overview

The article is for people who want to scale their WhatsApp API for customers, like CRM, SaaS, or other services and who needs to handle a lot (>100) of 🖥️ Sessions (WhatsApp Accounts)

If you’re using WAHA for 1-10 sessions - just make sure to follow 🔧 Install & Update guide. It handles all the necessary steps to make it work. 🚀

There are two ways to scale WAHA:

Vertical Scaling - adding more resources (CPU, RAM) to the single server to handle more sessions. That’s a good way to go if you need to handle up to 50 sessions (WEBJS) or 500 sessions (NOWEB).
Horizontal Scaling - adding more servers to handle more sessions. Requires a bit of more work to set up, but it’s the best way to go if you need to handle more than 500 sessions.

Vertical Scaling

Vertical Scaling is the process of adding more resources (CPU, RAM) to the single server to handle more sessions.

Assuming you’ve followed the guide 🔧 Install & Update and you got something like this architecture:

How many sessions you can run adding more resources (CPU and RAM) to the single WAHA server?
Here’s approximate example how many session you can run on a single server using Vertical Scaling approach:

🏭 Engine	Sessions	CPU	Memory
WEBJS	10	270%	2.5GB
WEBJS	50	1500%	20GB
NOWEB	50	150%	4GB
NOWEB	500	300%	30GB

👉 The benchmark may differ from case to case, it depends on usage pattern - how many messages you get, how many send, etc.

So if you need to run up to 50 session on WEBJS engine or up to 500 sessions on NOWEB - you can just keep adding more resources (CPU and RAM) to the single server! Fast to scale, easy to manage.🎉

If you want to run more sessions - you need to consider Horizontal Scaling. It’s not safe to run more than the above numbers on a single server!

Horizontal Scaling

Horizontal Scaling is the process of adding more servers to handle more sessions.

Right now the only way to do it is to run multiple WAHA instances and distribute the sessions between them in Your Application logic using Sharding technique:

Here’s key points how to set up Horizontal Scaling using Sharding technique:

You run multiple WAHA instances listening different hostnames (http://waha1.example.com, http://waha2.example.com, etc) or ports (http://waha.example.com:3001, http://waha.example.com:3002, etc).
You save the list of url, api-key, capacity to Your Application Database - Entities Schema
When a new user asks to run a new session - you follow Where to run a new session? logic to find a suitable WAHA instance and save user <-> session <-> server association to Your Application Database.
When you need to send a request to WhatsApp API - you follow Where to find the session? logic to find the WAHA instance to send the request.
All webhooks come to Your Application directly from the WAHA instance, so you don't need to worry about it.

We'll guide you through the process of setting up Horizontal Scaling
using Sharding technique in the next sections.

👉 Please note that each WAHA Worker must have its own database -
either File Storage or MongoDB URL (not a database). Otherwise, the WHATSAPP_RESTART_ALL_SESSIONS=True
option will restart ALL sessions in ALL workers on worker restart (you'll need disable it and run the session
restart logic in your application).

Entities Schema

In order to save WAHA instances and sessions associations you
need to have the following entities in Your Application Database:

Worker

Worker represents a single WAHA instance that can handle sessions.

id - unique identifier
url - URL of the WAHA instance, http://waha1.example.com, http://waha2.example.com, etc
api_key - API Key to authorize requests
capacity - how many sessions can be run on the WAHA instance (for simplicity, we're using a single field, but it can be a new model AvailableSession or similar).

By setting capacity you can manage the WAHA Worker usage and prevent overloading.

User

User is a user of Your Application that can run sessions.

id - unique identifier

👉 You can use either User or Tenant or Organization it completely depends on your application logic
and business model.
We'll use User for simplicity with a single field:

WAHASession

WAHASession represents a single session that is running on the WAHA Worker associated with the User.

id - unique identifier
name - WAHA session name
user_id - reference to the User
worker_id - reference to the Worker

Where to run a new session?

When a new user asks to run a new session - you need to find a suitable WAHA instance to run it.
You can simply get a list of session with capacity>0 and pick the one with the highest capacity.

It's just an example with simple logic. You can adjust it and distribute WhatsApp session based on country, proxy
settings,
customer level, etc.

Where to find the session?

When you need to send a request to WhatsApp API - you need to find the WAHA instance to send the request.
You can simply get the worker_id from the WAHASession and send the request to the WAHA instance using
the url and api_key.

Why this way?

WAHA is not stateless application, it has a runtime state (not technically a state as in database, but still a
state) - the connection to WhatsApp (either browser or websocket connection) which can not be moved automatically,
so all HTTP requests MUST be "sticky", meaning it MUST go only to the certain "worker" - one with "running" session.

This is why we can simply run more containers using Kubernetes Deployment/AWS ECS
(tho you can use StatefulSets for k8s)
, we need to care about WHERE we run the session and WHERE we send the request.

and few more reasons:

Simple - you don't need to worry about the load balancer, k8s, docker, etc.
Independent - you can run WAHA instances on different servers, different cloud providers, bare-metal, etc.
No single point of failure - if one WAHA instance goes down - the others are still working.
Flexible - you can configure HOW you distribute sessions across different servers based on your business logic.
Frees our hands - we can focus on building the best WhatsApp API and adding new features, and you can focus on building the best application. 😊

Single Dashboard - Multiple Servers

If you're running multiple servers
you can run a dedicated WAHA 📊 Dashboard just to have a single place where from you can manage all servers:

After that you can connect all server to the single dashboard:

WAHA 2024.8 - WhatsApp Business Labels API, Chat Archive and more!

WAHA -Self-Hosted WhatsApp API — Sun, 04 Aug 2024 05:14:59 +0000

🎉 We are thrilled to announce the release of WAHA 2024.8 🎉

WhatsApp Business Labels API

You can now work with WhatsApp Labels available in WhatsApp Business using the API!

👉 Read more about the WhatsApp Business Labels API on 🏷️ Labels page!

Chat archive/unarchive

You can now archive and unarchive WhatsApp Chats using API and receive events about chat archive in WhatsApp using webhooks!

👉 Read more about the endpoints and events on 💬 Chats page!

Calls Events

Now when the WhatsApp account receives (rejects and accepts) a new call - you can receive information about that using new call.* webhooks!

👉 Read more about the events on 📞 Calls page!

And more!

👉 Read the full 🆕 Changelog for WAHA 2024.8 release!

WAHA 2024.7 - WhatsApp Channels API, JSON logs

WAHA -Self-Hosted WhatsApp API — Wed, 24 Jul 2024 12:04:10 +0000

🎉 We are thrilled to announce the release of WAHA 2024.7 🎉

WhatsApp Channels API

WAHA now supports WhatsApp Channels - a brand-new feature introduced by WhatsApp.
You can manage, read and send messages to WhatsApp Channels (aka Newsletters) via API.

👉 Read more about available features on 📰 Channels documentation page.

💡 If you're completely new with the project, we wrote a
Step-By-Step Guide on How to send a post to WhatsApp Channel via API

JSON logs

WAHA now supports JSON logs. You can enable it by setting WAHA_LOG_FORMAT=JSON environment variable.
WAHA_LOG_FORMAT - supports formats:

WAHA_LOG_FORMAT=PRETTY - good for local development, default format
WAHA_LOG_FORMAT=JSON - can be useful if you're using central logging management system

👉 Learn more about logging configuration on 🔍 Observability page.

How to send a message to WhatsApp Channel via API

WAHA -Self-Hosted WhatsApp API — Wed, 24 Jul 2024 12:01:24 +0000

WAHA, Free Self-Hosted WhatsApp API, supports WhatsApp Channels, a brand-new feature introduced by WhatsApp.

It is a one-way broadcast tool that allows administrators to send various content types such as text, photos, videos, and polls.
Users receive push notifications from the channel, similar to a private message.

In this article, we give you a Step-By-Step guide how to send messages to WhatsApp Channels using WAHA - free, self-hosted WhatsApp API!

We'll install it on your own laptop or server, so no suspicious services have access to your WhatsApp account.

Step 0. Requirements

WAHA works on top of Docker, that's the only think you'll need!

👉 Please follow the

Docker official guides to install it on Linux, Windows, and macOS

Why Docker?
Docker makes it easy to ship all-in-one solution with the runtime and dependencies. You don't have to worry about language-specific libraries or chrome installation.

Also, Docker makes installation and update processes so simple, just one command!

Step 1. Run WAHA

After you installed Docker - you're ready to run WAHA!



docker run -it --rm -p 3000:3000/tcp --name waha devlikeapro/waha

# It prints logs and the last line must be
# WhatsApp API is running on: http://[::1]:3000

It may take time to download the image, depending on your internet speed.

If you're using ARM processor (like Apple M1/M2) run the following commands instead:



# Download the image
docker pull devlikeapro/waha:arm
# Rename it, so you can use devlikeapro/waha image in other place
docker tag devlikeapro/waha:arm devlikeapro/waha
# Run the same command!
docker run -it --rm -p 3000:3000/tcp --name waha devlikeapro/waha

# It prints logs and the last line must be
# WhatsApp API is running on: http://[::1]:3000

👉 Now, open Dashboard at

http://localhost:3000/dashboard

You'll see WAHA Dashboard:

Step 2. Run session

Now you start default session (current status should be STOPPED).

You can leave all configuration parameters by default:

Step 3. Scan QR

Wait until the session status is SCAN_QR and click on "camera" icon:

👉 If instead of QR you see Click to reload QR - stop the session and start it again.

You'll see QR code from WhatsApp Web app, now get your phone with installed WhatsApp application and scan the QR:

The session status will move to WORKING status:

Step 4. Get Channel ID

One step before you can send a message to you Channel - you need to get Channel ID in format 123123123@newsletter
to know where to send a message.

You can just execute the following curl command:



curl -X 'GET' \
  'http://localhost:3000/api/default/channels?role=OWNER' \
  -H 'accept: application/json'

In the response you'll see all channels, choose one and copy id:



[
  {
    "id": "111111111111111111@newsletter", // <========= copy that
    "name": "Channel Name",
    "role": "OWNER",
    ...
  }
]

As alternative to curl, you can use WAHA Swagger for that, open it at

http://localhost:3000/#/channels
, scroll down to Channels section.

Find GET /api/{session}/channels endpoint and expand it
Click Try it out
Choose role=OWNER if you have your own channels or role=ADMIN if you're admin in the channel (you can not send messages if you're SUBSCRIBER in the channel)
Click Execute

Step 5. Send a message to WhatsApp Channel

Now we're ready to send first messages to WhatsApp Channel via API!

Replace 123123@newsletter with your newsletter id, like 29847512@newsletter in the bellow command:



curl -X 'POST' \
  'http://localhost:3000/api/sendText' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "chatId": "123123123123@newsletter",
  "text": "Hi there!",
  "session": "default"
}'

As alternative to curl, you can use WAHA Swagger for that, open it at

http://localhost:3000/#/chatting
, scroll down to chatting section.

Find POST /api/sendText endpoint and expand it
Click Try it out
Replace 123123@newsletter with your newsletter id, like 29847512@newsletter in the bellow command
Click Execute

What is next?

🎉 You've sent the first message to WhatsApp Channel using WhatsApp API! 🎉

https://waha.devlike.pro/whatsapp-channels/