Installation Guide

Before beginning the installation, make sure your environment meets System requirements.

Important Info From v2.4

Ensure that you are using php v8.2
Ensure that you have enabled imagick extension in your server (If not you might experience error 500).
Ensure that you are running either MYSQL > 5.7.7 or MariaDB > 10.2.2 (Alternatively, you may enable the innodb_large_prefix option for your database)

1. Obtain the package

After purchasing Swiftchats, you will get a zipped folder. After unzipping the folder, you will get three folders, the source code folder, update folder and the documentation folder.

Documentation
Source-code
Update

2. Database setup (MySQL)

Create a new MySQL database.
Create a new MySQL username and password.
Assign full privileges to your database username.

On a VPS, create the database with the MySQL or MariaDB client (mysql / mariadb), or run the equivalent SQL from an admin tool. Grant the application user full privileges on that database and allow connections from the host where PHP runs (often localhost).

3. Uploading code

Before starting to upload the files, please make sure your file explorer has the option to view hidden files turned on. On some operating systems, the dotfiles are hidden by default.

Ubuntu and similar VPS or dedicated servers: The most reliable approach is to push your project to a private GitHub repository (or another Git host), then clone or pull the code on the server with Git. That gives you version history, simpler updates, and avoids incomplete SFTP uploads or missing application files. Create environment files such as .env directly on the server (never commit secrets to Git).

Git (recommended on Linux servers): Create a private repository, add the Swiftchats source code (including dotfiles your workflow requires), deploy keys or SSH access on the server, then git clone into your web root or project directory (for example /var/www/your-site).
Manual upload (alternative): Copy the source-code folder to your project directory on the server (for example under /var/www/) using SFTP or rsync. Ensure hidden files are included.
Ensure you have already created the MySQL database and DB user on the server and assigned that user to the database (see section 2).

4. Installer setup

Once you have configured the steps above, go to your domain or subdomain which should redirect you to the installation page. Go through each installation step and grant folder permissions where necessary.

5. Evolution API on Ubuntu (Docker)

The WhatsApp QR connect add-on uses Evolution API as the WhatsApp Web gateway. On Ubuntu, the recommended approach is to run Evolution API with Docker and Docker Compose alongside your Swiftchats stack.

WhatsApp QR connect add-on required. The Swiftchats WhatsApp QR connect integration (settings, connectivity, and related features) is only available if you have purchased the WhatsApp QR connect add-on for your Swiftchats license. Complete the add-on purchase before relying on this stack in production.

Install Docker Engine and Compose

On Ubuntu 20.04 or 22.04 LTS:

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker "$USER"

Log out and back in (or open a new SSH session) so the docker group applies. Verify:

docker --version
docker compose version

Create the Evolution API project directory

Create the project under /opt/evolution-api (default path used by Evolution API):

sudo mkdir -p /opt/evolution-api
sudo chown "$USER":"$USER" /opt/evolution-api
cd /opt/evolution-api

The next steps assume your shell is inside /opt/evolution-api.

Configure environment variables

Create or edit .env in /opt/evolution-api:

nano .env

Paste these variables into your .env file:

DATABASE_ENABLED=true
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://postgres:postgres@postgres:5432/evolution?schema=public
DATABASE_CONNECTION_CLIENT_NAME=evolution_exchange

AUTHENTICATION_API_KEY=your-authentication-api-key
WA_BUSINESS_TOKEN_WEBHOOK=your-whatsapp-business-token-webhook

DATABASE_SAVE_DATA_INSTANCE=true
DATABASE_SAVE_DATA_NEW_MESSAGE=true
DATABASE_SAVE_MESSAGE_UPDATE=true
DATABASE_SAVE_DATA_CONTACTS=true
DATABASE_SAVE_DATA_CHATS=true
DATABASE_SAVE_DATA_LABELS=true
DATABASE_SAVE_DATA_HISTORIC=true
CONFIG_SESSION_PHONE_VERSION=2.3000.1029992881

CACHE_REDIS_ENABLED=true
DATABASE_PROVIDER=postgresql
CACHE_REDIS_URI=redis://redis:6379/6
CACHE_REDIS_PREFIX_KEY=evolution
CACHE_REDIS_SAVE_INSTANCES=false
CACHE_LOCAL_ENABLED=false

Replace your-authentication-api-key and your-whatsapp-business-token-webhook with real secrets (for example strong random values from generate-random.org API keys).

Save AUTHENTICATION_API_KEY somewhere secure after you set it. Later, set EVOLUTION_API_KEY in the Swiftchats .env to the same value (see Connect Swiftchats to the WhatsApp gateway at the end of this section).

Create YAML file for Docker

In /opt/evolution-api (same directory as .env), create docker-compose.yaml:

nano docker-compose.yaml

Paste this into the file:

services:

  postgres:
    container_name: evolution_postgres
    image: postgres:15
    restart: always
    networks:
      - evolution-net
    command: ["postgres", "-c", "max_connections=1000"]
    ports:
      - "127.0.0.1:5432:5432"
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_DB=evolution
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:latest
    container_name: evolution_redis
    restart: always
    networks:
      - evolution-net
    command: redis-server --port 6379 --appendonly yes
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - evolution_redis:/data

  evolution-api:
    container_name: evolution_api
    image: evoapicloud/evolution-api:latest
    restart: always
    depends_on:
      - redis
      - postgres
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - evolution_instances:/evolution/instances
    networks:
      - evolution-net
    env_file:
      - .env

volumes:
  postgres_data:
  evolution_redis:
  evolution_instances:

networks:
  evolution-net:
    driver: bridge

Save and exit the editor.

Start the services

From /opt/evolution-api, launch Evolution API with Docker Compose:

docker compose up -d

This starts:

Evolution API (port 8080)
PostgreSQL (port 5432 on localhost)
Redis (port 6379 on localhost)

Verify the services are running:

docker compose ps

Reverse proxy (Nginx)

Create a reverse proxy to expose the API safely.

sudo nano /etc/nginx/sites-available/evolution

Paste this:

server {
    server_name evolution.yourdomain.com; #Replace with your subdomain
    client_max_body_size 10M;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;

        # Headers for API & Webhooks
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site and reload Nginx:

sudo ln -s /etc/nginx/sites-available/evolution /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo certbot --nginx -d evolution.yourdomain.com

Replace evolution.yourdomain.com with the same hostname you set in Nginx server_name. For more options or troubleshooting, see How to install in Nginx.

Connect Swiftchats to the WhatsApp gateway

In the Swiftchats .env file on the server, set:

EVOLUTION_BASE_URL — Same base URL as SERVER_URL in the Evolution API gateway (for example https://evolution.yourdomain.com).
EVOLUTION_API_KEY — Must match AUTHENTICATION_API_KEY from the gateway’s .env (use the value you saved when configuring Evolution API).

Clear config cache after editing:

php artisan config:clear

For the latest Evolution API options, environment variables, and troubleshooting, see the Evolution API installation documentation.

6. Laravel jobs and queues

To ensure successful delivery of WhatsApp campaigns, it’s essential to set up a queue system that runs at scheduled intervals to dispatch campaigns efficiently. On a VPS, use Supervisor to run Laravel queue workers and a cron entry for Laravel’s scheduler (see step 6 below).

Supervisor requires shell access (SSH) and permission to install system packages (for example sudo on Ubuntu).

If you decide to use Laravel queues, go to your .env file and change the following:

QUEUE_CONNECTION=database
QUEUE_MEMORY=128
QUEUE_TIMEOUT=300
QUEUE_DRIVER=database

Install Supervisor

On Ubuntu or Debian:

sudo apt update && sudo apt install supervisor -y

After installation, start Supervisor and enable it to run on boot:

sudo systemctl enable --now supervisor

Create a Supervisor configuration file for Laravel queues

Create a new configuration file inside /etc/supervisor/conf.d/:

sudo nano /etc/supervisor/conf.d/laravel-queue.conf

Add the following content:

[program:laravel-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /path-to-your-project/artisan queue:work --queue=default,campaign-logs,campaign-messages --tries=3 --timeout=3600
autorestart=true
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/laravel-queue.log

Replace /path-to-your-project/ with your actual Laravel project path.

Apply Supervisor changes

After creating the configuration file, run the following commands to update and start Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-queue:*

To check if Supervisor is running correctly, use:

sudo supervisorctl status

Monitoring and logs

You can check the logs if anything goes wrong:

tail -f /var/log/laravel-queue.log

If the queue worker stops unexpectedly, restart Supervisor:

sudo supervisorctl restart laravel-queue

Ensure Supervisor starts on boot

To prevent queue workers from stopping after a reboot, enable Supervisor:

sudo systemctl enable supervisor

Add a cron job for the Laravel scheduler

Edit the crontab:

crontab -e

Add this line (runs Laravel’s scheduler every minute):

* * * * * cd /path-to-your-project && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

Replace /path-to-your-project/ with your actual Laravel project path.

7. Trouble-shooting your installation

If you are facing issues with the installer, try the following: Grant access to your .env file — from your project directory, run:

chown -R www-data:www-data .env

Clear the installer lock — open the storage folder and delete the installed file. Retry the installation in your browser.

Get Started

Admin Panel

Customer Panel

Important Info From v2.4

1. Obtain the package

2. Database setup (MySQL)

3. Uploading code

4. Installer setup

5. Evolution API on Ubuntu (Docker)

6. Laravel jobs and queues

7. Trouble-shooting your installation

​Important Info From v2.4

​1. Obtain the package

​2. Database setup (MySQL)

​3. Uploading code

​4. Installer setup

​5. Evolution API on Ubuntu (Docker)

​6. Laravel jobs and queues

​7. Trouble-shooting your installation

Important Info From v2.4

1. Obtain the package

2. Database setup (MySQL)

3. Uploading code

4. Installer setup

5. Evolution API on Ubuntu (Docker)

6. Laravel jobs and queues

7. Trouble-shooting your installation