Installation FAQs

Q: What are the minimum requirements?

A: WaDesk runs on a standard Laravel 12 stack:

• PHP 8.2 or higher with the usual extensions (BCMath, Ctype, cURL, Fileinfo, JSON, Mbstring, OpenSSL, PDO, Tokenizer, XML, Zip)
• MySQL 8.0+ (MariaDB 10.6+ is also supported)
• Apache or Nginx with mod_rewrite, or LiteSpeed
• A queue worker for background jobs (campaigns, webhooks, scheduled sends)
• Node.js 18+ — required; the Node bridge carries the send path and the scheduler for every engine (see below)

Q: Can I run WaDesk on shared hosting, or do I need a VPS?

A: The Node bridge must stay running for every engine — it dispatches WhatsApp Cloud API and Twilio sends and runs the scheduler for broadcasts, campaigns, and scheduled messages — so the real question is whether your host can keep a long-lived Node process alive.

• Cloud API or Twilio: Shared hosting can work only if it can run the persistent Node bridge — many cPanel / Plesk hosts provide a “Setup Node.js App” tool that does exactly this. Because the bridge dispatches these sends and runs the scheduler, if your host cannot keep a Node process running, sends and scheduled / bulk jobs stop — use a VPS instead.
• Unofficial API: A VPS or dedicated server with SSH is strongly recommended. The Node.js bridge is a persistent process that must stay running to hold the WhatsApp Web session alive. Most shared hosts will not let you run a long-lived Node process, so the QR connection will keep dropping.

Recommendation: For any production or multi-tenant SaaS deployment, use a VPS. It gives you the control over Node, queue workers, and process management (for example with PM2 or Supervisor) that WaDesk needs to run reliably.

Q: How is WaDesk installed?

A: WaDesk ships with a guided web installer. You upload the files, create an empty database, point your domain at the public folder, and visit your domain in a browser. The installer runs database migrations, seeds default data, and creates your admin account automatically. Full steps are in the Web Installer Guide.

Q: Why does the Unofficial API need a separate Node.js service?

A: The Unofficial API connects to WhatsApp using a Node.js library that speaks WhatsApp Web's protocol. Laravel (PHP) cannot hold that live socket connection itself, so WaDesk bundles a small Node.js bridge that maintains the WhatsApp session, renders the pairing QR code, sends outgoing messages, and forwards inbound messages back to the Laravel app via webhooks.

Q: Do I need Node.js even if I only use the official engines?

A: Yes. The Node bridge is part of the send path for the official engines too — WhatsApp Cloud API (WABA) sends are dispatched through the bridge (it holds the per-phone WABA credentials and makes the Graph API call), and the bridge runs the scheduler plus the bulk-send pipeline (broadcasts, campaigns, scheduled messages, flows) for every engine, including Twilio. Only a single, one-off direct Twilio API send bypasses it. Treat the Node bridge as required for any production install.

Q: How do I keep the bridge running permanently?

A: Run the bridge as a managed process so it restarts automatically after a crash or server reboot. On a VPS, PM2 or a systemd service is the typical choice. If the Node process stops, sending stops: Unofficial API devices go offline, WABA dispatch fails, and the scheduler + bulk pipeline (broadcasts, campaigns, scheduled, flows) pause until it returns. Unofficial API sessions re-establish automatically once the bridge is back.

Q: Do I need SSL (HTTPS)?

A: Yes — HTTPS is effectively mandatory. Both the Meta Cloud API and Twilio require a publicly reachable HTTPS webhook URL to deliver inbound messages and status callbacks; they will not POST to plain HTTP. A free Let's Encrypt certificate is sufficient. Set APP_URL to your https:// domain and clear the config cache after changing it.

Q: Can I remove "public" from the URL?

A: Yes. On the first run a fresh install loads at https://yourdomain.com/public (or https://app.yourdomain.com/public on a subdomain) — that is normal. The standard way to remove /public is to create a .htaccess file in your project root folder (the folder above public) and add:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

This rewrites every request into public, so the site opens at https://yourdomain.com without /public. It needs mod_rewrite enabled, and afterwards your APP_URL should be the clean address without /public. On a VPS you can instead point the domain's document root straight at the public folder. For Cloudflare users, set the SSL mode to Full or Full (Strict) to avoid mixed-content and redirect-loop errors. Full setup context is in the Web Installer Guide.

Q: My inbound messages or ad leads are not arriving. Why?

A: Almost always a webhook reachability problem. Confirm that your domain is publicly accessible over HTTPS, that the webhook URL and verify token are saved correctly in Meta/Twilio, and that no firewall or "under construction" page is blocking the callback route. Inbound delivery on the official engines depends entirely on Meta or Twilio being able to reach your server.

Q: How do I update to a new version?

A: Download the latest package from your CodeCanyon downloads, then replace the application files while preserving your .env file, storage directory, and any uploaded media. Run database migrations to apply schema changes and clear the caches afterward. Always take a full backup of your files and database before updating.

php artisan migrate --force
php artisan config:clear
php artisan view:clear

Q: Do updates cost extra?

A: No. Updates are free for the lifetime of the item. Your CodeCanyon support window covers assistance, but new versions themselves are always available to download at no additional cost.

Q: Does WaDesk back itself up?

A: Backups are your responsibility as the server operator. WaDesk does not provide automated off-site backups. Schedule regular backups of your MySQL database and the storage directory, and keep a recent copy before any update or server change. See the Disclaimer for the full data-responsibility statement.

Q: How do I hide or deny access to the .env file?

A: When your document root points at the public/ folder, the .env file already sits outside the web root and cannot be reached from a browser. As an extra safeguard — especially if the whole project lives in your web root — create a .htaccess file in your project root folder and add:

<Files .env>
    Require all denied
</Files>

This blocks any direct web request to .env. On older Apache (2.2) use Order allow,deny then Deny from all inside the same block. Never expose .env — it holds your app key, database credentials, and API/payment keys.

Q: How do I turn debug mode on or off?

A: Debug mode shows detailed error pages, which helps you track down a problem on your site. Do not leave it on for long on a live site — it can reveal sensitive details. To change it:

1. Log in to your FTP account (or the hosting File Manager).
2. Open and edit the .env file.
3. Find APP_DEBUG and set the value:

APP_DEBUG=false   # OFF - recommended on live sites
APP_DEBUG=true    # ON  - shows detailed errors

Save and upload the file, then clear the config cache so the change is read:

php artisan config:clear

false means debug mode is OFF; true means it is ON.

Q: "No application encryption key has been specified"

A: Laravel cannot read a valid APP_KEY from your .env. Check, in order:

• Confirm the .env file exists — it is a hidden dotfile, so it may only look missing (see the next question).
• Confirm APP_KEY=base64:... is present and not blank. The installer sets it for you — do not change or remove it, as it is used to decrypt stored data.
• If the key is present but the error persists, clear the cached config: php artisan config:clear.

Q: My .env file is missing

A: Most of the time the .env file is not missing — it is just hidden, because filenames starting with a dot are hidden by default. Show hidden files for your environment below:

cd /var/www/wadesk
ls -la
nano .env

Q: 419 "Page Expired" error

A: A 419 means the session/CSRF token could not be validated — almost always because sessions are not being saved on your host, not a script bug. Fix it by:

• Making sure storage/ and storage/framework/sessions/ are writable (see File Permissions).
• Confirming you are on PHP 8.2+ and using the recommended PHP settings below.
• Increasing the session lifetime — set SESSION_LIFETIME higher in .env (or config/session.php) so sessions do not expire too quickly.
• Clearing caches after any change: php artisan config:clear.

Recommended php.ini settings:

memory_limit = 256M
max_execution_time = 300
max_input_time = 300
upload_max_filesize = 64M
post_max_size = 64M

See the Troubleshooting page's 419 section for more.

Q: "Could not find driver" (SQL error)

A: The database driver is not configured or enabled. Work through:

• Open .env and confirm DB_CONNECTION=mysql.
• Ensure the pdo_mysql PHP extension is installed and enabled.
• Confirm the connection details are correct — DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD — and that the database server is running.
• Confirm you are on a supported PHP version (8.2+) and the DB user can access the database.
• Restart your server / PHP-FPM after changes.

Q: "Class 'ZipArchive' not found"

A: The PHP zip extension is not enabled on your server. Enable it (in cPanel/Plesk under "Select PHP Version → Extensions", or in your php.ini) and the error clears. This is a server setting, not a script issue — if you are unsure how to enable it, ask your hosting provider.

Q: "curl_init()" error

A: The PHP curl extension is not enabled. Enable it the same way (PHP extension manager or php.ini) and the error clears. Again a server setting, not a script issue — your host can enable it for you if needed.

Q: MySQL / the database is not creating tables

A: The database user does not have enough rights. The user must have ALL PRIVILEGES on the database so the installer can run CREATE TABLE. Grant full privileges (see Creating the Database) and re-run. If you are unsure how, ask your hosting provider.

Q: 404 "Not Found" error

A: A 404 means the requested file could not be found — a server/setup issue, not a script bug. Check:

• All files extracted and uploaded properly (nothing truncated or half-uploaded).
• The document root points at the public/ folder, or the root .htaccess rewrite is in place (see Remove public From the URL).
• Folder permissions are correct (see File Permissions).
• The URL is correct, port 80/443 is open, and the server is up.

If it persists, your host can check the server logs for the exact cause.

Q: 403 "Forbidden" error

A: A 403 means access was denied. There are two cases:

• Inside the app: the logged-in user's role does not have permission for that page. Edit the user's role to grant the needed permission, then save/update.
• At the server level (before the app loads): usually a missing index.php, wrong folder permissions, or a directory-listing block. Confirm the files uploaded correctly and permissions are right.

Q: "Payload" error

A: A payload error usually means the data sent to the server in a request was missing, malformed, or too large. Check that required fields are filled and valid, and that your PHP post_max_size and upload_max_filesize are large enough for what you are submitting (see the 419 settings above). An expired session (419) can also surface as a payload issue — clear caches and retry.

Q: My .env changes are not taking effect

A: Laravel caches its configuration, so edits to .env may not show until the cache is rebuilt. Run:

php artisan config:clear
php artisan cache:clear
php artisan config:cache

Then restart your server. On shared hosting, also check for a server-side cache (Cloudflare, Varnish) that could be holding old responses.