🗄️ Storages
Overview
There are several storages that are used by the WAHA, below you can find the list of them and the way to configure them.
- 🖥️ Session Storage - used to store the session data, such as authentication information, configuration, and other data that is required to keep the session alive and connected to WhatsApp.
- 🖼️ Media Storage - used to store the media files, such as images, videos, and other files that are received from the WhatsApp instance.
Storage Type | 🖥️ Session Storage | 🖼️ Media Storage |
---|---|---|
Local | ✔️ | ✔️ |
MongoDB | ✔️ | #508 |
S3¹ | ➖ | ✔️¹ |
PostgresSQL | #450 | ➖ |
- Any S3 Compatible storage can be used, such as AWS S3, MinIO, DigitalOcean Spaces, etc. For in-house solutions, you can use MinIO.
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.
👉 Storages are available in WAHA Plus only.
Sessions
The 🖥️ Session storage is used to store the session data, such as authentication information, configuration, and other data that is required to keep the session alive and connected to WhatsApp.
If you want to save your session and do not scan QR code everytime when you launch WAHA - you MUST connect the session storage to the container.
For the session storage, you can use the following options:
- Local - the default option, stores the session data in the local storage using files.
- MongoDB - stores the session data in the MongoDB database.
Sessions - Local
By default, the WAHA uses the local storage (files) to store the session data.
In order to use the local storage and save the session data between the container restarts,
you need to mount the volume to the /app/.sessions
directory using the -v
option in docker run
command:
-v /path/to/on/host/.sessions:/app/.sessions
The full command to run the WAHA with the local storage and save the session data
in the current directory and .sessions
directory:
docker run -v `pwd`/.sessions:/app/.sessions -p 3000:3000/tcp devlikeapro/waha-plus
This is the only action you need to do to use the local storage - all session data will be available between the container restarts.
How it works
In the host machine, the session data will be stored in the current directory in the .sessions
directory.
Under the hood, the WAHA stores the session data in the following directory structure:
.sessions/{engine}/{sessionName}/...
when you log out the session using POST /api/sessions/{session}/logout or delete the session using DELETE /api/sessions/{session} it removes the directory with the session data.
Health Check
The WAHA Plus provides the health check endpoint that checks the local storage.
Sessions - MongoDB
If you want to use the MongoDB to store the session data, you need to:
- Start the MongoDB server (using docker or any other way). You can either start your own MongoDB server or use the one of cloud providers, like MongoDB Atlas.
- Set
WHATSAPP_SESSIONS_MONGO_URL=mongodb://user:password@host:port/
environment variable to connect to the MongoDB server.
We recommend using your own MongoDB server as close as possible to WAHA server for the best performance and security reasons.
Example
First, you need to start MongoDB server:
docker run -d -p 27017:27017 --name mongodb -v mongo-data:/data/db mongo
Then, you need to run the WAHA with the WHATSAPP_SESSIONS_MONGO_URL
environment variable (please note using --network host
option as well)
docker run -e WHATSAPP_SESSIONS_MONGO_URL=mongodb://localhost:27017/ --network host devlikeapro/waha-plus
This is the only action you need to do to use the MongoDB storage - all session authentication data will be stored in the MongoDB database.
How it works
When you start a session, it stores the session data in the MongoDB database in two databases:
waha_{engine}
- it saves the session configuration insessions
collection withname: {sessionName}
field.waha_{engine}_{sessionName}
- it saves the WhatsApp authentication data and other session data. Each engine saves different data in this database.
when you log out the session using POST /api/sessions/{session}/logout or delete the session using DELETE /api/sessions/{session} it removes the session data from both databases.
For dealing and troubleshooting with the MongoDB, we recommend using MongoDB Compass.
MongoDB Atlas
If you use the MongoDB Atlas you must grant
Atlas Admin
role in Security => Database Access before you connect to the database.
For production please consider running the MongoDB server close to the WAHA server for the best performance and security reasons.
Health Check
The WAHA Plus provides the health check endpoint that checks the MongoDB connection.
Media
When your WhatsApp instance receives media files, it stores them in the media storage.
You can use the following options to store the media files:
- Local - the default option, stores the media files in the local storage using files.
- S3 - stores the media files in the S3 storage.
Read more about available configuration options ->.
The following table shows the compatibility of the storage with the engines:
WEBJS | NOWEB | |
---|---|---|
Local | ✔️ | ✔️ |
S3 | 🕒 | 🕒 |
Media - Local
By default, the WAHA uses the local file storage to store the media files and those files has a short lifetime (180 seconds).
So it’s your app responsibility to download and store them in a safe persistent place during this time.
Save media files between the container restarts
If you want to use the local storage and save the media files between the container restarts for a long time - you need to:
- Specify a dedicated folder to store the media files using
WHATSAPP_FILES_FOLDER=/app/.media
environment variable - Disable automatic media files cleanup using
WHATSAPP_FILES_LIFETIME=0
environment variable - Connect the volume to the specified folder using the
-v /path/to/files/on/host:/app/.media
option indocker run
command to the folder specified inWHATSAPP_FILES_FOLDER
environment variable.
Read more about available configuration options ->.
Here’s all the steps in one command:
docker run -v /path/to/on/host/.media:/app/.media -e WHATSAPP_FILES_FOLDER=/app/.media -e WHATSAPP_FILES_LIFETIME=0 -p 3000:3000/tcp devlikeapro/waha-plus
Health Check
The WAHA Plus provides the health check endpoint that checks the local storage.
Media - S3
You can use the S3 storage to store the media files.
Any S3 Compatible storage can be used, such as AWS S3, MinIO, DigitalOcean Spaces, etc. For in-house solutions, you can use MinIO.
Configuration
WAHA_MEDIA_STORAGE=S3
- enable the S3 storageWAHA_S3_REGION=eu-west-1
- the region of the S3 bucketWAHA_S3_BUCKET=waha
- the name of the S3 bucketWAHA_S3_ACCESS_KEY_ID=minioadmin
- the access key of the S3 bucketWAHA_S3_SECRET_ACCESS_KEY=minioadmin
- the secret access key of the S3 bucketWAHA_S3_ENDPOINT=http://127.0.0.1:9000
- the endpoint of the S3 bucket (not required for AWS S3)WAHA_S3_FORCE_PATH_STYLE=True
- force path style for the S3 bucket (not required for AWS S3)WAHA_S3_PROXY_FILES
- proxy media files through WAHA (False
by default)WAHA_S3_PROXY_FILES=False
- generate pre-signed URLs for media files and send them to the client inmedia.url
WAHA_S3_PROXY_FILES=True
- WAHA will proxy media files through itself inmedia.url
After you enabled S3 here’s example for message webhook payload:
{
"event": "message",
"session": "default",
"engine": "WEBJS",
"payload": {
"id": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"hasMedia": true,
"media": {
"url": "http://localhost:3000/api/files/true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.jpg",
"mimetype": "image/jpeg",
"filename": null,
"s3": {
"Bucket": "bucket-name",
"Key": "/default/true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.jpg"
},
"error": null // if there was an error during file download
}
...
}
}
in addition to media.*
field it will have media.s3.*
field with the S3 bucket information.
S3 Metadata
Each file saved in S3 has additional metadata:
X-Amz-Meta-Waha-Session=default
- the session nameX-Amz-Meta-Waha-Message-Id=true_111...
- the message IDX-Amz-Meta-Waha-Media-File-Name=media.jpg
- the media file name (if available)