Getting started

Installation

Six steps, in two systems. If you have not read How it works, do that first — it explains why the file you upload to WHMCS is not the file you downloaded.

Upgrading from 3.9? Stop here and read Upgrading from 3.9 instead. The order of the WHMCS steps is different, and the instinctive order deletes your data.

1. Install the plugin into your dashboard

  1. Go to Admin Panel → Plugins.
  2. Click Add Plugin, top right.
  3. Choose whmcs-integration.zip from your download and submit.
  4. It appears in the plugin list, with its version alongside it.

2. Fill in the plugin's options

On the plugin's row, click the gear button — Edit plugin options. Five fields, all required:

FieldWhat it is
Plugin Prefix The addon's folder name inside WHMCS, and the prefix of every function in it. Read the rule below before typing one.
Plugin Name What the addon is called in the WHMCS admin — the name you will look for under Addon Modules and in the Addons menu.
Plugin Description One line, shown beneath the name in the WHMCS addon list.
Plugin Long Description A longer description, stored in the addon's manifest.
Author Name You, or your company. Shown as the addon's author in WHMCS.

All five are yours to choose, and they are what make the addon appear in WHMCS under your own branding. Save when you are done.

The prefix rule

The prefix becomes PHP function names in the generated module — a prefix of my_prefix produces my_prefix_config(), my_prefix_activate() and so on. So it is restricted to what PHP accepts as part of a function name:

  • It must start with a lowercase letter.
  • After that, only lowercase letters, digits and underscores.
  • No capitals, no spaces, no hyphens, no dots, nothing else.

So hostmsg, acme_sms and notify2 are fine; Acme SMS, acme-sms, 2notify and acme.sms are not.

A prefix outside that character set is refused at download time, with a generic error and no explanation of which field caused it. If the download fails and you cannot see why, the prefix is the first thing to check. The refusal is deliberate: an invalid prefix would produce a module PHP cannot parse, and the failure would only show up later, inside WHMCS.

3. Download the generated addon

  1. Go to your dashboard's Overview page — the front page you land on when you sign in.
  2. Click the Plugins button in the header, top right.
  3. A Plugin Downloads dialog opens. Click the WHMCS button inside it.
  4. A ZIP downloads, named after your prefix — my_prefix.zip for a prefix of my_prefix.

The ZIP is built fresh each time you click, from whatever the plugin's options say at that moment. Change a name or description later and simply download again.

The Plugins button only appears on the Overview page, and only once the plugin is installed. If it is missing, reload the page — it is added by a script that loads with the dashboard.

4. Put the addon into WHMCS

  1. Unzip the download. Inside is a single folder named after your prefix.
  2. Upload that whole folder into your WHMCS installation's modules/addons/ directory.
  3. You should end up with, for example, modules/addons/my_prefix/my_prefix.php. If the PHP file's name does not match its folder's name, the upload went wrong — WHMCS will not run it.

5. Activate it

  1. In WHMCS, go to Configuration → System Settings → Addon Modules (prior to WHMCS 8.0, Setup → Addon Modules).
  2. Find the addon under the Plugin Name you chose and click Activate.
  3. Tick your own admin role under Access Control and save.

Activating creates the plugin's two tables and seeds all 28 message templates. It is safe to repeat: activating again never duplicates templates and never discards wording you have edited.

If you skip the Access Control tick, the addon activates cleanly and then never appears in the Addons menu. That looks exactly like a failed install and is not one.

6. Configure and test

  1. Open the addon from the WHMCS Addons menu.
  2. Fill in the Settings tab — see Configuration.
  3. Send yourself one message from the Send Message tab. That single test proves the API key, the permissions, the sending service and libphonenumber all at once.

Only then go through Message templates and enable the events you actually want.

Changing the prefix later

A different prefix means a different addon: a new folder, new function names, a new row in Addon Modules. The old one does not become the new one.

Never leave two of them active at once. Both would listen for the same WHMCS events and both would send, so every client receives every notification twice. Deactivate the old addon before activating the new one. Deactivating keeps your settings and templates — both addons read the same two tables — so nothing is lost in the swap.