Troubleshooting

Start with the module log

Nearly everything here is diagnosed from one place: Configuration → System Logs in WHMCS, then Module Log on the sidebar. (Prior to WHMCS 8.0 this lived at Utilities → Logs → Module Log.) Every send attempt is recorded there, successful or not, and the failure text is the platform's own words rather than a generic error.

If the log is empty, turn module logging on — WHMCS only records module calls while it is enabled. Enable it, reproduce the problem once, read the newest entries, then toggle module logging back off.

The entries you will care about:

Entry	Means
phone_library_missing	libphonenumber is not installed. Nothing can send. See below.
phone_unresolvable	One recipient's number could not be validated. See below.
api_call_failed	Your platform rejected the send. The text says why.
api_call_attempt_failed	One attempt failed and was retried. Harmless on its own if a success follows.
charset_migration_failed	The utf8mb4 migration could not run. See emoji.

Nothing sends at all

Work through these in order — the first two account for most cases.

1. The API key and its permissions

The key needs sms_send and wa_send. A key without the permission for the service you chose is rejected on every send, and the module log carries the platform's own wording: “This API key doesn't have permission to use this endpoint!”

Check the key under Tools → API Keys in your dashboard. While you are there, confirm your subscription actually includes the service — sms for SMS, whatsapp for WhatsApp. The permission and the service are two separate things and both are required.

Re-paste the key into the Settings tab if you are unsure it saved. The field is deliberately blank on every load, so a blank field is not evidence the key is missing — the help text tells you which state you are in.

2. libphonenumber

Look for phone_library_missing in the module log. One entry per request is written, naming libphonenumber\PhoneNumberUtil.

If it is there, the plugin is refusing to send anything at all, deliberately: without that library a bad number cannot be told from a good one, and a bad number can be delivered to an unrelated subscriber. See Requirements — and in particular, do not run composer require inside your WHMCS root to fix it.

3. Everything else

• Is the template enabled? Each event has its own Enable tick.
• WhatsApp selected but no WhatsApp Account ID? Nothing will send.
• SMS with neither a Device Unique ID nor a Gateway Unique ID? There is nothing to send through.
• Can WHMCS reach your platform install at all? A Transport error in the log means it could not — DNS, an outbound firewall, or a TLS certificate the WHMCS server does not trust.
• Two addons active at once does the opposite — every message twice. If clients report duplicates, look for a second addon in Addon Modules from an older prefix.

Then send one message from the Send Message tab. It reports the failure on screen, in words, which is faster than reading logs.

One particular client never receives anything

Everyone else gets their messages; one client never does. Look for phone_unresolvable in the module log, with that client's number in it.

The number stored on their WHMCS profile could not be turned into a valid international number, so the plugin refused to send rather than guess. A guess here does not fail harmlessly — it delivers that client's invoice, service password or ticket reply to whichever real subscriber happens to hold the number that was guessed. Refusing is recoverable; that is not.

Usual causes, in the order worth checking:

• The country on the client's profile is wrong or empty. A national number is interpreted against the client's country, so the wrong country makes a perfectly good number unresolvable.
• The number is not a real number. Digits transposed, one missing, a landline typed where a mobile was meant, or a placeholder like 000000000.
• Extra text in the field — an extension, a second number, a note. Spaces, brackets and dashes are fine; anything that is not part of the number is not.

Fix the client's profile in WHMCS — country first, then the number — and send them a test from the Send Message tab. Storing the number in full international form, +639171234567, resolves it regardless of the country field.

An emoji will not save in a template

You paste an emoji into a template, press Save, and the save fails. This only happens on installs upgraded from 3.9: those tables were created with an older character set that cannot store emoji at all, and the database rejects the write outright.

The fix is to reactivate the addon. Go to Configuration → System Settings → Addon Modules, deactivate and activate it again — that runs the migration which converts both tables to utf8mb4. From 4.0 onwards deactivating keeps your settings and templates, so nothing is lost.

If emoji still will not save afterwards, check the module log for charset_migration_failed. That means your host does not permit the ALTER the migration needs. Everything else works; ask your host to run the conversion, or write the templates without emoji.

The addon does not appear in the Addons menu

Almost always the Access Control tick. Activating an addon in WHMCS does not by itself grant your admin role access to it — go back to Configuration → System Settings → Addon Modules, tick your own role and save.

If it is not listed on that page at all, the files are in the wrong place. You should have modules/addons/<prefix>/<prefix>.php, with the PHP file's name matching its folder's name exactly.

The download does not produce a ZIP

The Plugin Prefix is the first thing to check. It must start with a lowercase letter and contain only lowercase letters, digits and underscores — anything else is refused, with a generic error that does not say which field caused it. See the prefix rule.

If the button itself is missing, remember it lives on the dashboard's Overview page only, under Plugins in the header. Reload the page if you have just installed the plugin.

The domain renewal reminder never fires

It is the only template driven by the WHMCS daily cron rather than by an event, so it is also the only one that can be silent while everything else works.

• Confirm the WHMCS cron is running — Configuration → System Health.
• Days Before is an exact match, not a window. At 15, a domain expiring in 14 days is already past its notification and will not get one.
• Only domains with status Active are considered.
• The client needs a phone number on their profile; the skip is recorded in the module log.

Invoice payment reminders never arrive

The other invoice messages work, but the four reminders never do. They are the templates that do not fire on their own: they ride on WHMCS's own invoice reminder automation.

• Check Automation Settings in WHMCS. If invoice reminders are switched off there, or their day counts are set so they never come due, there is no reminder for the addon to accompany.
• Confirm the WHMCS cron is running — the reminders are sent by it.
• In the module log, look for InvoicePaymentReminder_type_seen. It is written every time WHMCS sends a reminder, and it records which stage WHMCS said it was. Its absence means WHMCS is not sending reminders at all — the problem is on the WHMCS side, not here.

Clients receive some messages twice

Two addons are active. Changing the Plugin Prefix produces a second, separate addon rather than replacing the first, and both listen for the same WHMCS events. Deactivate the one you no longer want at Configuration → System Settings → Addon Modules — from 4.0 onwards that keeps your settings and templates, which both addons share.

A template is listed several times

Left over from an older version, whose activation added a fresh copy of all 28 templates every time it ran. Deactivate and activate the addon once on 4.0 or newer: the duplicates are removed and the oldest copy of each — the one you have been editing — is the one kept.

“Your session expired. Please try again.”

The page was open longer than your WHMCS admin session lasted, so the form was rejected rather than accepted from an unknown source. Nothing was saved and nothing was sent. Reload the page and do it again.