Update Process

Overview

This guide explains how to safely update WaDesk to a newer version. All PHP dependencies and frontend assets are pre-built in the update package, so a standard update is: back up → upload new files → run migrations → clear cache and rebuild assets → restart the Node bridge.

Always review the Change Log first to understand what has changed and whether a release needs new environment variables or configuration.

Two ways to update. From v1.1.0 onward, WaDesk includes a one-click In-App Updater in the admin panel that automates everything below. The manual file-replacement steps on this page are still fully supported — and are the only way to move from v1.0.0 to v1.1.0, because 1.0.0 shipped before the updater existed. See Choosing Your Update Method first.

Choosing Your Update Method

Which path you take depends on the version you are currently running.

Updating from v1.0.0 → v1.1.0 (Manual)

Version 1.0.0 has no in-app updater, so this one upgrade must be done manually by replacing files on your server. It is a one-time manual step; afterwards you will have the updater. In short:

• Back up your database and files (Step 1).
• Replace the application code — app/, bootstrap/ (except bootstrap/cache/), config/, database/, lang/, resources/, routes/, public/build/, the node/ bridge source, and root files like composer.json, composer.lock, package.json, artisan, and config/version.php (Step 2).
• Skip / never overwrite — .env, storage/ (holds the Node bridge's WhatsApp sessions for every connected number), your uploaded files in public/ (media, logos, branding), and the installed vendor/ and node/node_modules/ dependency folders (What NOT to Overwrite).
• Then run migrations → clear caches → restart the Node bridge & queue (Steps 3–5).

The golden rule for the manual upgrade: replace code folders, never replace data/config (.env, storage/, public/ uploads). When in doubt, extract the package to a separate folder and copy only the code across.

Updating from v1.1.0 and later (In-App Updater)

Once you are on v1.1.0+, every future update can be done from inside the admin panel at Admin → Update — no FTP/SSH, no manual file juggling. The updater runs the same safe sequence this page describes, automatically, and only the Super Admin can run it. How it works:

1. Verify license — enter your CodeCanyon purchase code; the updater validates it with Envato before allowing an update.
2. Automatic backup — it snapshots your current files and database first, so you always have a restore point.
3. Upload the package — from the package's update folder, upload the version update ZIP (for v1.2 that is update_1.2.zip) exactly as it is — do not unzip it, and do not upload the full installable package. The updater reads its config/version.php and refuses anything that is not newer than your current version.
4. Apply files — it extracts and replaces the application code while preserving your .env, storage/, and uploaded files automatically — the things you would manually exclude are protected for you.
5. Run migrations — new database migrations are applied.
6. Finalize — caches are cleared and a health check confirms the app still boots. You then restart the Node bridge (see Step 5) so Unofficial API numbers pick up the new bridge code.

One-click rollback. Every run keeps a backup. If a release misbehaves, the Rollback button on the same screen restores the previous files and database from any saved backup — no command line needed.

Still take your own backup before a major update, and the bridge restart in Step 5 is the one manual touch the updater cannot do for you (it runs as a separate process).

Updating from v1.2 → v1.3

Updates are sequential — v1.2 is compulsory before v1.3. You cannot jump straight to v1.3 from an older release. You must already be running v1.2 first, then apply v1.3 on top. If you are on v1.0.0 or v1.1.0, update one step at a time — e.g. 1.0.0 → 1.1.0 → 1.2 → 1.3 — running migrations and clearing cache after each step. The updater refuses any package that is not newer than your installed version, so it will block an out-of-order upload.

Once you are on v1.2, apply v1.3 with the In-App Updater exactly as described above:

1. Raise your upload limit to the maximum first (see the red box at the top of this page) — the v1.3 ZIP is larger than the default PHP limit and will be rejected otherwise.
2. Back up your database and files yourself (Step 1).
3. Go to Admin → Update, verify your CodeCanyon purchase code, then upload update_1.3.zip from the package’s update folder — exactly as it is, do not unzip it.
4. Let it apply files and run migrations, then finalize.
5. Restart the Node bridge (Step 5) — on a VPS pm2 restart all; on cPanel/Hostinger use the Node app manager. This is required for v1.3 — the scheduled-message and connection fixes live in the Node bridge and only take effect after a restart.

Node token must match. v1.3 hardens the Laravel↔Node connection. Make sure the same NODE_WEBHOOK_TOKEN is set in both Laravel (Admin → settings, or .env) and the Node bridge’s node/.env, then run php artisan config:clear and restart Node. If they don’t match, device pairing, sending, and scheduled messages return “unauthorized”. (Alternatively, point the Node server URL at http://127.0.0.1:<port> when Laravel and Node share the same server — loopback is trusted automatically.)

Updating from v1.3 → v1.4

Updates are sequential — v1.3 is compulsory before v1.4. You cannot jump straight to v1.4 from an older release. You must already be running v1.3 first, then apply v1.4 on top. If you are further back, update one step at a time — e.g. 1.1.0 → 1.2 → 1.3 → 1.4 — running migrations and clearing cache after each step. The updater refuses any package that is not newer than your installed version, so it will block an out-of-order upload.

Once you are on v1.3, apply v1.4 with the In-App Updater exactly as described above:

1. Raise your upload limit to the maximum first (see the red box at the top of this page) — the v1.4 ZIP is larger than the default PHP limit and will be rejected otherwise.
2. Back up your database and files yourself (Step 1).
3. Go to Admin → Update, verify your CodeCanyon purchase code, then upload update_1.4.zip from the package’s update folder — exactly as it is, do not unzip it.
4. Let it apply files and run migrations, then finalize.
5. Clear the view cache — run php artisan view:clear (Step 4). This is required for v1.4: the pricing page is a compiled Blade view, so without this the old compiled copy keeps serving the previous yearly-price calculation even though the new files are in place.
6. Restart the Node bridge (Step 5) — on a VPS pm2 restart all; on cPanel/Hostinger use the Node app manager.

Check your yearly plans after updating. v1.4 fixes how a plan with a yearly billing period is priced and charged. If you sell an annual plan, open Admin → Packages and confirm the billing period and amount read as you intend — a plan set to 1 year is now charged its full yearly amount in a single payment and is treated as yearly even when the pricing-page toggle is not carried in the URL. Also check Admin → Settings that the yearly toggle is enabled if you offer monthly→annual conversion; with it switched off, the toggle is hidden and monthly plans are billed monthly.

On cPanel, redo the Node entry-point rename. An update ships a fresh index.js, which overwrites the file you renamed during setup. After finalizing, go back into the node folder, rename index.js to index-old.js and index-cpanel.js to index.js, then restart the Node app — otherwise the bridge will not come back up. Full steps: Running the Node Bridge on cPanel.

Updating from v1.6 → v1.7

Updates are sequential — v1.6 is compulsory before v1.7. You cannot jump straight to v1.7 from an older release. You must already be running v1.6 first, then apply v1.7 on top. If you are further back, update one step at a time — e.g. 1.4 → 1.5 → 1.6 → 1.7 — running migrations and clearing cache after each step. The updater refuses any package that is not newer than your installed version, so it will block an out-of-order upload.

v1.7 is a channel release: it adds Email (through a connected MailTrixy install), plus LINE, WeChat and Viber. Once you are on v1.6, apply v1.7 with the In-App Updater exactly as described above:

1. Raise your upload limit to the maximum first (see the red box at the top of this page).
2. Back up your database and files yourself (Step 1).
3. Go to Admin → Update, verify your CodeCanyon purchase code, then upload update_1.7.zip from the package’s update folder — exactly as it is, do not unzip it.
4. Let it apply files and run migrations, then finalize.
5. Clear the view cache — run php artisan view:clear (Step 4). Required for v1.7: the new channel screens are compiled Blade views, so without this the old compiled copies keep rendering.
6. Restart the Node bridge (Step 5) — on a VPS pm2 restart all; on cPanel/Hostinger use the Node app manager. v1.7 updates the Node runtime that runs the new channels’ flows.

Email is OFF on every plan by default — tick it or the channel stays invisible. The v1.7 migration adds the Email plan flag defaulting to off, so even a correctly connected MailTrixy bridge shows nothing: no mailbox picker, no email sender, no Email option anywhere. After finalizing, go to Admin → Packages, edit each plan that should include email, and tick Email (set a monthly limit if you want to cap usage). This is the single most common “the update didn’t work” report.

The new channels need their credentials before a workspace can connect them. Each is off until configured in Admin → Settings: LINE needs a Channel access token and Channel secret, WeChat needs AppID, AppSecret, Token and EncodingAESKey (and a Verified Service Account), Viber needs just its bot authentication token, and Email needs a reachable MailTrixy install plus a shared secret entered on both sides. See each channel’s guide under Channels for exactly what to set. Existing workspaces keep working unchanged — every new feature is opt-in and plan-gated.

On cPanel, redo the Node entry-point rename. As with every update, v1.7 ships a fresh index.js that overwrites your renamed file. After finalizing, rename index.js to index-old.js and index-cpanel.js to index.js in the node folder, then restart the Node app. Full steps: Running the Node Bridge on cPanel.

Updating from v1.5 → v1.6

Updates are sequential — v1.5 is compulsory before v1.6. You cannot jump straight to v1.6 from an older release. You must already be running v1.5 first, then apply v1.6 on top. If you are further back, update one step at a time — e.g. 1.3 → 1.4 → 1.5 → 1.6 — running migrations and clearing cache after each step. The updater refuses any package that is not newer than your installed version, so it will block an out-of-order upload.

v1.6 is a large, multi-channel release, so it ships a big batch of new files and database migrations. Once you are on v1.5, apply v1.6 with the In-App Updater exactly as described above:

1. Raise your upload limit to the maximum first (see the red box at the top of this page) — the v1.6 ZIP is larger than the default PHP limit and will be rejected otherwise.
2. Back up your database and files yourself (Step 1).
3. Go to Admin → Update, verify your CodeCanyon purchase code, then upload update_1.6.zip from the package’s update folder — exactly as it is, do not unzip it.
4. Let it apply files and run migrations (v1.6 adds several new tables — companies, payments, tasks, projects, quotes and the channel tables), then finalize.
5. Clear the view cache — run php artisan view:clear (Step 4). Required for v1.6: the new inbox, channel and CRM screens are compiled Blade views, so without this the old compiled copies keep rendering.
6. Restart the Node bridge (Step 5) — on a VPS pm2 restart all; on cPanel/Hostinger use the Node app manager. v1.6 updates the Node runtime that powers Instagram and cross-channel flows, so this step is required for those channels to work.

New channels need their credentials before a workspace can connect them. v1.6 adds Instagram, Facebook Messenger, Telegram, TikTok and SMS. Each is off until configured in Admin → Settings: Instagram/Facebook reuse (or extend) your existing Meta app, Telegram needs a bot token, SMS needs Twilio or MSG91 keys, and TikTok needs its app credentials. See each channel’s guide under Channels for exactly what to set. Existing WhatsApp workspaces keep working unchanged — every new feature is opt-in and plan-gated.

On cPanel, redo the Node entry-point rename. As with every update, v1.6 ships a fresh index.js that overwrites your renamed file. After finalizing, rename index.js to index-old.js and index-cpanel.js to index.js in the node folder, then restart the Node app. Full steps: Running the Node Bridge on cPanel.

WhatsApp Cloud API (WABA) Setup

The WABA / WhatsApp Cloud API engine is Meta’s official API — ideal for verified business sending, templates, and calling. To connect a number:

1. Create / open your WhatsApp Business Account in Meta Business Manager and add a phone number under WhatsApp → API Setup.
2. Collect four values: Phone Number ID, WABA ID, a permanent access token (via a System User), and an App Secret for webhook signature verification.
3. In WaDesk go to Devices → Add device → Meta (WABA) and paste those values. WaDesk stores the token encrypted at rest.
4. Set the webhook in your Meta app to WaDesk’s callback URL (shown on the connect screen) and Verify it. Subscribe to the messages field so inbound messages, statuses, and calls reach the Team Inbox.
5. Approve templates under Templates — outbound business‑initiated messages outside the 24‑hour window must use an approved template. WaDesk lints templates before submit to reduce rejections.

Coexistence: the same WABA number cannot run on the Unofficial API and Cloud API at the same time. If you migrate a number to WABA, disconnect it from the Unofficial engine first. WaDesk blocks connecting the same WABA in two workspaces (first‑connected wins).

Step 1: Back Up Your Database and Files

Never skip this step. Before touching anything, back up the two things that contain your data and configuration:

• Database: Export it via your hosting control panel (phpMyAdmin → Export) or over SSH:

  mysqldump -u your_db_user -p your_database > wadesk-backup.sql

• Files: Download or compress your whole WaDesk directory — or at minimum the items you must never lose: .env, the storage/ folder, and any user uploads in public/.

Keep these backups until you have confirmed the update works. If anything goes wrong, they are your fastest path back to a working install (see Rollback).

Step 2: Upload the New Files

Download the latest version from your CodeCanyon Downloads page, then upload the new files into your WaDesk directory, overwriting the existing application code. You can use your hosting File Manager, FTP/SFTP, or over SSH:

rsync -av --exclude='.env' --exclude='storage/' --exclude='node/node_modules/' /tmp/wadesk-update/ /var/www/wadesk/

Overwrite the application code — app/, config/, database/migrations/, resources/, routes/, public/build/, the node/ bridge source, and root files such as composer.json and config/version.php.

Assets are pre-built. The update package already contains the compiled Vite assets in public/build/, so for most updates you do not need to run composer install or npm run build. Only rebuild if the changelog says new dependencies were added (see Step 4).

What NOT to Overwrite

These contain your data and configuration. Replacing them will break your install or lose your data. Always exclude them when uploading:

• .env — Your database credentials, app key, mail, AI, and payment-gateway keys. Losing this breaks the installation.
• storage/ — Logs, cached files, sessions, and the bundled Node bridge's WhatsApp session/auth data. Overwriting this disconnects every Unofficial API number.
• User uploads in public/ (e.g. uploaded media, logos, and branding assets) — never delete buyer-uploaded files.
• vendor/ and node/node_modules/ — Installed dependencies. Leave them in place unless the changelog tells you to reinstall.

Critical: If your update tool cannot exclude folders, extract the package to a separate directory first and copy only the application code across — do not let .env or storage/ be overwritten.

Step 3: Run Database Migrations

New versions may add or change database tables. Run migrations so the schema matches the new code. Only new migrations run — your existing data is not touched.

VPS / Dedicated Server (SSH):

php artisan migrate --force

Shared Hosting (no SSH): Use your hosting's “PHP / Cron” or terminal tool to run the same command in your application's root directory, or ask your hosting provider's support to run php artisan migrate --force for you.

Do not skip migrations. Running new code against an old schema is the most common cause of post-update errors.

Step 4: Clear Cache and Rebuild Assets

Stale config, route, view, and compiled caches can make new code misbehave. Clear and rebuild them.

VPS / Dedicated Server (SSH):

php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

Shared Hosting (no SSH): Using your File Manager, delete the contents of these folders (keep the folders themselves):

• bootstrap/cache/ — delete all .php files
• storage/framework/cache/data/ — delete all files
• storage/framework/views/ — delete all .php files

Only if the changelog says new dependencies were added, reinstall and rebuild:

composer install --no-dev --optimize-autoloader
npm install
npm run build

Step 5: Restart the Node Bridge

If any workspace uses the Unofficial API engine, restart the bundled Node.js bridge so it runs the new code. Your saved WhatsApp sessions live in storage/ and are not affected by a restart — connected numbers stay connected.

If you run the bridge under PM2:

pm2 restart wadesk-bridge

If you run it under systemd:

sudo systemctl restart wadesk-bridge

Then restart Laravel's queue workers so they pick up the new code as well:

php artisan queue:restart

Cloud API / Twilio only: If no workspace uses the Unofficial API, you can skip the bridge restart — but still run queue:restart.

Step 6: Verify

Confirm the update succeeded by checking the core flows:

• The admin panel and a workspace dashboard both load without errors.
• Connected WhatsApp numbers still show as connected (Unofficial API), or your Cloud API / Twilio sender still sends.
• A test message sends and inbound messages arrive in the Team Inbox.
• Queue jobs are processing (campaigns, scheduled sends).
• The version shown in the admin panel matches the new release.

Never run a real campaign as your test. Use a single test number you control — live workspaces send real WhatsApp messages.

Rollback

If the update causes problems and you need to revert to the previous version:

1. Restore the database:

   mysql -u your_db_user -p your_database < wadesk-backup.sql

2. Restore files: Replace the updated application code with your backed-up copy. Your .env and storage/ were never touched, so leave them as they are.
3. Clear caches:

   php artisan optimize:clear

4. Restart the bridge and queue:

   pm2 restart wadesk-bridge
   php artisan queue:restart

Keep your backup until the new version has been verified in production for a few days.

Important Notes

Critical: Follow these guidelines to avoid data loss and downtime.

• Never delete or overwrite .env — it holds your app key, database credentials, and all API/payment keys.
• Never delete or overwrite storage/ — it holds logs, sessions, and the Node bridge's WhatsApp auth data for every connected number.
• Always run migrations after uploading new files.
• Always clear caches — stale config/route/view caches are a frequent source of post-update bugs.
• Restart the Node bridge and queue workers so long-running processes pick up the new code.
• Check the changelog for breaking changes — some releases require new environment variables or a dependency reinstall. Review the Change Log before every update.