WHMCS Module

1. What it does

The CloudWave SMS integration for WHMCS is a normal addon module. It connects your WHMCS to your CloudWave Bulk SMS account and lets you:

• See your SMS wallet balance and available Sender IDs inside WHMCS.
• Send a one-off SMS to a client, a client group, or a pasted list.
• Run bulk campaigns to a filtered audience (status / group / country / cap), throttled by the WHMCS cron.
• Automate event SMS: new client, invoice created/paid/reminder, order placed/activated, ticket opened/replied, and staff alerts.
• Keep a delivery log of everything sent, with cost and status.

There are two parts, shipped together:

2. Requirements

• WHMCS 8.x (tested on 8.10) running on PHP 7.4 or newer.
• A CloudWave Bulk SMS account — the portal at https://sms.cloudwavebd.com (you sign in there with your WHMCS client login).
• Funds in your portal SMS wallet (top up under Add Funds — bKash or WHMCS invoice).
• WHMCS cron configured and running (needed for bulk campaigns and scheduled sends).
• Outbound HTTPS (cURL) allowed from the WHMCS server to the portal — most hosts allow this by default.

3. Download

Download the module ZIP, then upload the two folders inside it into your WHMCS installation.

cloudwave-whmcs-modules.zip

Contains modules/addons/cloudwave_sms/ and modules/notifications/CloudWaveSms/.

Download ZIP

4. Install the module

1. Unzip the downloadYou will have two folders: cloudwave_sms (the addon module) and CloudWaveSms (the notification provider).
2. Upload the addon modulePut the cloudwave_sms folder in <whmcs>/modules/addons/, so the path is exactly:

   <whmcs>/modules/addons/cloudwave_sms/cloudwave_sms.php
   <whmcs>/modules/addons/cloudwave_sms/hooks.php
   <whmcs>/modules/addons/cloudwave_sms/lib/…
   <whmcs>/modules/addons/cloudwave_sms/views/…

3. Upload the notification providerPut the CloudWaveSms folder in <whmcs>/modules/notifications/:

   <whmcs>/modules/notifications/CloudWaveSms/CloudWaveSms.php

4. Check the file layoutEvery file must be present, including the whole lib/ and views/ sub-folders. A partial upload is the most common cause of a blank module page (the module will tell you which file is missing).

5. Get your API credentials

1. Open the portalGo to https://sms.cloudwavebd.com and sign in (this uses your WHMCS client login).
2. Create a dedicated keyOpen API & Plugins in the sidebar and click Generate API credentials. Use a separate key for WHMCS so you can revoke it later without affecting your website or scripts.
3. Copy both valuesCopy the API Key (starts with cw_) and the API Secret. Keep them safe — the secret is private.
4. Top up if neededUnder Add Funds, add wallet credit (bKash or a WHMCS invoice). A send is only accepted if the balance covers it.

6. Activate & configure

1. ActivateIn WHMCS go to Setup → Addon Modules, find CloudWave SMS and click Activate. Activation creates the five mod_cloudwave_sms_* tables.
2. Access controlStill in Setup → Addon Modules, click Configure (or Access Control) and grant the module to the admin roles that should use it.
3. Enter your settingsOpen the module (Addons → CloudWave SMS → Settings) and fill in the fields below.
4. SaveClick Save, then use Test API connection on the Overview tab.

Settings reference

7. The module screens

8. Bulk campaigns & cron

A bulk campaign is queued immediately and sent progressively, so a large audience never blocks a web request:

1. Audience is resolvedFrom tblclients, one row per recipient is written to the queue table and the message is merged per client.
2. Cron drains the queueEach WHMCS cron run (AfterCronJob) pushes up to Messages per Cron Run.
3. Bodies are packedMessages without merge tags are sent in single API calls of up to Recipients per API Call; personalised bodies go one-per-recipient. Failures retry up to three times.

9. Event automations

Each event maps to a WHMCS hook. Client events message the client's number on file; staff events message the Admin SMS Recipients setting.

Only valid Bangladeshi mobile numbers (017…, 8801…, +8801…) are messaged; a client without one is skipped silently. Each template can be enabled/disabled and reworded on the Templates tab.

Merge tags

Every template supports {company_name}, {whmcs_url}, {date}, {time}, plus:

Unknown tags are stripped before sending, so a client never sees a stray {typo}.

10. Notification provider (optional)

The notification provider lets WHMCS Notification Rules deliver SMS — useful for staff alerts and anything the rule engine fires.

1. Activate itGo to Setup → Staff Management → Notification Providers, find CloudWave SMS and activate it with the same base URL, key and secret. Add optional Fallback Recipients.
2. Add recipients per ruleUnder Notification Rules, open each rule and set the SMS Recipients (one number per line) and an optional Sender ID override.

The provider validates the credentials when you save and warns you if the wallet balance is zero. It works with or without the addon module.

11. Wallet top-ups paid through WHMCS

Besides bKash, your clients can top up their SMS wallet by paying a WHMCS invoice with any gateway enabled in WHMCS. The portal creates the invoice; when WHMCS marks it paid, the wallet is credited automatically.

How it flows

1. Client chooses “Pay via WHMCS”On the portal's Add Funds page the client enters an amount; the portal records a pending top-up.
2. Portal creates an invoiceIt calls the WHMCS API (CreateInvoice) with a line item that contains an SMTOP-<id> reference, then redirects the client to viewinvoice.php.
3. Client paysWith any gateway enabled in WHMCS (card, mobile banking, bank transfer).
4. InvoicePaid hook notifies the portalThe hook finds the SMTOP-<id> marker and POSTs a signed payload to the portal's /whmcs-callback.
5. Wallet creditedThe portal verifies the HMAC signature and credits the wallet. Duplicate callbacks are ignored (idempotent).

One-time setup

1. Create WHMCS API credentialsIn WHMCS: Setup → Staff Management → API Credentials (Config → System → API Credentials). Note the Identifier and Secret.
2. Put them in the portalOn the portal server, set SMS_WHMCS_API_IDENTIFIER and SMS_WHMCS_API_SECRET in config/secrets.php.
3. Install the updated hookMake sure <whmcs>/includes/hooks/cloudwave_sms.php is the version that ships with the module — it contains the InvoicePaid handler. (It is also the file that powers the SSO login button.)
4. Optional: callback secretBy default the portal signs the callback with the SSO secret. To use a separate one, set the same sms_callback_secret in the CloudWave Console addon settings and SMS_WHMCS_CALLBACK_SECRET in the portal.

12. Testing checklist

1. Test API connectionOverview tab → shows your live wallet balance and how many Sender IDs are available.
2. Send a test SMSOverview tab → send to your own mobile. Then check the Log tab for the row.
3. One-off sendSend SMS tab → a client, a group, or pasted numbers.
4. Bulk campaignBulk tab → create a small campaign and press Push now; then confirm it drains on the next cron run.
5. AutomationTemplates tab → enable one event (e.g. Invoice Paid) and trigger it in a test order.
6. Top-up (optional)Behave as a client: Add Funds → Pay via WHMCS → pay the invoice → confirm the wallet is credited.

13. Troubleshooting

14. Upgrade / uninstall

Upgrading

Replace the files in modules/addons/cloudwave_sms/ (and the notification provider) with the new version, then reset OPcache. Settings and data are preserved.

Deactivating

Deactivating in Setup → Addon Modules stops the automations but keeps all tables and settings.

Removing completely

To remove all data, deactivate the module and drop the tables mod_cloudwave_sms_log, mod_cloudwave_sms_queue, mod_cloudwave_sms_batch, mod_cloudwave_sms_templates and mod_cloudwave_sms_optout.