Getting started

Upgrading from 3.9

Replace the module files first. Only then touch Addon Modules. The instinctive order — deactivate, then upload — destroys your data.

Why the order matters

WHMCS runs the deactivate routine from whatever module files are on disk at that moment. 3.9's routine DROP TABLEs both plugin tables. 4.0's keeps them — but it cannot help if 3.9 is the version still on disk when you press Deactivate.

So the deactivate step is safe only after the files have been replaced. Do it the other way round and you lose the API key and all 28 templates before the new version ever runs.

Do this

  1. Back the two tables up first:

    mysqldump -u <user> -p <whmcs_db> mod_zxmessaging_settings mod_zxmessaging_templates > zxmessaging-backup.sql
  2. Upload the new module files over the existing ones, replacing them. Leave the addon activated while you do this.
  3. Now go to Configuration → System Settings → Addon Modules (prior to WHMCS 8.0, Setup → Addon Modules), deactivate the addon, and activate it again. That runs the new version's migration, which upgrades the tables in place and keeps everything you own.

Never

  • Never deactivate while 3.9 is still the version on disk.
  • Never deactivate after rolling back to 3.9. Rolling back is otherwise safe — it is the deactivate that destroys the tables, not the rollback.

Either mistake loses the API key and resets all 28 templates to their defaults. Restore from the dump in step 1 if it happens.

Getting the new files

The module you upload in step 2 is generated, exactly as it was for 3.9 — install the new plugin into your dashboard, then download the addon from the Plugins button on your Overview page. See Installation.

Use the same Plugin Prefix you are already running. A different prefix does not replace the old addon — it produces a second, separate one, and you would then have to deactivate the 3.9 addon to stop it duplicating every message. That deactivate is precisely the one that drops your tables.

What the reactivation actually does

The activation is a migration, not a reinstall. In order, it:

  • creates either table if it is missing;
  • converts both tables to utf8mb4, which is what lets emoji be saved — 3.9 created them with a character set that rejects emoji outright;
  • removes duplicate rows an older activation left behind, keeping the oldest copy of each — the one you have been editing;
  • adds any template that is missing;
  • refreshes each existing template's variable list and description.

Your wording, your Enable toggles, your Days Before value and your admin phone numbers are not touched. Only the variable list and the description are refreshed, because those two describe how the message is filled in rather than what it says — an out-of-date variable list would substitute values into the wrong placeholders.

Because of that, activating is safe to repeat. If you are ever unsure whether the migration ran, deactivate and activate once more.

After upgrading

  • Open the Settings tab and confirm the API key is still there. The field is blank by design and should read “A key is already saved”; if it does not, the key is gone — restore your dump.
  • Check both template tabs list each template once. Duplicates from an older install are cleaned up by the reactivation.
  • Send one message from Send Message to confirm sending still works.
  • If the charset conversion could not run — a host that forbids ALTER — the plugin still works, but emoji cannot be stored, and the reason is in Configuration → System Logs → Module Log as charset_migration_failed.